4 Upgrading BSF

This chapter provides information about upgrading Oracle Communications Cloud Native Core, Binding Support Function (BSF) deployment to the latest release.

4.1 Supported Upgrade Paths

The following table lists the supported upgrade paths for BSF:

Source Release Target Release
23.4.x 23.4.6
23.2.x 23.4.6

Note:

BSF must be upgraded before upgrading cnDBTier.

.

4.2 Upgrade Strategy

BSF supports in-service upgrade. The supported upgrade strategy is RollingUpdate. The rolling update strategy is a gradual process that allows you to update your Kubernetes system with only a minor effect on performance and no downtime. The advantage of the rolling update strategy is that the update is applied Pod-by-Pod so the greater system can remain active.

Following engineering configuration parameters are used to define upgrade strategy:
  • upgradeStrategy parameter indicates the update strategy used in BSF.
  • maxUnavailable parameter determines the maximum number of pods that can be unavailable during upgrade.

Table 4-1 Predefined Upgrade Strategy Value

MicroService Upgrade Value (maxUnavailabe)
Alternate Route Service 50%
bsf-management-service 50%
Diameter Gateway 50%
Egress Gateway 50%
Ingress Gateway 50%
NRF Client NF Management 50%
Perf-Info 50%
App-info 50%
Query Service 50%
CM Service 50%
Config Server 50%
Audit Service 50%

4.3 Preupgrade Tasks

This section provides information about preupgrade tasks to be performed before upgrading BSF.

  1. Backup the current custom-values.yaml file.
  2. Update the new custom_values.yaml file for target BSF release. For details on customizing this file, see Customizing BSF.
  3. Before starting the upgrade, take a manual backup of BSF REST based configuration. This helps if preupgrade data has to be restored.

    Note:

    For Rest API configuration details, see Oracle Communications Cloud Native Core, Binding Support Function REST Specification Guide.
  4. Before upgrading, perform sanity check using Helm test. See the Performing Helm Test section for the Helm test procedure.
  5. Install or upgrade the network policies, if applicable. For more information, see Configuring Network Policies.

Note:

It is recommended to perform BSF upgrade in a specific order. For more information about the upgrade order, see Oracle Communications Cloud Native Core, Solution Upgrade Guide.

Before starting the procedure to upgrade Binding Support Function (BSF), perform the following tasks:
  • Since Diameter Connector is removed from BSF, perform any of the following methods to prepare system for upgrade with functional Diameter Connector:

    One-step Upgrade: Set the value of diamConnectorEnable as false in the custom values yaml file and then perform the upgrade. This method is a site isolation upgrade and may have an impact on traffic.

    OR

    Two-step Upgrade:
    1. Set the value of the diamConnectorEnable parameter as true in the custom values yaml file and perform the upgrade.
    2. After a successful upgrade, change the value of diamConnectorEnable to false in the same custom values yaml file and rerun the upgrade command.

      Running the same upgrade command twice by changing the diamConnectorEnable parameter values does not impact the traffic.

Perform either of the following scenarios for enabling or disabling OpenTelemetry as per the requirement, when upgrading from 23.2.x to 23.4.6:
  • When tracing is enabled in 23.2.x
    • Stay Enabled
      1. Ensure that envJaegerCollectorHost is enabled.

        Note:

        Jaeger Collector service must be up and running inside OCCNE-Infra, with port specified in values.yaml as open.
      2. Ensure that following configuration has been enabled in 23.4.6 in custom_values.yaml.
        
envJaegerCollectorHost: 'occne-tracer-jaeger-collector.occne-infra'
envJaegerCollectorPort: 4318 -> Make sure this matches with OCCNE-INFRA jaeger collector service port.          
tracing:
  tracingEnabled: 'true'
  tracingSamplerRatio: 0.001
  tracingJdbcEnabled: 'true'
  tracingLogsEnabled: 'false'
      3. Delete or ignore the old configuration.
    • Disable
      To disable OpenTelemetry update the following parameter in the custom_values.yaml:
      tracing:
  tracingEnabled: 'false'
  • When tracing is disabled in 23.2.x
    • Stay Enabled
      1. Ensure that envJaegerCollectorHost is enabled.

        Note:

        Jaeger Collector service must be up and running inside OCCNE-Infra, with port specified in values.yaml as open.
      2. Ensure that following configuration has been enabled in 23.4.6 in custom_values.yaml.
        
envJaegerCollectorHost: 'occne-tracer-jaeger-collector.occne-infra'
envJaegerCollectorPort: 4318 -> Make sure this matches with OCCNE-INFRA jaeger collector service port.          
tracing:
  tracingEnabled: 'true'
  tracingSamplerRatio: 0.001
  tracingJdbcEnabled: 'true'
  tracingLogsEnabled: 'false'
    • Disable
      To disable OpenTelemetry update the following parameter in the custom_values.yaml:
      tracing:
  tracingEnabled: 'false'

