Upgrade

This chapter details how to update an existing KeySafe 5 install to the latest version.

If the environment that is being upgraded contains a WSOP3.x instance, it must be upgraded to at least WSOP v3.3.0 prior to upgrading KeySafe 5.

When upgrading KeySafe 5 it is recommended to first update the Helm charts installed in the central platform and then update all KeySafe 5 Agent installs on host machines being managed by KeySafe 5.

Upgrading from KeySafe 5 1.3

To upgrade the release of a Helm Chart we do a helm upgrade command, see Helm Upgrade

List all installed releases using helm list -A.

$ helm list -A
NAME            	NAMESPACE      	REVISION	UPDATED                                	STATUS  	CHART                         	APP VERSION
keysafe5-backend	nshieldkeysafe5	1       	2024-04-25 15:59:40.995994525 +0100 BST	deployed	nshield-keysafe5-backend-1.3.0	1.3.0
keysafe5-istio  	nshieldkeysafe5	1       	2024-04-25 15:58:09.344300669 +0100 BST	deployed	nshield-keysafe5-istio-1.3.0  	1.3.0
keysafe5-ui     	nshieldkeysafe5	1       	2024-04-25 15:57:42.260802671 +0100 BST	deployed	nshield-keysafe5-ui-1.3.0     	1.3.0
mongo-chart     	mongons        	1       	2024-04-25 15:55:05.825098514 +0100 BST	deployed	mongodb-12.1.31               	5.0.10
rabbit-chart    	rabbitns       	1       	2024-04-25 15:58:19.881365343 +0100 BST	deployed	rabbitmq-11.16.2              	3.11.18

Ensure all pods are healthy prior to performing an upgrade, unhealthy pods can prevent helm from fully completing an upgrade.

The process involves upgrading the charts in the following order:

keysafe5-backend
keysafe5-ui
keysafe5-istio
mongo-chart
rabbit-chart

Unpack the source

mkdir ~/keysafe5-upgrade
tar -C ~/keysafe5-upgrade -xf nshield-keysafe5-1.4.0.tar.gz
cd ~/keysafe5-upgrade

Docker Images

The Docker images need to be loaded onto a Docker registry that each node in your Kubernetes cluster can pull the images from. See Docker Images for more details.

Upgrading the KeySafe 5 backend

The parameters used for the running Helm chart need to be retrieved into a file called keysafe5-backed-values.yaml.

helm -n nshieldkeysafe5 get values --all --output yaml keysafe5-backend > keysafe5-backend-values.yaml

This file will need updating with the new KeySafe 5 1.4 settings.

helm upgrade --install keysafe5-backend \
  --namespace=nshieldkeysafe5 \
  --wait --timeout 3m \
  --values keysafe5-backend-values.yaml \
  --set hsm_mgmt.image=$DOCKER_REGISTRY/keysafe5/hsm-mgmt:1.4.0 \
  --set sw_mgmt.image=$DOCKER_REGISTRY/keysafe5/sw-mgmt:1.4.0 \
  --set codesafe_mgmt.image=$DOCKER_REGISTRY/keysafe5/codesafe-mgmt:1.4.0 \
  helm-charts/nshield-keysafe5-backend-1.4.0.tgz

Upgrading the KeySafe 5 UI, and Istio

The same process as for the backend is also used for the UI, and Istio:

helm -n nshieldkeysafe5 get values --all --output yaml keysafe5-ui > keysafe5-ui-values.yaml
helm -n nshieldkeysafe5 get values --all --output yaml keysafe5-istio > keysafe5-istio-values.yaml

You may make changes to the yaml files before upgrading though this is not required.

helm upgrade --install keysafe5-ui \
  --namespace=nshieldkeysafe5 \
  --wait --timeout 3m \
  --values keysafe5-ui-values.yaml \
  --set ui.image=$DOCKER_REGISTRY/keysafe5/mgmt-ui:1.4.0 \
  --set ui.pullPolicy=Always \
  helm-charts/nshield-keysafe5-ui-1.4.0.tgz

helm upgrade --install keysafe5-istio \
  --namespace=nshieldkeysafe5 \
  --wait --timeout 3m \
  --values keysafe5-istio-values.yaml \
  helm-charts/nshield-keysafe5-istio-1.4.0.tgz

Agent Upgrade

To update the KeySafe 5 Agent installed on a machine:

Take a backup of the Agent config directory located at %NFAST_DATA_HOME%/keysafe5/conf.
Uninstall the existing KeySafe 5 Agent as detailed in the KeySafe 5 Installation Guide for the currently installed version of the product.
Install the new KeySafe 5 Agent as detailed in chapter KeySafe 5 Agent Installation.

Upgrading supporting software

KeySafe 5 1.3 recommended RabbitMQ 3.12.13 and MongoDB 7.0.7. This section details how to upgrade the software from these versions to the latest recommended compatible versions.

MongoDB 7.0.7 to 7.0.11

To update a non-Kubernetes existing MongoDB install to a MongoDB 7.0.11 install, see the official documentation at Upgrade to the Latest Revision of MongoDB.

To update a MongoDB 7.0.7 install deployed via Bitnami Helm Charts:

First ensure that MongoDB is running.

helm list -A

Fetch the existing helm chart’s settings

helm -n mongons get values --output yaml mongo-chart > mongo-chart-values.yaml

The password and replicaset key have not changed, so we can upgrade.

helm upgrade mongo-chart bitnami/mongodb \
  --namespace mongons \
  --wait --timeout 3m \
  --set image.tag=7.0.11-debian-12-r0 \
  --values mongo-chart-values.yaml \
  --version 15.0.2

After this has finished, wait until the KeySafe 5 backend services are running again.

Obtain details of newly deployed helm charts

helm list -A

RabbitMQ 3.12.13 to 3.13.3

To update a non-Kubernetes existing RabbitMQ install, see the official documentation at Upgrading RabbitMQ.

To update a RabbitMQ 3.12.13 install deployed via Bitnami Helm Charts:

# Obtain details of currently deployed helm charts
# Substitute chart and namespace values in the commands below as required
helm list -A

# Fetch current rabbitmq helm chart deployed values
helm -n rabbitns get values --output yaml rabbit-chart > rabbit-chart-values.yaml

# Upgrade helm chart based on existing deployed values
helm upgrade --install rabbit-chart \
  --namespace=rabbitns \
  --values rabbit-chart-values.yaml \
  --set image.tag=3.13.3-debian-12-r1 \
  --set service.type=LoadBalancer \
  --set extraPlugins="rabbitmq_auth_mechanism_ssl" \
  --wait --timeout 10m \
  bitnami/rabbitmq --version 12.13.1

# Obtain details of newly deployed helm charts
helm list -A

Istio

The version of Istio installed aligns with the software version of istioctl.

For details of how to upgrade Istio, see Upgrade Istio.