Installing Cloud Native Binding Support Function

2 Installing Cloud Native Binding Support Function

This chapter describes how to install Cloud Native Binding Support Function (BSF) on a cloud native environment.

This chapter contains the following:

Pre-Installation Tasks

Prior to installing the BSF, perform the following tasks:

Checking the Software Requirements

The following software must be installed before installing Binding Support Function (BSF):

Note:

In this release, BSF supports Oracle Communications Cloud Native Environment (OCCNE) 1.5.

To check the OCCNE version, run the following command:

echo $OCCNE_VERSION

Software	Version
Kubernetes	v1.16.7
HELM	v3.0

To check the current helms and Kubernetes version installed in the CNE, run the following commands:

kubectl version

helm3 version

The following table summarizes additional software that may be needed depending on the requirement of the services:

Software	App Version	Notes
elasticsearch	7.6.1	Required for Logging
elastic-curator	2.0.2	Required for Logging
elastic-exporter	1.1.2	Required for Logging
logs	2.7.0	Required for Logging
kibana	7.6.1	Required for Logging
grafana	5.0.5	Required for Metrics
prometheus	11.0.2	Required for Metrics
prometheus-node-exporter	1.9.0	Required for Metrics
metallb	0.12.0	Required for External IP
metrics-server	2.10.0	Required for Metric Server
tracer	0.13.3	Required for Tracing

Note:

Software, listed in the table given above, are available if the BSF is deployed in the Oracle Communications Cloud Native Environment (OCCNE). If you are deploying BSF in any other environment, the required software must be installed before installing BSF. To check the installed software items, run:

helm ls

Some of the systems may need to use helm command with admin.conf file. For example:

helm --kubeconfig admin.conf

Note:

If you are using Network Repository Function (NRF), install it before proceeding with the BSF installation. BSF 1.5.1 supports NRF 1.8.

Checking the Environment Setup

Note:

This section is applicable only when the Binding Support Function (BSF) is deployed in the environment, other than OCCNE.

Network access

The Kubernetes cluster hosts must have network access to:

Local helm repository, where the BSF helm charts are available.
To check if the Kubernetes cluster hosts have network access to the local helm repository, run the following command:
```
helm repo update
```
Note:
Some of the systems may need to use helm command with admin.conf file. For example:
```
helm --kubeconfig admin.conf
```
Local docker image repository, where the BSF images are available.
To check if the Kubernetes cluster hosts have network access to the local docker image repository, run the following command to pull any image with tag name:
```
docker pull docker-repo/image-name:image-tag
```
where:
docker-repo is the IP address or host name of the repository.

image-name is the docker image name.

image-tag is the tag the image used for the BSF pod.

Note:

All the kubectl and helm related commands that are used in this guide must be executed on a system depending on the infrastructure/deployment. It could be a client machine, such as, a VM, server, local desktop, and so on.

Client Machine Requirements

This section lists the client machine requirements where the deployment commands are executed.

It should have network access to the helm repository and docker image repository.
It should have network access to the Kubernetes cluster.
It should have necessary environment settings to run the kubectl and docker commands. The environment should have privileges to create namespace in the Kubernetes cluster.
It should have helm client installed with the push plugin. The environment should be configured so that the helm install command deploys the software in the Kubernetes cluster.

Server or Space Requirements

For information on the server or space requirements, see the Oracle Communications Cloud Native Environment (OCCNE) Installation Guide.

Secret File Requirement

For enabling HTTPs on Ingress/Egress gateway the following certificates and pem files has to be created before creating secret files for keys:

ECDSA private Key and CA signed ECDSA Certificate (if initialAlgorithm: ES256)
RSA private key and CA signed RSA Certificate (if initialAlgorithm: RSA256)
TrustStore password file
KeyStore password file
CA signed ECDSA certificate

Installation Procedure

This section describes the tasks that you need to perform, in the given sequence, to be able to install Binding Support Function (BSF).

The installation procedure consists of following steps:

Downloading BSF Package

This section provides information on how to download Binding Support Function (BSF) package.

To download the BSF package from MOS:

Login to My Oracle Support with your credentials.
Select Patches and Updates tab to locate the patch.
In Patch Search window, click Product or Family (Advanced).
Enter Oracle Communications Cloud Native Core - 5G in Product field, select Oracle Communications Cloud Native Core Binding Support Function 1.5.0.0.0 from Release drop-down.
Click on Search. The Patch Advanced Search Results displays a list of releases.
Select the required patch from the search results. The Patch Details window opens.
Click on Download. File Download window appears.
Click on the zip file to download the package. Package is named as follows:
ReleaseName-pkg-Releasenumber.tgz

where:

