Upgrading dSSM¶
Overview¶
The Cloud-Native Network Functions (CNFs) distributed Session State Management (dSSM) Sentinel and DB Pods can be upgraded using the typical Helm upgrade process. However, to ensure the process completes without service interruption, a custom dssm-upgrade-hook container is deployed during the upgrade. The upgrade process maintains all of the dSSM DB Pod session state data.
This document guides you through upgrading the dSSM database, and verifying the update results are successful.
Note: If preserving data is not required, refer to the Quick Upgrade section to properly uninstall and upgrade the dSSM installation.
Requirements¶
Ensure you have:
- A running CNF dSSM Database installation.
- A newer version of the CNF dSSM Helm chart.
- A workstation with Helm installed.
Procedures¶
Use the procedures below to upgrade the dSSM database, verify the results, and if required, rollback to the previous installation version.
Pre-upgrade status¶
Use the step below to verify the dSSM Pod cluster status and persisted data. This will be useful to ensure the upgrade is successful.
Verify the STATUS of the dSSM Pods is Running:
In this example, the dSSM Pods are in the cnf-gateway Namespace:
oc get pods -n cnf-gateway
NAME READY STATUS RESTARTS f5-dssm-db-0 2/2 Running 0 f5-dssm-db-1 2/2 Running 0 f5-dssm-db-2 2/2 Running 0 f5-dssm-sentinel-0 2/2 Running 0 f5-dssm-sentinel-1 2/2 Running 0 f5-dssm-sentinel-2 2/2 Running 0
Log in to the dSSM database (DB):
oc exec -it f5-dssm-db-0 -- bash
Enter the Redis command line interface (CLI):
redis-cli --tls --cert /etc/ssl/certs/dssm-cert.crt \ --key /etc/ssl/certs/dssm-key.key \ --cacert /etc/ssl/certs/dssm-ca.crt
List the DB entries. The entries should be present after the upgrade.
KEYS *
1) "0073c3b6eft_dns4610.144.175.221" 2) "0073c3b6eft_dns4610.144.175.222" 3) "0073c3b6eft_dns4610.144.175.224" 4) "0073c3b6eft_dns4610.144.175.223" 5) "0073c3b6eft_dns4610.144.175.220"
Software upgrade¶
Use the steps below to upgrade the dSSM Sentinel and DB Pods.
Note: The dssm-upgrade-hook container logs valuable diagnostic data, opening a second shell to view the data is recommended.
Change into the directory containing the latest CNFs Software, and obtain the f5-dssm Helm chart version:
In this example, the CNFs files are in the cnfinstall directory:
cd cnfinstall
ls -1 tar | grep f5-dssm
The example output should appear similar to the following:
f5-dssm-1.2.0.tgz
Create a Helm values file named dssm-upgrade-values.yaml, and set the
image.repository
parameter:In this example, Helm pulls the dssmUpgrader image from registry.com:
dssmUpgrader: image: repository: registry.com
To grant the dssm-upgrade-hook container access the K8S API, create two YAML files with the following code, and set the
namespace
parameter to the dSSM installation Project:Important: The dssm-upgrade-hook will fail to complete the upgrade without proper access to the K8S API.
kind: Role apiVersion: rbac.authorization.k8s.io/v1 metadata: name: pods-list namespace: cnf-gateway rules: - apiGroups: ["", "apps"] resources: ["pods", "statefulset", "statefulsets"] verbs: ["get", "delete", "list", "watch"]
kind: RoleBinding apiVersion: rbac.authorization.k8s.io/v1 metadata: name: pods-list subjects: - kind: ServiceAccount name: default namespace: cnf-gateway roleRef: kind: Role name: pods-list apiGroup: rbac.authorization.k8s.io
Create the
Role
andRoleBinding
objects:oc create -f role.yaml
oc create -f role-binding.yaml
Verify the
Role
andRoleBinding
objects have been created:oc describe -f role.yaml
Name: pods-list Labels: <none> Annotations: <none> PolicyRule: Resources Non-Resource URLs Resource Names Verbs --------- ----------------- -------------- ----- pods [] [] [get delete]
oc describe -f role-bind.yaml
Name: pods-list Labels: <none> Annotations: <none> Role: Kind: Role Name: pods-list Subjects: Kind Name Namespace ---- ---- --------- ServiceAccount default cnf-gateway
Obtain the NAME of the current dSSM Helm release:
helm list -n cnf-gateway
In this example, the dSSM Helm release NAME is f5-dssm:
NAME NAMESPACE REVISION STATUS CHART f5-dssm cnf-gateay 1 deployed f5-dssm-1.0.0
Upgrade the dSSM database Pods using the newer version Helm chart:
Note: The timeout value is a precaution; cluster resources may cause the process to go beyond the default 300 seconds.
helm upgrade f5-dssm <chart>.tgz -f <values>.yaml --timeout 800s -n <namespace>
For example:
helm upgrade f5-dssm f5-dssm-1.2.0.tgz -f dssm-upgrade-values.yaml --timeout 800s -n cnf-gateway
To monitor the upgrade status, in the second shell, view the dssm-upgrade-hook container logs:
oc logs -f f5-dssm-hook -n cnf-gateway
The upgrade logs should begin similar to the following:
HELM-HOOK IS RUNNING UPGRADING SENTINELS Namespace is cnf-gateway dssm-upgrade-hook IS RUNNING
The upgrade logs should end similar to the following:
DONE UPGRADING Helm-hook pod is going down pod "dssm-upgrade-hook" deleted
Post-upgrade status¶
Use the steps below to ensure the dSSM software upgrade was successful.
List the REVISION ( version) of the dSSM Helm releases:
helm history f5-dssm -n cnf-gateway
REVISION STATUS CHART APP VERSION DESCRIPTION 1 superseded f5-dssm-1.0.0 v1.0.0 Install complete 2 deployed f5-dssm-1.2.0 v1.2.0 Upgrade complete
Verify the dSSM Pod STATUS is currently Running:
oc get pods -n cnf-gateway
NAME READY STATUS f5-dssm-db-0 2/2 Running f5-dssm-db-1 2/2 Running f5-dssm-db-2 2/2 Running f5-dssm-sentinel-0 2/2 Running f5-dssm-sentinel-1 2/2 Running f5-dssm-sentinel-2 2/2 Running
Verify the dSSM Pod STATUS is currently Running:
Note: It may take a few minutes for the rollback to complete.
oc get pods -n cnf-gateway
NAME READY STATUS f5-dssm-db-0 2/2 Running f5-dssm-db-1 2/2 Running f5-dssm-db-2 2/2 Running f5-dssm-sentinel-0 2/2 Running f5-dssm-sentinel-1 2/2 Running f5-dssm-sentinel-2 2/2 Running
Log in to the dSSM database (DB):
oc exec -it f5-dssm-db-0 -n cnf-gateway -- bash
Enter the Redis command line interface (CLI):
redis-cli --tls --cert /etc/ssl/certs/dssm-cert.crt \ --key /etc/ssl/certs/dssm-key.key \ --cacert /etc/ssl/certs/dssm-ca.crt
List the DB entries. These entries should be the same as the pre-upgrade check.
KEYS *
1) "0073c3b6eft_dns4610.144.175.221" 2) "0073c3b6eft_dns4610.144.175.222" 3) "0073c3b6eft_dns4610.144.175.224" 4) "0073c3b6eft_dns4610.144.175.223" 5) "0073c3b6eft_dns4610.144.175.220"
Delete the
Role
andRoleBinding
objects:oc delete -f role-binding.yaml
oc delete -f role.yaml
Rollback¶
If the dSSM database is not performing as expected after the upgrade, rollback to the previous dSSM database version using the steps below:
List the current version of the dSSM database:
helm list -n cnf-gateway
In this example, the dSSM database version is *v1.2.0 and the REVISION version is 2:
NAME NAMESPACE REVISION STATUS CHART APP VERSION f5-dssm cnf-gateway 2 deployed f5-dssm-1.2.0 v1.2.0
Rollback the dSSM database to the previous REVISION (installation version):
helm rollback f5-dssm <revision> -n <namespace>
In this example, the previous REVISION is 1:
helm rollback f5-dssm 1 -n cnf-gateway
List the Helm REVISION (installation versions) of the dSSM database:
helm history f5-dssm -n cnf-gateway
REVISION STATUS CHART APP VERSION DESCRIPTION 1 superseded f5-dssm-1.0.0 v1.0.0 Install complete 2 superseded f5-dssm-1.2.0 v1.2.0 Upgrade complete 3 deployed f5-dssm-1.0.0 v1.0.0 Rollback to 1
Verify the dSSM Pod STATUS is currently Running:
Note: It may take a few minutes for the rollback to complete.
oc get pods -n cnf-gateway
NAME READY STATUS f5-dssm-db-0 2/2 Running f5-dssm-db-1 2/2 Running f5-dssm-db-2 2/2 Running f5-dssm-sentinel-0 2/2 Running f5-dssm-sentinel-1 2/2 Running f5-dssm-sentinel-2 2/2 Running
Quick Upgrade¶
The quick upgrade section provides a much easier way to upgrade the dSSM database if preserving data is not a requirement. Use the steps below to properly uninstall the current dSSM Database installation and then reinstall using Helm.
List the dSSM Helm release:
helm list -n <namespace>
In this exammple, the dSSM database release f5-dssm is installed in the cnf-gateway Namespace:
helm list -n cnf-gateway
NAME NAMESPACE REVISION STATUS CHART APP VERSION f5-dssm cnf-gateway 1 deployed f5-dssm-1.0.0 v1.0.0
Uninstall the dSSM installation:
helm uninstall f5-dssm -n cnf-gateway
The commaznd output will appear similar to the following:
release "f5-dssm" uninstalled
List the dSSM PVCs:
oc get pvc -n cnf-gateway
NAME STATUS VOLUME data-f5-dssm-db-0 Bound pvc-933c17ae-4378-4eac-8d09-65848a1e164e data-f5-dssm-db-1 Bound pvc-c843c33b-c277-46f2-bcb1-4ee5db76ea4b data-f5-dssm-db-2 Bound pvc-d0f5441b-0e0c-4385-b558-a84e15fc44a9
Delete each of the PVCs using the PVC NAME:
oc delete pvc data-f5-dssm-db-0 -n cnf-gateway
The command output will appear similar to the following:
persistentvolumeclaim "data-f5-dssm-db-0" deleted
Once all of the PVCs have been deleted, reinstall the dSSM DBs using the dSSM Database installation guide.
Feedback¶
Provide feedback to improve this document by emailing cnfdocs@f5.com.