Installation Guide - On-premises

1.0 Introduction

This article describes how to deploy Fortanix Armor in a customer-managed Kubernetes environment (on-premises or cloud-hosted).

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.

The article assumes that the required infrastructure and prerequisites described in Prerequisites are already in place.

2.0 Key Components

For information on Fortanix Armor key components, refer to Key Components.

3.0 Fortanix Armor Architecture Diagram (On-premises)

For more information on the Fortanix Armor Architecture, refer to Fortanix Armor Architecture (On-premises).

4.0 Prerequisites

For prerequisites to install and deploy Fortanix Armor on-premises, refer to Prerequisites.

5.0 Ingress Controller

The Fortanix Armor Kubernetes Operator creates and manages an Ingress resource to expose static UI artifacts. This Ingress resource relies on an existing Ingress Controller to manage it.

For detailed steps to configure the Ingress resource, refer to the Section 8.5: Ingress Configuration.

Run the following command to install a Kubernetes Ingress Controller (For example: NGINX Ingress):

helm upgrade --install nginx-ingress -n nginx-ingress  \
  --create-namespace  \
  --set controller.kind=daemonset  \
  --set-json controller.service.annotations='{"service.beta.kubernetes.io\/azure-load-balancer-internal": "true"}'  \
  oci://ghcr.io/nginx/charts/nginx-ingress \
  --wait

6.0 Cert-Manager

Fortanix Armor uses cert-manager to automate TLS certificate provisioning for internal platform components.

Install a supported version of cert-manager. For supported versions, refer to https://cert-manager.io/docs/releases.

Run the following command to install cert-manager:

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.4/cert-manager.yaml

NOTE

• cert-manager is used for internal TLS certificate management within the cluster.

• You must also provision external TLS certificates separately for the Fortanix Armor UI (static frontend) and the Armor API endpoint as described in Section 10.0: Install Certificates.

• You must create a certificate issuer (ClusterIssuer) as described in Section 6.1: Create Cluster Issuer that generates a self-signed certificate.

• The cert-manager and the required ClusterIssuer must be installed and configured before deploying the Fortanix Armor Kubernetes Operator, as the operator depends on cert-manager for this automated certificate provisioning.

6.1 Create Cluster Issuer

A ClusterIssuer is a resource created by cert-manager that defines how certificates should be issued for the cluster. Fortanix Armor can use cert-manager to issue this TLS certificate automatically.

To enable this, you must create a ClusterIssuer.

NOTE

In this example, a self-signed ClusterIssuer is used to generate certificates within the cluster. For production environments, configure cert-manager to use an external or trusted CA.

1. To create the ClusterIssuer resource, create a file named cluster-issuer.yaml with the following content:

   apiVersion: cert-manager.io/v1
   kind: ClusterIssuer
   metadata:
     name: selfsigned-cluster-issuer
   spec:
     selfSigned: {}

2. Run the following command to create the ClusterIssuer and apply the configuration:

   kubectl apply -f cluster-issuer.yaml

7.0 Deploy Fortanix Armor Kubernetes Operator

The following example demonstrates how to authenticate to Fortanix OCI registry, create required namespaces and image pull secrets, and deploy the Fortanix Armor Kubernetes Operator using a Helm chart.

NOTE

• This example assumes that Fortanix container images and Helm charts are pulled directly from the Fortanix-managed registry.

• If your organization mirrors these images to an internal container registry, the registry URL, credentials, and Helm chart location will differ.

• The Helm chart location and configuration values are provided below. For the latest available versions of the Fortanix Armor Kubernetes Operator Helm Chart, click here.

1. The following environment variables need to be set to install Fortanix Armor Kubernetes Operator:  

   export REGISTRY_USERNAME="my_username" #replace
   export REGISTRY_PASSWORD="password" #replace 
   export OPERATOR_NAMESPACE="armor" 
   export VERSION_TO_DEPLOY="1.0.404" #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.

2. Create the secret that will allow the operator to pull the images from the registry URL.

   kubectl create namespace "$OPERATOR_NAMESPACE" --dry-run=client -o yaml | kubectl apply -f -
   kubectl create secret docker-registry oci-registry-secret \
         --docker-server="$REGISTRY_URL" \
         --docker-username="$REGISTRY_USERNAME" \
         --docker-password="$REGISTRY_PASSWORD" \
         --docker-email="user@fortanix.net" \
         --dry-run=client -o yaml | kubectl apply -n "$OPERATOR_NAMESPACE" -f -

   Where,

   • oci-registry-secret: Kubernetes image pull secret created in each namespace to allow access to the Fortanix OCI registry.