ReleaseName is used to track this installation instance.
Releasenumber is the release number.
For example,ocbsf-pkg-1.5.1.0.0.tgz

Pushing the Images to Customer Docker Registry

This section describes how to push the images to customer docker registry.

To Push the images to customer docker resgistry, perform the following steps:

Untar the Binding Support Function (BSF) package file to get BSF docker image tar file.
tar -xvzf ocbsf-pkg-1.5.1.0.0.tgz
The directory consists of the following:
- BSF Docker Images File:
  ocbsf-images-1.5.1.tar
- Helm File:
  ocbsf-1.5.1.tgz
- Readme txt File:
  Readme.txt
- Checksum for Helm chart tgz file:
  ocbsf-1.5.1.tgz.sha256
- Checksum for images' tgz file:
  ocbsf-images-1.5.1.tar.sha256
Load the ocbsf-images-1.5.1.tar file into the Docker system
```
docker load --input /IMAGE_PATH/ocbsf-images-1.5.1.tar
```
To verify that the image is loaded correctly, enter the following command:
```
docker images
```
For more information on docker images available in BSF, see Docker Images.

Run the following set of commands to create a new tag for each imported image and push the image to the customer docker registry:

docker tag ocbsf/oc-config-mgmt:1.8.0 CUSTOMER_REPO/oc-config-mgmt:1.8.0
docker push CUSTOMER_REPO/oc-config-mgmt:1.8.0

docker tag ocbsf/oc-config-server:1.8.0 CUSTOMER_REPO/oc-config-server:1.8.0
docker push CUSTOMER_REPO/oc-config-server:1.8.0

docker tag ocbsf/oc-diam-connector:1.8.1 CUSTOMER_REPO/oc-diam-connector:1.8.1
docker push CUSTOMER_REPO/oc-diam-connector:1.8.1

docker tag ocbsf/configurationupdate:1.4.0 CUSTOMER_REPO/configurationupdate:1.4.0
docker push CUSTOMER_REPO/configurationupdate:1.4.0

docker tag ocbsf/oc-app-info:1.8.0 CUSTOMER_REPO/oc-app-info:1.8.0
docker push CUSTOMER_REPO/oc-app-info:1.8.0

docker tag ocbsf/ocingress_gateway:1.8.2 CUSTOMER_REPO/ocingress_gateway:1.8.2
docker push CUSTOMER_REPO/ocingress_gateway:1.8.2

docker tag ocbsf/ocegress_gateway:1.8.2 CUSTOMER_REPO/ocegress_gateway:1.8.2
docker push CUSTOMER_REPO/ocegress_gateway:1.8.2

docker tag ocbsf/oc-diam-gateway:1.8.1 CUSTOMER_REPO/oc-diam-gateway:1.8.1
docker push CUSTOMER_REPO/oc-diam-gateway:1.8.1

docker tag ocbsf/oc-bsf-management:1.5.1 CUSTOMER_REPO/oc-bsf-management:1.5.1
docker push CUSTOMER_REPO/oc-bsf-management:1.5.1

docker tag ocbsf/oc-query:1.8.1 CUSTOMER_REPO/oc-query:1.8.1
docker push CUSTOMER_REPO/oc-query:1.8.1

docker tag ocbsf/oc-perf-info:1.8.0 CUSTOMER_REPO/oc-perf-info:1.8.0
docker push CUSTOMER_REPO/oc-perf-info:1.8.0

docker tag ocbsf/nrf-client:1.3.0 CUSTOMER_REPO/nrf-client:1.3.0
docker push CUSTOMER_REPO/nrf-client:1.3.0

docker tag ocbsf/oc-readiness-detector:1.5.1 CUSTOMER_REPO/oc-readiness-detector:1.5.1
docker push CUSTOMER_REPO/oc-readiness-detector:1.5.1

docker tag ocbsf/configurationinit:1.4.0 CUSTOMER_REPO/configurationinit:1.4.0
docker push CUSTOMER_REPO/configurationinit:1.4.0

where:

CUSTOMER_REPO is the docker registry address having Port Number, if registry has port attached.

Note:

For OCCNE, copy the package to bastion server and use localhost:5000 as CUSTOMER_REPO to tag the images and push to bastion docker registry.

Note:

You may need to configure the Docker certificate before the push command to access customer registry via HTTPS, otherwise, docker push command may fail.

Configuring Database, Creating Users, and Granting Permissions

This section describes how to configure database, create users, and grant permissions to the users.

Configure Database, Create Users, and Grant Permissions

Perform the following steps to configure MySQL database for different microservices:

