Upgrade

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

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.

This page details upgrading from KeySafe 5 1.5 or 1.6.1 to 1.7.

To upgrade from an earlier version, you must first upgrade to either 1.5 or 1.6.1. To upgrade to one of these versions, see the Installation and Upgrade Guide for that version.

Upgrade the Helm Charts

Check pod status of all installed releases using helm list -A.

1.5 example:

$ helm list -A
NAME                    NAMESPACE       REVISION        UPDATED                                 STATUS          CHART                           APP VERSION
keysafe5-backend        nshieldkeysafe5 1               2026-02-27 15:02:13.282721102 +0000 UTC deployed        nshield-keysafe5-backend-1.5.0  1.5.0
keysafe5-istio          nshieldkeysafe5 1               2026-02-27 15:02:52.330394377 +0000 UTC deployed        nshield-keysafe5-istio-1.5.0    1.5.0
keysafe5-ui             nshieldkeysafe5 1               2026-02-27 15:02:27.88054163 +0000 UTC  deployed        nshield-keysafe5-ui-1.5.0       1.5.0
mongo-chart             mongons         1               2026-02-27 15:00:38.400603954 +0000 UTC deployed        mongodb-17.0.0                  8.0.13

1.6.1 example:

$ helm list -A
NAME                    NAMESPACE       REVISION        UPDATED                                 STATUS          CHART                                   APP VERSION
keysafe5-alertmanager   nshieldkeysafe5 1               2026-03-05 15:34:21.088573428 +0000 UTC deployed        nshield-keysafe5-alertmanager-1.6.1     1.6.1
keysafe5-backend        nshieldkeysafe5 1               2026-03-05 15:34:05.548334361 +0000 UTC deployed        nshield-keysafe5-backend-1.6.1          1.6.1
keysafe5-istio          nshieldkeysafe5 1               2026-03-05 15:34:46.687963379 +0000 UTC deployed        nshield-keysafe5-istio-1.6.1            1.6.1
keysafe5-prometheus     nshieldkeysafe5 1               2026-03-05 15:34:20.901035813 +0000 UTC deployed        nshield-keysafe5-prometheus-1.6.1       1.6.1
keysafe5-ui             nshieldkeysafe5 1               2026-03-05 15:34:21.318073454 +0000 UTC deployed        nshield-keysafe5-ui-1.6.1               1.6.1
mongo-chart             mongons         1               2026-03-05 15:32:28.634747553 +0000 UTC deployed        mongodb-17.0.0                          8.0.13

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

Upgrade the Helm Charts in the following order using helm upgrade:

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

See Helm Upgrade for more information.

Unpack the source

mkdir ~/keysafe5-1.7.0
tar -C ~/keysafe5-1.7.0 -xf nshield-keysafe5-1.7.0.tar.gz
cd ~/keysafe5-1.7.0/keysafe5-k8s

Load the 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 instructions.

Move the CA

The CA needs to be moved from the 1.5 or 1.6.1 directory of KeySafe 5 to the 1.7.0 directory. Depending on your existing setup this is done in different ways. This guide includes the steps for moving internalCA and externalCA.

Both methods use the ~/keysafe5-1.7.0/keysafe5-k8s/updateinternalcerts.sh script.

externalCA

Create a new directory in the 1.7.0 upgrade directory. This directory needs to contain the server, the client keys, and certificates in PEM format.

mkdir ~/keysafe5-1.7.0/keysafe5-k8s/externalCA

The following files need to be included in this directory:

  ca.crt                      The certificate of the CA that is to be trusted by
                              the system.
  agentcomms.key              The key to be used by the Agent Communications
                              Server
  agentcomms.crt              And its certificate
  ks5agentcomms.key           The key to be used by ks5
  ks5agentcomms.crt           And its certificate

Run updateinternalcerts.sh to refresh certificates:
```
./updateinternalcerts.sh -n certs externalCA
```
This specific command refreshes certificates in the "certs" namespace. For more instructions refer to the help of updateinternalcerts.sh.

internalCA

If you are using internalCA then the CA is contained within a folder called "CA" or "internalCA" of the previous installation.

Copy the existing folder into the current directory for the upgrade, for example:
```
cp -r ~/existing-ks5-install/internalCA .
```
Generate the new certificates using updateinternalcerts.sh.

