Install on Kubernetes

The installer script deploys the Securosys Key Manager to a Kubernetes cluster using Helm. It prompts you for the values required to reach the TSB and installs the charts. Runtime settings such as OAuth, TOTP and Notifications are configured in the Key Manager UI after installation.

The installer supports minikube, k3s, EKS, GKE, AKS, and any standard Kubernetes cluster. It requires helm, kubectl, openssl, and curl on the machine it runs on.

Linux

curl -fsSL https://dlarea.securosys.com/software/kms/install_k8s.sh | bash

macOS (Homebrew Bash)

curl -fsSL https://dlarea.securosys.com/software/kms/install_k8s.sh | /opt/homebrew/bin/bash

Offline (Linux)

The following command stages the Helm charts, the container images (as tar-files), and the installer itself for later offline installation.

curl -fsSL https://dlarea.securosys.com/software/kms/install_k8s.sh | bash -s -- fetch-resources-for-offline-installation

Copy the staged resources/ directory to the target site, then load the images into a registry your cluster can reach. Unlike Docker, Kubernetes nodes pull images from a registry, so a site-local registry is required; single-node minikube is the exception (minikube image load <image.tar>).

Run the installer in offline mode, pointing it at your registry and the staged charts:

KMS_IMAGE_REGISTRY=<your-registry> OFFLINE=true ./install_k8s.sh --dir <dir-with-the-chart-archives>

Installation Overview

The installer proceeds in four main steps:

1. Check the environment. The installer checks that the required tools are present, asks which kubectl context and namespace to deploy to, and logs in to the Securosys registry (chart pulls and the image pull Secret).
2. Request configuration details. The installer prompts you to choose the TSB deployment mode (see below) and the optional services. It then prompts you for the necessary details to connect to the TSB or HSM.
3. Write configuration and deploy backing services. The installer generates the Helm values files and Kubernetes Secrets, pulls the pinned chart versions, and deploys the backing releases as needed: PostgreSQL, an on-prem TSB, and the KMIP Server.
4. Install the KMS. Optionally, the installer installs the KMS chart and runs health checks. It also creates the keymanager-k8s CLI for all later operation tasks.

The installer can be rerun at any time to apply configuration changes and regenerate the values files. It records its answers in kms-install.env (secrets excluded, they live in Kubernetes Secrets) and prompts only for values that are not already set.

Cluster Selection

Every run asks which kubectl context to target; minikube is the default when present. If minikube is installed but not running, the installer offers to start a local cluster. The selection applies to the current installer run only (your kubeconfig current-context is not changed). The namespace is prompted for and created when missing.

TSB Deployment Mode

The Key Manager never talks to the HSM directly. All cryptographic operations are routed through the Transaction Security Broker (TSB), which translates REST to JCE, as described in the KMS architecture. A TSB with the REST_API license is therefore mandatory for every deployment.

When deploying a TSB, the following modes are available. The installer asks you to choose between them.

Mode	HSM	TSB	Required installer input
cloud	Securosys CloudHSM	Hosted by Securosys	TSB URL, valid TSB access token (JWT)
onprem	On-premise Primus HSM	TSB and its PostgreSQL database are deployed into the cluster by the installer	HSM host, JCE port, Partition name and Setup Password

tip

To use an already-running TSB instead of deploying one, set TSB_ONPREM_DEPLOY=false together with its TSB_API_URL in the kms-install.env file.

Service Selection

Some services are optional. The installer asks you which services you want to deploy.

• Minimum services (installed by default): envoy, dashboard, auth, keycore and possibly tsb
• Optional services (no additional license required): mcp, discovery, compliance
• Optional services (additional license required): kmip (see KMIP Server Installation)

The selection can be changed later with keymanager-k8s services.

Installer Options

Setting an environment variable before running the installer skips the corresponding prompt, which enables unattended installation.

TSB_API_URL=https://my-tsb.example.com TSB_ACCESS_TOKEN=xxx ./install_k8s.sh