Login to the server where the ssh keys are stored and SQL nodes are accessible.
Connect to the SQL nodes.
Log into the database as a root user.
Create database for different microservices by running the following commands:
```
CREATE DATABASE IF NOT EXISTS ocbsf_config_server_<identifier>;
CREATE DATABASE IF NOT EXISTS ocbsf_release_<identifier>;
```

Create database for BSF management service:

CREATE DATABASE IF NOT EXISTS ocpm_bsf_<Identifier>;
  
CREATE TABLE IF NOT EXISTS ocpm_bsf_<Identifier>.pcf_binding (
  binding_id binary(16) not null,
  ipv4_addr varchar(64),
  ip_domain varchar(128),
  ipv6_prefix varchar(64),
  mac_addr_48 varchar(64),
  dnn varchar(128),
  supi varchar(64),
  gpsi varchar(64),
  snssai_sd varchar(64),
  snssai_sst integer,
  created_date_time datetime(6) not null,
  json_content longblob not null,
  primary key (binding_id),
  key idx_created_date_time (created_date_time),
  key idx_ipv4Addr (ipv4_addr, created_date_time),
  key idx_ipv6Prefix (ipv6_prefix, created_date_time),
  key idx_macAddr48 (mac_addr_48, created_date_time),
  key idx_supi (supi, created_date_time),
  key idx_gpsi (gpsi, created_date_time)
);

Note:

The script given above uses the default database name "ocpm_bsf". You may replace the default name with custom database name wherever applicable.

Create an admin user and grant all the necessary permissions by running the following set of commands:

CREATE USER 'username'@'%' IDENTIFIED BY 'password';

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, REFERENCES, INDEX ON bsf_config_server_<Identifier>.* TO 'username'@'%';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, REFERENCES, INDEX ON bsf_release_<Identifier>.* TO 'username'@'%';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, REFERENCES, INDEX ON ocpm_bsf_<Identifier>.* TO 'username'@'%';
FLUSH PRIVILEGES;

where

username is the username and password is the password for MYSQL admin user.

In the below example, "bsfadminusr" is used as username, "bsfadminpasswd" is used as password. Here, all permissions are being granted to "bsfadminusr".

CREATE USER 'bsfadminusr'@'%' IDENTIFIED BY 'bsfadminpasswd';

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, REFERENCES, INDEX ON bsf_config_server_<Identifier>.* TO 'bsfadminusr'@'%';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, REFERENCES, INDEX ON bsf_release_<Identifier>.* TO 'bsfadminusr'@'%';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, REFERENCES, INDEX ON ocpm_bsf_<Identifier>.* TO 'bsfadminusr'@'%';
FLUSH PRIVILEGES;

Create an application user and grant all the necessary permissions by running the following set of commands:
```
CREATE USER 'username'@'%' IDENTIFIED BY 'password';
```
```
GRANT SELECT, INSERT, UPDATE, DELETE ON bsf_config_server_<Identifier>.* TO 'username'@'%';
GRANT SELECT, INSERT, UPDATE, DELETE ON bsf_release_<Identifier>.* TO 'username'@'%';
GRANT SELECT, INSERT, UPDATE, DELETE ON ocpm_bsf_<Identifier>.* TO 'username'@'%';
FLUSH PRIVILEGES;
```
where

username is the username and password is the password for MYSQL application user.
In the below example, "bsfusr" is used as username, "bsfpasswd" is used as password. Here, all permissions are being granted to "bsfusr".
```
CREATE USER 'bsfusr'@'%' IDENTIFIED BY 'bsfpasswd';
```
```
GRANT SELECT, INSERT, UPDATE, DELETE ON bsf_config_server_<Identifier>.* TO 'bsfusr'@'%';
GRANT SELECT, INSERT, UPDATE, DELETE ON bsf_release_<Identifier>.* TO 'bsfusr'@'%';
GRANT SELECT, INSERT, UPDATE, DELETE ON ocpm_bsf_<Identifier>.* TO 'bsfusr'@'%';
FLUSH PRIVILEGES;
```
Note:
The database name is specified in the envMysqlDatabase parameter for respective services in the custom-value.yaml file.

Note:
It is recommended to use unique database name when multiple instances of Binding Support Function (BSF) are deployed in the network as they share the same data tier (MySQL cluster).

Verify Permissions

To verify that admin user and application user have all the permissions, you can run the following command:

show grants for username

where username is the name of the admin or application user.

For example:

show grants for bsfadminusr;
show grants for bsfusr;

Then, exit from database and logout from MYSQL node.

Create Namespace

If a namespace does not exist, create namespace by running the following command:

kubectl create namespace release_namespace

where:

release_namespace is the deployment BSF namespace used by helm command.

For example, running the following command creates ocbsf namespace:

kubectl create namespace ocbsf

Create Kubernetes secret