3. Log in to the Fortanix registry to pull the Helm chart.

   echo "$REGISTRY_PASSWORD" | helm registry login "$REGISTRY_URL" -u "$REGISTRY_USERNAME" --password-stdin
   
   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" #present in changelog (customer can choose which version they want to use)

   Optionally, append the following parameters to the above Helm command to schedule the operator pods on specific Kubernetes nodes:

   --set "k8ssandra-operator.nodeSelector.kubernetes\.io/hostname"="<node-name>" \
   --set "k8ssandra-operator.cass-operator.nodeSelector.kubernetes\.io/hostname"="<node-name>" \
   --set "armorPlatformOperator.nodeSelector.kubernetes\.io/hostname"="<node-name>"
   

   Where, <node-name> specifies the Kubernetes node name where the operator pods should be scheduled. For example, aks-sgxpool11-79929798-vmss000000.

   NOTE

   The nodeSelector configuration is optional. If not specified, Kubernetes schedules the operator pods using the cluster's default scheduling behavior.

4. Run the following command to verify that the Fortanix Armor Kubernetes Operator is successfully deployed and is running correctly within the Kubernetes cluster.

   kubectl get pods -n <operator-namespace>

   Ensure all pods are running.

   

5. Create the Armor Platform Resource configuration file. Refer to Section 8.0: Create ArmorPlatform Resource and Apply the Configuration.

8.0 Create ArmorPlatform Resource and Apply the Configuration

This section describes how to create an ArmorPlatform custom resource to define the Fortanix Armor platform configuration and trigger deployment of Armor components by the operator.

NOTE

• The following configuration is a single YAML file. It is presented in multiple sections below for readability. Use the following sample configuration as a reference and update values as required for your environment.

• Contact the Fortanix Support Team to create the correct configuration file.

• The YAML file can be found in the following path: armor-platform-operator-chart/templates/platform-crd.yaml

8.1 Base Configuration

Define the core configuration for the ArmorPlatform resource, including platform identity, replica settings, and container image configuration.

apiVersion: fortanix.com/v1
kind: ArmorPlatform
metadata:
  name: platform-test
spec:
  # Immutable once created
  name: platform-test

  # Optional Node selector used to target SGX-enabled node pools.
  nodeSelector:     
    feature.node.kubernetes.io/cpu-security.sgx.enabled: "true"

  # Confidential computing infrastructure configuration
  ccInfrastructure: # see Section 8.2

  # Optional configurations (can be omitted if defaults are sufficient)
  enrollment: # see Section 8.3
  database: # see Section 8.4

  # Controls the number of copies of each microservice to maintain. 
  # Also controls database replicas unless explicitly defined in the 
  # Cassandra datacenter topology.
  replicas: 3

  # Default image configuration
  imageDefaults:
    pullSecretRef: "oci-registry-secret"
    registry: "cr.download.fortanix.com"

  # Optional image overrides for specific services
  imageOverrides:
    - service: alhambra
      repository: "alhambra-backend"

  # External access and certificate configuration
  ingress: # see Section 8.5

  # Internal cluster network ranges (pod CIDR, service CIDR, etc.)
  internalSubnets:
    - "<pod-subnet-cidr>"
    - "<service-subnet-cidr>"
  # Used to temporarily prevent the operator from reconciling this ArmorPlatform resource.
  paused: false
   

NOTE

• The nodeSelector configuration is optional and supports multiple label selectors for stricter node selection.

• The nodeSelector configuration requires enabling labelling for the SGX-enabled user node pool in AKS. For instructions on configuring the labelling, refer to Prerequisites.

Where,

• nodeSelector (optional): Specifies node labels used to schedule Fortanix Armor workloads on SGX-enabled nodes.

• replicas: Specifies the number of instances for Fortanix Armor services and Cassandra nodes. The default value is 3.

• imageDefaults: Defines default container image registry and pull configurations for all components.

  • registry: Specifies the container registry URL hosting Fortanix Armor images.

  • pullSecretRef: Specifies the Kubernetes secret for registry authentication.

• imageOverrides (optional): Allows specific Fortanix Armor services to use container image settings that differ from the defaults defined in imageDefaults. This is typically used when mirroring images to an internal container registry or when overriding image repositories for selected services.

  NOTE

  Contact Fortanix Support for guidance on supported service-specific image overrides.

• internalSubnets: Defines CIDR ranges representing internal cluster networks (for example, pod CIDR and service CIDR). Traffic originating from these ranges is treated as internal to the cluster. Multiple CIDRs should be specified to cover all cluster networking ranges.