The following example sets the expiration date for 1 year. This command may appear to fail, but if a folder called keysafe5-cert-update is created then this step was successful.
```
./updateinternalcerts.sh agentcomms 365
```

Update MongoDB and define new database roles

Ensure that the MongoDB you have installed matches the prerequisites described here.
Connect to mongosh, with admin privileges.

Add the following new roles for the KS5 user.

Upgrading from 1.5:

View code

> db.createRole(
  {
    role: "monitoring-mgmt-db-user",
    privileges: [
        {
          "resource": {"db": "monitoring-mgmt-db", "collection": ""},
          "actions": ["createIndex", "find", "insert", "remove", "update"]
        },
      ],
    roles: []
  }
)
> db.createRole(
  {
    role: "licence-mgmt-db-user",
    privileges: [
        {
          "resource": {"db": "licence-mgmt-db", "collection": ""},
          "actions": ["createIndex", "dropCollection", "find", "insert", "remove", "update"]
        },
      ],
    roles: []
  }
)
> db.createRole(
  {
    role: "agent-mgmt-db-user",
    privileges: [
        {
          "resource": {"db": "agent-mgmt-db", "collection": ""},
          "actions": ["createIndex", "dropCollection", "find", "insert", "remove", "update"]
        },
      ],
    roles: []
  }
)
> db.updateRole( "hsm-mgmt-db-user",
  {
    privileges : [
        {
          "resource": {"db": "hsm-mgmt-db", "collection": ""},
          "actions": ["createIndex", "dropIndex", "find", "insert", "remove", "update"]
        },
      ]
  }
)
> use $external
> x509_user = {
   "roles" : [
     {"role": "agent-mgmt-db-user", "db": "admin" },
     {"role": "codesafe-mgmt-db-user", "db": "admin" },
     {"role": "hsm-mgmt-db-user", "db": "admin" },
     {"role": "sw-mgmt-db-user", "db": "admin" },
     {"role": "monitoring-mgmt-db-user", "db": "admin" },
     {"role": "licence-mgmt-db-user", "db": "admin" },
   ]
 }
> db.updateUser("CN=ks5-mongo-user", x509_user)
> exit
$ exit

Upgrading from 1.6.1:

View code

> db.createRole(
  {
    role: "agent-mgmt-db-user",
    privileges: [
        {
          "resource": {"db": "agent-mgmt-db", "collection": ""},
          "actions": ["createIndex", "dropCollection", "find", "insert", "remove", "update"]
        },
      ],
    roles: []
  }
)
> db.updateRole( "hsm-mgmt-db-user",
  {
    privileges : [
        {
          "resource": {"db": "hsm-mgmt-db", "collection": ""},
          "actions": ["createIndex", "dropIndex", "find", "insert", "remove", "update"]
        },
      ]
  }
)
> use $external
> x509_user = {
   "roles" : [
     {"role": "agent-mgmt-db-user", "db": "admin" },
     {"role": "codesafe-mgmt-db-user", "db": "admin" },
     {"role": "hsm-mgmt-db-user", "db": "admin" },
     {"role": "sw-mgmt-db-user", "db": "admin" },
     {"role": "monitoring-mgmt-db-user", "db": "admin" },
     {"role": "licence-mgmt-db-user", "db": "admin" },
   ]
 }
> db.updateUser("CN=ks5-mongo-user", x509_user)
> exit
$ exit

Upgrade the KeySafe 5 backend

Retrieve the parameters used for running the Helm Chart into a file called keysafe5-backend-values.yaml:

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

The new services support the same common values as other services, such as probe thresholds.

If you are upgrading from v1.5, you will have the following new services: monitoring_mgmt, licence_mgmt, and agent_mgmt.

If you are upgrading from v1.6.1, you will have the following new service: agent_mgmt.

If required, add them to the keysafe5-backend-values.yaml file:

