Upgrade Fortanix Armor

1.0 Introduction

This article describes how to upgrade an existing Fortanix Armor deployment to a newer version.

Fortanix Armor on-premises is deployed on a customer-managed Kubernetes cluster using a Fortanix-provided Helm chart and Kubernetes operator. The operator manages the lifecycle of all Fortanix Armor components, which are deployed as containerized services within the cluster.

This article assumes that Fortanix Armor is already deployed and that the required infrastructure and prerequisites are in place.

2.0 Supported Upgrade Paths

Before you upgrade, review the release notes for the target Fortanix Armor Kubernetes Operator version to verify the supported upgrade path and any version-specific upgrade requirements.

For supported upgrade paths, refer to the latest Fortanix Armor Kubernetes Operator Release Notes.

3.0 Before You Upgrade

3.1 Verify Prerequisites

Ensure that the existing Kubernetes cluster and infrastructure meet the prerequisites for the target Fortanix Armor version. For more information, refer to Prerequisites.

3.2 Backup the Existing Configuration

Before upgrading, back up the existing Fortanix Armor configuration and data as described in Backup and Restore.

3.3 Verify the Cassandra `StorageClass`

Before upgrading, run the following command to verify that the StorageClass used by the existing Cassandra deployment is available in the Kubernetes cluster:

kubectl get storageclass

Do not change the existing Cassandra StorageClass configuration unless required by the target Armor version.

4.0 Prepare the Deployment for Upgrade

4.1 Preserve Customer-Managed Resources

If you are upgrading from an Armor Kubernetes Operator version earlier than 28.0.5, preserve the existing Cassandra inter-node TLS resources before initiating the upgrade by applying the helm.sh/resource-policy=keep annotation as described in this section.

Run the following commands once before initiating the upgrade to prevent Helm from deleting the existing Cassandra inter-node TLS resources:

kubectl -n cert-manager annotate issuer cluster-ca-issuer helm.sh/resource-policy=keep
kubectl -n cert-manager annotate certificate cluster-ca helm.sh/resource-policy=keep
kubectl -n cert-manager annotate clusterissuer cluster-issuer helm.sh/resource-policy=keep

NOTE
Run the above commands before upgrading to Armor Kubernetes Operator 28.0.5 or later. The helm.sh/resource-policy=keep annotation prevents Helm from deleting these resources during the upgrade.
This is a one-time step required only when upgrading an existing deployment from an Armor Kubernetes Operator version earlier than 28.0.5. After the upgrade, these resources are customer-managed and do not need to be annotated again for subsequent Armor upgrades.
After the resources are preserved, they remain customer-managed and do not need to be recreated during subsequent Armor upgrades.

4.2 Update the Database Configuration

If you are upgrading from an Armor Kubernetes Operator version earlier than 28.0.5, ensure that spec.database.issuerRef of the ArmorPlatform resource is set to cluster-issuer before initiating the upgrade.

For information about the ArmorPlatform resource configuration, refer to Create ArmorPlatform Resource and Apply the Configuration.

5.0 Upgrade Fortanix Armor Kubernetes Operator

5.1 Prerequisites

Before upgrading the Fortanix Armor Kubernetes Operator, ensure that:

You have access to the Fortanix OCI registry and the credentials required to authenticate to it.
Helm is installed on the system from which you are performing the upgrade.
You have kubectl access to the Kubernetes cluster with sufficient permissions to perform the upgrade.

NOTE
Do not recreate the Fortanix Armor Kubernetes Operator namespace, image pull secret, or other resources that were created during the initial installation unless specifically required by the target version.

5.2 Set the Required Environment Variables

Set the environment variables required to authenticate to the Fortanix OCI registry and specify the Kubernetes namespace and target Fortanix Armor Kubernetes Operator version for the upgrade.

export REGISTRY_USERNAME="my_username" #replace
export REGISTRY_PASSWORD="password" #replace
export OPERATOR_NAMESPACE="armor" 
export VERSION_TO_DEPLOY="<operator-version>" #replace with fortanix provided version
export REGISTRY_URL="cr.download.fortanix.com"

Where,