• paused (optional): Temporarily suspends reconciliation of the ArmorPlatform resource. When enabled, the operator does not apply configuration changes until reconciliation is resumed.

8.2 Confidential Computing Infrastructure Configuration

Define the confidential computing infrastructure for Fortanix Armor. This section specifies the hardware-backed security technology (for example, Intel SGX) and its required configuration for enabling enclave-based workloads.

ccInfrastructure:
  sgx:
    aesmd:
      dcapProvider: azure

Where,

• ccInfrastructure: Defines the confidential computing infrastructure configuration.

• sgx: Specifies the use of Intel SGX for confidential workloads.

• aesmd: Configures the Intel SGX Architectural Enclave Service Manager (AESM) required for SGX functionality.

  • dcapProvider: Specifies the DCAP provider used for SGX attestation. For Azure deployments, set this value to azure.

8.3 Enrollment Configuration

Define the enrollment configuration for compute nodes joining the Fortanix Armor platform. This section controls the supported SGX types and the policies used to verify and authorize nodes during the enrollment process.

enrollment:
  allowedSgxTypes:
    - standard
    - scalableWithIntegrity
  joinPolicy:
    - node-ca
    - sgx

Where,

• allowedSgxTypes: Defines the SGX enclave types that are permitted during node enrollment.

  • standard: Supports standard SGX enclaves.

  • scalableWithIntegrity: Supports SGX scalable enclaves with integrity protection.

• joinPolicy: Defines the validation mechanisms used during node enrollment.

  • node-ca: Validates node certificates issued by the configured node CA.

  • sgx: Validates SGX attestation evidence during enrollment.

8.4 Database Configuration

Define the storage, topology, TLS, and backup configuration for the Cassandra database used by Fortanix Armor.

database:
  datacenters:
    - name: dc1
      size: 3
      racks:
        - name: rack1
          nodeAffinityLabels: {}

  replicationStrategy:
    dc1: 3

# Optional issuer used for internal TLS certificates
  issuerRef: selfsigned-cluster-issuer

  storageConfig:
    storageClassName: "managed-csi-retain"
    storageSize: "100Gi"

  backup:
    secret: medusa-azure-key-test
    bucketName: medusa
    prefix: platform
    schedule: "30 1 * * *"
    backupStorageProvider:
      kind: "azureBlobs"

    storageProvider:
      mode: azureBlobs

Where,

• datacenters: Defines the Cassandra cluster topology, including the number of nodes and rack configuration.

• racks: Defines logical grouping of nodes within a datacenter.

  • nodeAffinityLabels (optional): Specifies node selection constraints for Cassandra pods. If not provided, pods are scheduled on any available nodes in the cluster.

• replicationStrategy (optional): Defines the replication factor per datacenter. Defaults to the datacenter topology if not explicitly specified.

• issuerRef (optional): Specifies the cert-manager Issuer or ClusterIssuer used for internal TLS certificates between Cassandra nodes.

• storageConfig:  Defines storage settings for Cassandra.

  • storageClassName: Specifies the Kubernetes storage class used for persistent volumes.

  • storageSize: Specifies the size of the persistent volume allocated for Cassandra.

• backup (optional): Defines backup configuration for Cassandra.

  • secret: Specifies the credentials for backup storage.

  • bucketName: Specifies the storage bucket or container.

  • prefix: Specifies the prefix used for organizing backups.

  • schedule: Specifies the cron schedule for backups.

  • storageProvider.mode: Specifies the backup storage provider (currently supports azureBlobs).

For detailed instructions on Cassandra backup configuration and restore procedures, refer to Backup and Restore.

8.5 Ingress Configuration

Define the external access configuration for Fortanix Armor, including domain settings for generating the API certificate and Armor UI endpoint exposure.

ingress:
  api:
    certConfig:
      subject: "armor.onprem.fortanix.com"
      sans:
        - "armor.onprem.fortanix.com"
        - "api.armor.onprem.fortanix.com"

      # Optional (for cert-manager)
      # useCertManager:
      #   kind: issuer or clusterIssuer
      #   issuer: <issuer_name>
      #   duration: 2160h

      # Optional
      # signerName: "<signer-name>"
      # expirationSeconds: 7776000
      # extraAnnotations:
      #   key: "value"

    # Optional: Proxy Protocol configuration (advanced)
    # proxyProtocolConfig:
    #   mode: disabled or maybeFrom or requiredFrom
    #   subnets:
    #     - "1.2.3.0/24"

  staticAssets:
      baseUrl: "https://static.armor.onprem.fortanix.net"
      ingress:
        ingressKind: "nginx"
        extraAnnotations:
        ingressTlsSecretName: "armor-static-secret"
      # extraAnnotations:
      #   key: "value"