4.4 Upgrade Tasks

This section includes information about upgrading an existing Binding Support Function (BSF) deployment.

Helm Upgrade

Upgrading an existing deployment replaces the running containers and pods with new containers and pods. If there is no change in the pod configuration, it is not replaced. Unless there is a change in the service configuration of a microservice, the service endpoints remain unchanged.

Upgrade Procedure

Caution:

  • Stop the provisioning traffic before you start the upgrade procedure.
  • Do not perform any configuration changes during the upgrade.
  • Do not exit from helm upgrade command manually. After running the helm upgrade command, it takes some time (depending upon the number of pods to upgrade) to upgrade all the services. In the meantime, you must not press "ctrl+c" to come out from helm upgrade command. It may lead to anomalous behavior.
  1. Unzip the release package file to the system where you want to deploy BSF. The BSF release package is named using the following convention:

    ReleaseName-pkg-Releasenumber.tgz

    where, ReleaseName is the name used to track a particular installation instance and

    Releasenumber is the release number.

    For BSF 23.4.6, the release package file name is ocbsf-pkg23.4.6.0.0.tgz.

    Note:

    For information on how to download the package from My Oracle Support (MOS), see Downloading BSF package.
  2. Untar the BSF package file to get the docker image tar file:
    tar -xvzf ReleaseName-pkg-ReleaseNumber.tgz

    For Example: 

    tar -xvzf ocbsf-pkg-23.4.6.0.0.tgz
    The directory consists of the following:
    • ocbsf-images-23.4.6.tar - BSF Docker Images File
    • ocbsf-23.4.6.tgz - Helm Charts
    • Readme.txt - Readme txt file
    • ocbsf-23.4.6.tgz.sha256 - Checksum for Helm chart tgz file
    • ocbsf-images-23.4.6.tar.sha256 - Checksum for images tgz file
  3. Load and Push the Images to Customer Docker Registry. See Pushing the Images to Customer Docker Registry.
  4. Modify the required custom-values.yaml file for the target BSF release. To learn how to customize the file or any specific parameters, see Customizing BSF.

    Note:

    The values of the parameters mentioned in the custom values yaml file overrides the defaults values specified in the helm chart. If the envMysqlDatabase parameter is modified, then you should modify the configDbName parameter with the same value.
    1. Upgrade BSF using Helm:
      helm upgrade -n <release-namespace> <helm-chart> -f <custom-file>

      Example:

      helm upgrade -n ocbsf ocbsf-23.4.6.tgz -f ocbsf-23.4.6-custom-values.yaml
    where:

    helm_chart is the location of the helm chart extracted from ocbsf-23.4.6.tgz file

    release_name is the release name used by helm command.

    release_namespace is the deployment namespace used by helm command.

    custom_file - is the name of the custom values yaml file.

    Optional parameters that can be used in the helm install command:
    • atomic:If this parameter is set, installation process purges chart on failure. The --wait flag will be set automatically.
    • wait: If this parameter is set, installation process will wait until all pods, PVCs, Services, and minimum number of pods of a deployment, StatefulSet, or ReplicaSet are in a ready state before marking the release as successful. It will wait for as long as --timeout.
    • timout duration: If not specified, default value will be 300 (300 seconds) in Helm. It specifies the time to wait for any individual Kubernetes operation (like Jobs for hooks). If the helm install command fails at any point to create a Kubernetes object, it will internally call the purge to delete after the timeout value. Here, the timeout value is not for overall installation, but for automatic purge on installation failure.

    Note:

    It is recommended not to use --wait and --atomic parameters along with helm upgrade as this might result in upgrade failure.
  6. Run the following command to check the status of jobs and pods:
    kubectl get jobs,pods -n release_namespace
    For example: 
    kubectl get jobs,pods -n ocbsf
    You should see the status as Running for all the pods if BSF is deployed successfully.
  7. Before upgrading, perform sanity check using Helm test. See the Performing Helm Test section for the Helm test procedure.
  8. If the upgrade for BSF fails due to any of the following conflicts, you are required to delete the conflicting items using the relevant commands as follows:
    • In case of conflict due to rolebinding, run the following command:
      kubectl delete rolebinding <conflicting item> -n <namespace>
    • In case of conflict due to PodDisruptionBudget, run the following command:
      kubectl delete PodDisruptionBudget <conflicting item> -n <namespace>

    If the upgrade fails due to any other reason, see Upgrade or Rollback Failure in Oracle Communications Cloud Native Core, Binding Support Function Troubleshooting Guide.