REGISTRY_URL: The OCI (Oracle Cloud Infrastructure) registry endpoint that hosts the Fortanix Armor container images and Helm charts (cr.download.fortanix.com).
REGISTRY_USERNAME: Username used to authenticate to the Fortanix OCI registry.
REGISTRY_PASSWORD: Password or token used to authenticate to the Fortanix OCI registry.
OPERATOR_NAMESPACE: The Kubernetes namespace where the Fortanix Armor Kubernetes Operator is installed (for example, armor).
VERSION_TO_DEPLOY: The version of the Fortanix Armor Kubernetes Operator Helm chart to be deployed.

5.3 Authenticate to the Fortanix OCI Registry

echo "$REGISTRY_PASSWORD" | helm registry login "$REGISTRY_URL" -u "$REGISTRY_USERNAME" --password-stdin

Where,

REGISTRY_URL: The OCI (Oracle Cloud Infrastructure) registry endpoint that hosts the Fortanix Armor container images and Helm charts (cr.download.fortanix.com).
REGISTRY_USERNAME: Username used to authenticate to the Fortanix OCI registry.
REGISTRY_PASSWORD: Password or token used to authenticate to the Fortanix OCI registry.

NOTE
If your organization mirrors Fortanix container images and Helm charts to an internal registry, use the registry URL, credentials, and Helm chart location configured for your environment.

5.4 Upgrade the Fortanix Armor Kubernetes Operator

Run the following command to upgrade the Fortanix Armor Kubernetes Operator to the target version:

helm upgrade --install armor-platform-operator-chart \
  oci://cr.download.fortanix.com/charts/armor-platform-operator \
  --namespace "$OPERATOR_NAMESPACE" \
  --no-hooks \
  --version "$VERSION_TO_DEPLOY"

Replace VERSION_TO_DEPLOY with the target Armor Kubernetes Operator version specified in the release notes for the Armor Kubernetes Operator version you are upgrading to.

NOTE
If your existing deployment uses nodeSelector settings to schedule the Armor Kubernetes Operator pods on specific Kubernetes nodes, preserve the existing scheduling configuration when upgrading.

5.4.1 Upgrade Using Helm 4

WARNING
If you are upgrading an existing Fortanix Armor Kubernetes Operator deployment from 1.0.480 or later to 28.0.5 or later using Helm 4, add --server-side=false argument to the helm upgrade command.

For upgrades that meet the conditions described above, run the following command:

helm upgrade --install armor-platform-operator-chart \
  oci://cr.download.fortanix.com/charts/armor-platform-operator \
  --namespace "$OPERATOR_NAMESPACE" \
  --no-hooks \
  --version "$VERSION_TO_DEPLOY" \
  --server-side=false

NOTE
The --server-side=false argument is required only for the first upgrade to version 28.0.5 or later using Helm 4.
It is not required for fresh installations.
It is not required when using Helm versions earlier than Helm 4.
After the first upgrade to 28.0.5, subsequent Helm 4 upgrade commands do not require the argument.

5.5 Perform a One-Time Cassandra Restart

If you are upgrading from an Armor Kubernetes Operator version earlier than 28.0.5, perform the following one-time step after the upgrade.

Starting with Armor Kubernetes Operator version 28.0, the Cassandra deployment uses an updated network configuration that changes hostNetwork from true to false.

WARNING
This operation causes temporary downtime while the Cassandra pods restart. The restart takes approximately 3 minutes on average but may take longer depending on the hardware and pod scheduling.

NOTE
After upgrading the Armor Kubernetes Operator, wait until the armor-platform-operator pod is up and running before performing the Cassandra restart. Do not execute the following command immediately after the operator upgrade command. The operator must be running to reconcile the Cassandra deployment and bring the Cassandra pods back up after the restart.

Run the following command to restart the Cassandra pods with the updated configuration:

kubectl scale sts main-dc1-rack1-sts --replicas 0 -n armor

The Cassandra pods should return with 3/3 under READY and return to the Running state.

NOTE
This is a one-time operation required after the first upgrade from a version earlier than 28.0.5 to a version that includes the updated Cassandra configuration.
It is not required for subsequent upgrades.
No data loss is expected.

5.6 Verify the Operator Upgrade

After the upgrade completes, verify that the Fortanix Armor Kubernetes Operator and Armor platform components are running successfully.

Run the following command to verify the Fortanix Armor Kubernetes Operator pods:
```
kubectl get pods -n <operator-namespace>
```
Ensure all pods are in the Running state.
Figure 1: Operator deployed
Verify the ArmorPlatform resource: For more information about the ArmorPlatform configuration, refer to Create ArmorPlatform Resource and Apply the Configuration.