Where,

• certConfig: Defines the certificate configuration for the Fortanix Armor API domain.

  • subject: Specifies the primary domain used for the Fortanix Armor API certificate.

  • sans: Specifies the Subject Alternative Names (SANs) for the certificate. For mutual TLS configurations, at least one SAN must include the  api. prefix as described in the Section 13.0: Certificate Requirement for Mutual TLS.

  • useCertManager (optional): Specifies whether automated certificate provisioning using cert-manager is enabled.

    • kind: Specifies the issuer type (issuer or clusterIssuer).

    • issuer: Specifies the name of the configured cert-manager issuer.

    • duration (optional): Specifies the certificate validity period (default value is 2160 hours).

  • signerName (optional): Specifies the certificate signer to be used.

  • extraAnnotations (optional): Specifies additional annotations applied to the generated certificate resources (for example, for NGINX configuration).

  • expirationSeconds (optional): Specifies the validity period of the issued certificate.

• proxyProtocolConfig (optional): Defines proxy protocol handling for incoming connections.

  • mode: Specifies how Proxy Protocol headers are handled.

    • disabled: Proxy Protocol is not used.

    • maybeFrom: Proxy Protocol headers are accepted from configured subnets when present.

    • requiredFrom: Proxy Protocol headers are required from configured subnets.

  • subnets: Specifies the list of CIDR ranges from which Proxy Protocol headers are accepted.

• staticAssets: Defines the configuration for serving Fortanix Armor UI static content.

  • baseUrl: Specifies the public URL to access static UI assets.

  • Ingress: Defines how static assets are exposed using Kubernetes Ingress.

    • ingressKind: Specifies the ingress implementation used to expose static assets (for example, NGINX Ingress).

    • ingressTlsSecretName (optional): Specifies the ingress implementation used to expose static assets (for example, NGINX Ingress).

    • extraAnnotations (optional): Specifies annotations passed directly to the ingress resource. These may be used for ingress-controller-specific configuration such as NGINX directives or cert-manager integration.

NOTE

• The values defined in certConfig are used by the operator to generate a CSR.

• After applying the ArmorPlatform resource, wait for the operator to generate a CSR for the configured domain. Then proceed to Section 10.0: Install Certificates to complete certificate installation.

• Changing the configured Fortanix Armor domain after deployment may affect multi-factor authentication (MFA) for existing users. For more details, refer to Section 12.2: Sign Up and Log In.

8.6 Apply the Configuration

Perform the following steps to apply the ArmorPlatform configuration to the Kubernetes cluster to initiate Fortanix Armor deployment:

1. Download the YAML file armor-platform.yaml .

2. Run the following command to apply the custom resource:

   kubectl apply -f armor-platform.yaml

9.0 Create Load Balancer

• A load balancer is typically used to provide external access to Fortanix Armor.

• The load balancer forwards client traffic to the Kubernetes Service exposing the Fortanix Armor API, which listens on port 8443.

• A single externally accessible port is sufficient for all Fortanix Armor client traffic.

Example load balancer configuration (cloud):

apiVersion: v1
kind: Service
metadata:
  name: bargate-lb
  namespace: armor
  annotations:
    service.beta.kubernetes.io/azure-load-balancer-internal: "true"
spec:
  type: LoadBalancer
  ports:
  - name: https
    port: 443
    protocol: TCP
    targetPort: 8443
  selector:
    app: bargate

Where,

• <external-port>: The port exposed to clients (for example, 443).

• targetPort: Must be set to 8443, which is the port used by the Fortanix Armor API.

Run the following command to install the load balancer:

kubectl apply -f bargate_loadbalancer.yml 
kubectl get service bargate-lb

10.0 Install Certificates

The following sections show how to provision TLS certificates for the Armor UI and API endpoints.

10.1 Fortanix Armor Static UI Certificates

This section describes how to generate and install a TLS certificate for the Fortanix Armor static UI (frontend).

1. Run the following commands to generate a TLS key and CSR, and create a Kubernetes TLS secret for the Armor static UI endpoint:

   openssl genrsa -out static.key 2048
   openssl req -new -key static.key -out static.csr   -subj "/CN=static.armor.onprem.fortanix.net"