helm upgrade --install keysafe5-backend \
  --namespace=nshieldkeysafe5 \
  --values keysafe5-backend-values.yaml \
  --set hsm_mgmt.image=$DOCKER_REGISTRY/keysafe5/hsm-mgmt:1.7.0 \
  --set sw_mgmt.image=$DOCKER_REGISTRY/keysafe5/sw-mgmt:1.7.0 \
  --set codesafe_mgmt.image=$DOCKER_REGISTRY/keysafe5/codesafe-mgmt:1.7.0 \
  --set agent_mgmt.image=$DOCKER_REGISTRY/keysafe5/agent-mgmt:1.7.0 \
  --set licence_mgmt.image=$DOCKER_REGISTRY/keysafe5/licence-mgmt:1.7.0 \
  --set monitoring_mgmt.image=$DOCKER_REGISTRY/keysafe5/monitoring-mgmt:1.7.0 \
  --set messageBus.compatibilityMode=true \
  --set messageBus.URL=127.0.0.1:18084 \
  --set messageBus.auth.type=tls \
  --set messageBus.tls.enabled=true \
  --set messageBus.tls.existingSecret=agentcomms-client-certificates \
  --set messageBus.serverTLS.existingSecret=agentcomms-server-certificates \
  --values keysafe5-backend-values.yaml \
  --wait --timeout 3m \
  helm-charts/nshield-keysafe5-backend-1.7.0.tgz

Upgrade the KeySafe 5 WebUI

Retrieve the parameters used for running the Helm Chart into a file called keysafe-ui-values.yaml:

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

You can change the yaml files before upgrading, although this is not required.

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

Upgrade the KeySafe 5 Istio

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

Enable the agent-mgmt port and certificates reference:

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

istioctl x precheck

istioctl upgrade -y \
  --set values.gateways.istio-ingressgateway.ingressPorts[0].name=agent-comms \
  --set values.gateways.istio-ingressgateway.ingressPorts[0].port=18084 \
  --set values.gateways.istio-ingressgateway.ingressPorts[0].protocol=TCP

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

Prometheus

Install Prometheus (upgrading from 1.5 only)

If you are upgrading from 1.6.1, see here

Create a file called pvc.yaml with the following contents in your current folder:

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: prometheus-data-keysafe5
spec:
  storageClassName: local-path
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 4Gi

Create it in kubernetes:

kubectl apply -f pvc.yaml --namespace=nshieldkeysafe5

After the volume has been created, install the Prometheus Helm Chart:

helm install keysafe5-prometheus \
  --namespace=nshieldkeysafe5 \
  --set prometheus.image=$DOCKER_REGISTRY/keysafe5/prometheus:v3.5.1 \
  --set prometheus.pvc=prometheus-data-keysafe5 \
  --set prometheus.sharedpvc=data-nshield-keysafe5 \
  --wait --timeout 3m \
  helm-charts/nshield-keysafe5-prometheus-1.7.0.tgz

Upgrade Prometheus (upgrading from 1.6.1 only)

Retrieve the paramaters for the running Helm Chart into a file called keysafe5-prometheus-values.yaml:

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

Upgrade Prometheus:

helm upgrade --install keysafe5-prometheus \
  --namespace=nshieldkeysafe5 \
  --set prometheus.image=$DOCKER_REGISTRY/keysafe5/prometheus:v3.5.1 \
  --set prometheus.pvc=prometheus-data-keysafe5 \
  --set prometheus.sharedpvc=data-nshield-keysafe5 \
  --wait --timeout 3m \
  helm-charts/nshield-keysafe5-prometheus-1.7.0.tgz

Prometheus Alertmanager

Install Alertmanager (upgrading from 1.5 only)

If you are upgrading from 1.6.1, see here

Install the Alertmanager Helm Chart with helm install keysafe5-alertmanager:

helm install keysafe5-alertmanager\
  --namespace=nshieldkeysafe5 \
  --set alertmanager.image=$DOCKER_REGISTRY/keysafe5/alertmanager:v0.31.1 \
  --set alertmanager.sharedpvc=data-nshield-keysafe5 \
  --set sidecar.image=$DOCKER_REGISTRY/keysafe5/alert-manager-sidecar:1.7.0 \
  --set sidecar.configPath=/etc/shared_volume/prometheus \
  --wait --timeout 3m \
  helm-charts/nshield-keysafe5-alertmanager-1.7.0.tgz

Upgrade Alertmanager (upgrading from 1.6.1 only)

Retrieve the parameters used for the running Helm Chart into a file called keysafe5-alertmanager-values.yaml:

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