Variable	Purpose
INSTALL_DIR	Working directory for charts and values files. Alias --dir
INSTALL_MODE=auto	Non-interactive install using all defaults, requires TSB_ACCESS_TOKEN
KUBE_CONTEXT	kubectl context to deploy to. Alias --context
NAMESPACE	Kubernetes namespace. Alias --namespace/-n
RELEASE_NAME	Helm release name of the KMS (kms)
TSB_API_URL, TSB_ACCESS_TOKEN	Cloud TSB endpoint and token
KMS_IMAGE_REGISTRY, KMS_IMAGE_TAG	Image registry and tag override for all KMS services. Alias --tag
KMS_IMAGE_PULL_POLICY	Always, IfNotPresent or Never for every KMS container, also available as --pull-policy
OFFLINE=true	Force offline mode and skip the connectivity probe
RESOURCE_DIR	Directory holding pre-staged installation resources
KMS_AUTO_INIT=false	Leave the KMS sealed instead of initializing it
INSTALL_VERBOSE=1	Verbose installer output

On-Prem TSB Variables

In onprem mode, the HSM connection prompts correspond to the following variables.

Variable	Prompt	Default
TSB_HSM_HOST	HSM hosts, IP address or DNS name, comma-separated	required
TSB_HSM_JCE_PORT	HSM JCE port	2300
TSB_HSM_USERNAME	HSM User/Partition name	required
TSB_HSM_SETUP_PASSWORD	HSM Setup Password	required
TSB_HSM_PROXY_USERNAME, TSB_HSM_PROXY_PASSWORD	HSM proxy credentials, only requested for Securosys CloudHSM	empty

All HSM values can instead be read from a Securosys Cloud Console Connection Configuration block, which skips their prompts:

./install_k8s.sh --hsm-config cloudhsm.txt

Additional on-prem TSB instances are onboarded after installation with keymanager-k8s add-tsb.

Network Access

The installer does not bind host ports; the services are exposed through Kubernetes Services.

• On minikube, the envoy gateway is a NodePort Service; the installer prints the dashboard URL (minikube service kms-envoy --url -n <namespace>).
• On other clusters, envoy is a ClusterIP Service; expose it with your Ingress or LoadBalancer of choice (kubectl get svc kms-envoy -n <namespace>).
• Dashboard TLS is controlled with ENVOY_TLS_MODE (disabled, self-signed, or provided together with ENVOY_TLS_PROVIDED_CERT/ENVOY_TLS_PROVIDED_KEY). The certificate is renewed with keymanager-k8s tls-rotate.
• The KMIP Server listens on port 5696 on its own ClusterIP Service.

Result

Once the installer completes, it has:

• Created the keymanager-k8s script used for all operation tasks.
• Written the values files and kms-install.env, and created the Kubernetes Secrets holding the credentials.
• Pulled the pinned Helm charts and (optionally) installed the releases.
• Printed the dashboard URL of the Key Manager.

Open the dashboard and complete the Initial Wizard.

Directory Structure

The installation directory should now look as follows:

.
├── kms-install.env              # installation record, read back on reruns (no secrets)
├── values-kms.yaml              # cluster profile overlay, rewritten on every rerun
├── values-kms-config.yaml       # resolved configuration overlay, rewritten on every rerun
├── values-tsb-onprem.yaml       # on-prem TSB only
├── values-tsb-postgresql.yaml   # on-prem TSB only
├── values-kmip.yaml             # KMIP Server only
├── kms-<version>.tgz            # pinned chart archives (also tsb, psql, kmip)
├── keymanager-k8s               # operator CLI
└── resources                    # input for offline installation

info

Unlike the Docker installation, no credentials are written to disk: HSM, database, and TSB credentials live in Kubernetes Secrets in the target namespace. The values files are only overlays over the chart defaults; inspect the effective configuration with helm get values kms -n <namespace> --all.

Troubleshooting

Check the deployment state and service health at any time:

./install_k8s.sh status

Inspect a failing service with keymanager-k8s logs <service>, for example keymanager-k8s logs auth or keymanager-k8s logs kmip-server.

The installer is idempotent: after fixing the cause, rerun it and it continues with the recorded configuration, re-prompting only for missing values.