2. Submit the CSR and obtain the signed certificate. Run the following command to store the certificate:

   kubectl create secret tls armor-static-secret  --cert=keys/static.crt --key=keys/static.key -n armor

   Here, armor-static-secret is the secret ingressTlsSecretName created in Section 8.5: Ingress Configuration.

10.2 Fortanix Armor API Certificate

This section describes how to provision a TLS certificate for the Fortanix Armor API endpoint using a Kubernetes Certificate Signing Request (CSR).

1. Run the following command to list the CSR objects generated by the operator for Fortanix Armor:

   kubectl -n <namespace> get csr

   Where, <namespace> is the namespace where the Fortanix Armor platform components are deployed (for example, armor).

2. Identify the CSR generated for Fortanix Armor. Run the following command to extract the CSR content generated for the Armor API certificate from Kubernetes for signing by a CA.

   The certificate chain must include:

   • The signed certificate

   • Intermediate CA certificates (if applicable)

   • Root CA certificate

   The CSR name typically follows the format: fortanix-bargate-csr-<timestamp>

   CSR_NAME=<csr-name>
   
   kubectl get csr "$CSR_NAME" -o jsonpath='{.spec.request}' | base64 -d > "$CSR_NAME.csr"
   

   Where, <csr-name> is the name of the CSR generated for the Fortanix Armor API certificate.

3. Sign the extracted CSR using your organization’s CA and prepare the certificate chain.

   NOTE

   The exact steps for signing the certificate depend on your organization’s CA and security policies.

4. Run the following command to upload the signed certificate back to the Kubernetes cluster to complete the certificate installation process:

   BASE64=$(base64 -w 0 "${CSR_NAME}-full.crt")
   
   kubectl get csr "${CSR_NAME}" -o json | \
   jq ".status.certificate = \"$BASE64\"" | \
   kubectl replace --raw "/apis/certificates.k8s.io/v1/certificatesigningrequests/${CSR_NAME}/status" -f -
   

   Where, CSR_NAME is the name of the CSR generated for the Fortanix Armor API certificate (for example, fortanix-bargate-csr-<timestamp>). Ensure that this value matches the CSR name used in the previous steps.

5. Run the following command to approve the uploaded certificate:

   kubectl certificate approve fortanix-bargate-csr-1776774680

11.0 Configure System Administration Settings (Using Armor API)

To configure system administration settings using the Armor API, refer to System Management.

12.0 Access Fortanix Armor UI

This section describes how to access the Fortanix Armor user interface (UI) using the configured domain after successful deployment and verify that the platform is reachable.

12.1 Verify Fortanix Armor UI Accessibility

After successful deployment and certificate installation, verify that the Fortanix Armor UI is accessible.

Perform the following steps:

1. Visit the following URL to access the static assets endpoint:

   https://<static-assets-domain>

   Where, https://<static-assets-domain> corresponds to the staticAssetsBaseUrl configured in Section 8.5: Ingress Configuration.

   For example: https://static.onprem.fortanix.com

2. If prompted, accept the browser warning about the TLS certificate (when using self-signed certificates).

3. Access the Fortanix Armor UI: https://<armor-domain>. This domain corresponds to the certConfig.subject configured in Section 8.5: Ingress Configuration.

4. Confirm that the login page is displayed successfully.

12.2 Sign Up and Log In

Perform the following steps to sign up for Fortanix Armor:

1. Visit https://<armor-domain> and sign up.

   NOTE

   • The first user to sign up for Fortanix Armor and create an account automatically assumes the role of system administrator.

   • MFA device registrations are bound to the domain name through which the registration was performed. If the Fortanix Armor domain name is changed after users have registered MFA devices, those devices will no longer be valid for authentication using the new domain. Users may need to re-register their MFA devices after a domain change. Plan the production domain name carefully before onboarding users and enabling MFA.

2. Once you sign up, enter your email address and password, and click LOG IN.

   

12.3 Create and Select an Account

For detailed instructions to create an account, refer to Getting Started with Fortanix Armor.

12.4 References

To know the features available for Fortanix CCM on-premises deployments, refer to the Fortanix CCM Feature Support Matrix (SaaS vs On-premises).

To know the features available for Fortanix Key Insight on-premises deployments, refer to the Fortanix Key Insight Feature Support Matrix (SaaS vs On-premises).

13.0 Certificate Requirement for Mutual TLS

For connections that require mutual TLS (for example, Node Agent communication), the public certificate must include a SAN that begins with the following:

api.<your-domain>

NOTE

Ensure that the domain defined for mutual TLS aligns with the certificate configuration provided in Section 8.5: Ingress Configuration.