Upgrade Prometheus Alertmanager:

helm upgrade --install keysafe5-alertmanager\
  --namespace=nshieldkeysafe5 \
  --set alertmanager.image=$DOCKER_REGISTRY/keysafe5/alertmanager:v0.31.1 \
  --set alertmanager.sharedpvc=data-nshield-keysafe5 \
  --set sidecar.image=$DOCKER_REGISTRY/keysafe5/alert-manager-sidecar:1.7.0 \
  --set sidecar.configPath=/etc/shared_volume/prometheus \
  --wait --timeout 3m \
  helm-charts/nshield-keysafe5-alertmanager-1.7.0.tgz

KeySafe 5 Agent Upgrade

To upgrade KeySafe 5 Agents, see Agent Upgrade.

Confirm Upgrade

To check whether the upgrades were successful, run the following commands and compare them to the expected outputs:

First check:

helm list -A

Expected output:

NAME                    NAMESPACE       REVISION        UPDATED                                 STATUS          CHART                                   APP VERSION
keysafe5-alertmanager   nshieldkeysafe5 1               2026-02-27 15:33:59.978870545 +0000 UTC deployed        nshield-keysafe5-alertmanager-1.7.0     1.7.0
keysafe5-backend        nshieldkeysafe5 3               2026-02-27 15:25:24.4028532 +0000 UTC   deployed        nshield-keysafe5-backend-1.7.0          1.7.0
keysafe5-istio          nshieldkeysafe5 2               2026-02-27 15:29:54.541051281 +0000 UTC deployed        nshield-keysafe5-istio-1.7.0            1.7.0
keysafe5-prometheus     nshieldkeysafe5 1               2026-02-27 15:32:11.479065523 +0000 UTC deployed        nshield-keysafe5-prometheus-1.7.0       1.7.0
keysafe5-ui             nshieldkeysafe5 2               2026-02-27 15:28:16.589140868 +0000 UTC deployed        nshield-keysafe5-ui-1.7.0               1.7.0
mongo-chart             mongons         1               2026-02-27 15:00:38.400603954 +0000 UTC deployed        mongodb-17.0.0                          8.0.13

Second check:

kubectl get pods -A

Expected output:

NAMESPACE         NAME                                        READY   STATUS    RESTARTS   AGE
istio-system      istio-ingressgateway-86b88cb445-5cxwt       1/1     Running   0          36m
istio-system      istiod-5fdd7c6d74-qvclm                     1/1     Running   0          36m
kube-system       coredns-697968c856-r2hz6                    1/1     Running   0          36m
kube-system       local-path-provisioner-774c6665dc-8t8h9     1/1     Running   0          36m
kube-system       svclb-istio-ingressgateway-bfa0de4b-bnxhj   4/4     Running   0          36m
mongons           mongo-chart-mongodb-0                       1/1     Running   0          35m
mongons           mongo-chart-mongodb-1                       1/1     Running   0          34m
mongons           mongo-chart-mongodb-arbiter-0               1/1     Running   0          35m
nshieldkeysafe5   nshield-alertmanager-0                      2/2     Running   0          103s
nshieldkeysafe5   nshield-alertmanager-1                      2/2     Running   0          103s
nshieldkeysafe5   nshield-alertmanager-2                      2/2     Running   0          103s
nshieldkeysafe5   nshield-keysafe5-0                          6/6     Running   0          9m54s
nshieldkeysafe5   nshield-keysafe5-1                          6/6     Running   0          10m
nshieldkeysafe5   nshield-keysafe5-2                          6/6     Running   0          10m
nshieldkeysafe5   nshield-keysafe5-ui-75d85874d9-5fkf4        1/1     Running   0          6m42s
nshieldkeysafe5   nshield-keysafe5-ui-75d85874d9-mvp5p        1/1     Running   0          7m4s
nshieldkeysafe5   nshield-keysafe5-ui-75d85874d9-xmc5h        1/1     Running   0          7m27s
nshieldkeysafe5   nshield-prometheus-0                        1/1     Running   0          3m32s
nshieldkeysafe5   ratelimit-6b698cff9d-9z5pw                  1/1     Running   0          5m18s
nshieldkeysafe5   redis-74bf56bf-55948                        1/1     Running   0          5m49s