Create a kubernetes secret for an admin user and an application user.

To create a kubernetes secret for storing database username and password for these users:

Create a yaml file (yaml_file_name1) with the application user's username and password with the syntax shown below:
```
apiVersion: v1
kind: Secret
metadata:
  name: bsf-db-pass
type: Opaque
data:
  mysql-username: YnNmdXNy
  mysql-password: YnNmcGFzc3dk
```
Note:
The values for mysql-username and mysql-password should be base64 encoded.
Create a yaml file (yaml_file_name2) with the admin user's username and password with the syntax shown below:
```
apiVersion: v1
kind: Secret
metadata:
  name: bsf-admin-db-pass
type: Opaque
data:
  mysql-username: YnNmcHJpdmlsZWdlZHVzcg==
  mysql-password: YnNmcHJpdmlsZWdlZHBhc3N3ZA==
```
Note:
The values for mysql-username and mysql-password should be base64 encoded.
Run the following commands to add the kubernetes secrets in a namespace:
```
kubectl create -f yaml_file_name1 -n release_namespace
kubectl create -f yaml_file_name2 -n release_namespace
```
where:
release_namespace is the deployment namespace used by the helm command.

yaml_file_name1 is the name of the yaml file that is created in step 1.

yaml_file_name2 is the name of the yaml file that is created in step 2.
For example: In the below example "application.yaml" is used as yaml file name created in step 1 and "admin.yaml" is used as a file name created in step 2, and "ocbsf" is used as a namespace:
```
kubectl create -f application.yaml -n ocbsf
```
```
kubectl create -f admin.yaml -n ocbsf
```

Installing BSF Package

This section describes how to install Binding Support Function (BSF) package.

Customize the custom-values.yaml file. For more information, see Customizing Binding Support Function.

Note:
The values of the parameters mentioned in the custom values yaml file overrides the default values specified in the helm chart. If the envMysqlDatabase parameter is modified, then you must modify the configDbName parameter with the same value.
Note:
The URL syntax for perf-info must be in the correct syntax, otherwise it keeps on restarting. The following is an example of URL for bastion server:
```
perf-info:
  configmapPerformance:
    prometheus: http://occne-prometheus-server.occne-infra.svc
```
Caution:
When you run the install command, make sure that you do not exit from helm install command manually. After running the helm install command, it takes some time to install all the services. In the meantime, you must not press "ctrl+c" to come out from helm install command as it leads to some anomalous behavior.
Install BSF using Helm2:
```
helm install <helm-chart>  --name <release-name> --namespace <release-namespace> -f <custom_file> --atomic --timeout 600
```
Install BSF using Helm3:
```
helm install -f <custom_file> <release-name> <helm-chart> --namespace <release-namespace> --atomic --timeout 10m
```
where:
helm-chartis the location of the helm chart extracted from ocbsf-pkg-1.5.1.tgz file

release_name is the release name used by helm command. The maximum allowed length is 63 characters.

release_namespace is the deployment namespace used by helm command.

custom_file is the name of the custom values yaml file (including location).
For example:
```
helm install /home/cloud-user/bsf-1.5.1.tgz --name ocbsf --namespace ocbsf -f ocbsf-custom-values-1.5.1.yaml --atomic
```
Parameters in helm install command:
- atomic: If this parameter is set, installation process purges chart on failure. The --wait flag will be set automatically.
- timeout duration (optional): If not specified default value will be 300 (300 seconds) in Helm2 and 5m (5 minutes) in Helm3. It specifies the time to wait for any individual kubernetes operation (like Jobs for hooks). The default value is 5m0s. If the helm install command fails at any point to create a kubernetes object, it will internally call the purge to delete after timeout value (default: 300s).
  
  Note:
  Timeout value is not for the overall install, but for automatic purge on installation failure.

Verifying BSF Installation

This section describes how to verify if Binding Support function (BSF) is installed successfully.

To verify installation while running the install command, run the following command:

watch kubectl get jobs,pods -n release_namespace

Press "Ctrl+C" to exit watch mode. Make sure to run the watch command on a different terminal.

helm status release_name -n release_namespace

Check Installation Status

To check the installation status, run any of the following commands:

For Helm2:

helm ls release_name

For example:

helm ls ocbsf

For Helm3:

helm3 ls release_name -n <release-namespace>

You should see the status as DEPLOYED if the deployment is successful.

To get status of jobs and pods, run the following command:

kubectl get jobs,pods -n release_namespace

For example:

kubectl get pod -n ocbsf

You should see the status as Running for all the pods if the deployment is successful.

Note:

If the installation is not successful or you do not see the status as Running for all the pods, perform the troubleshooting steps mentioned under Troubleshooting Binding Support Function.