Server

Install vHSM to effectively managing identities and access controls for workloads spread across multiple clouds and on-premises environments

Installing vHSM

Note: To install vHSM you need an enterprise licence. Contact support to get an enterprise licence.

Note: To install vHSM as a production server you need to create a `config.json` file. For more information, see Configuration.

You can install vHSM using a docker image, helm chart, or compile from source

Pull the latest image: docker pull harbor.enclaive.cloud/vhsm/vhsm:latest
Set the enterprise license key that you received as an environment variable: export ENCLAIVE_LICENCE=<licence-key>
Start a docker container named vhsm-container with the image that you pulled:

docker run -d --name vhsm-container -p 8200:8200 -p 8201:8201 -e ENCLAIVE_LICENCE="$ENCLAIVE_LICENCE" harbor.enclaive.cloud/vhsm/vhsm:latest

Check if the container is running: docker ps
Access the logs of the container to get the environment variable, unseal key, and root token details.

The output is similar to:


WARNING! dev mode is enabled! In this mode, vHSM runs entirely in-memory
and starts unsealed with a single unseal key. The root token is already
authenticated to the CLI, so you can immediately begin using Vault.

You may need to set the following environment variables:

    $ export VAULT_ADDR='http://0.0.0.0:8200'

The unseal key and root token are displayed below in case you want to
seal/unseal the vHSM or re-authenticate.

Unseal Key: pafYkq2uEVve3FW7n7RM6JUK/MWEHzAxvrEdlrb4QD4=
Root Token: hvs.7oXsG8t8L198HEpB865FdpFG

Development mode should NOT be used in production installations!

Set the environment variables for accessing vHSM. Save the unseal key, and the root token. You will need these key, and token to access the vHSM UI.
You can now go to a browser and access vHSM ui at: http://127.0.0.1:8200/

Set the enterprise license key that you received as an environment variable.

export ENCLAIVE_LICENCE=<licence-key>

Install vHSM in the Kubernetes cluster using helm.

helm install vhsm oci://harbor.enclaive.cloud/vhsm/vhsm \
  --version 0.29.0 \
  --set injector.enabled=false \
  --set server.extraEnvironmentVars.ENCLAIVE_LICENCE="$ENCLAIVE_LICENCE"

The output is similar to:

Pulled: harbor.enclaive.cloud/enclaive-dev/vhsm:0.29.0
Digest: sha256:d10c10f013efbff0275c33b5c292dd442017c85406aecebf8dc19a2302bf43af
NAME: vhsm
LAST DEPLOYED: Fri Feb 21 19:11:59 2025
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
Thank you for installing Enclaive vHSM!

Now that you have deployed vHSM, you should look over the docs on using
Vault with Kubernetes available here:

https://docs.enclaive.cloud/virtual-hsm


Your release is named vhsm. To learn more about the release, try:

  $ helm status vhsm
  $ helm get manifest vhsm

Check if the Pods are running in the Kubernetes cluster: kubectl get pods The output is similar to:

NAME     READY   STATUS    RESTARTS   AGE
vhsm-0   0/1     Running   0          78s

Check if the services are running: kubectl get svc

The output is similar to:

NAME            TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)             AGE
kubernetes      ClusterIP   10.96.0.1       <none>        443/TCP             13m
vhsm            ClusterIP   10.96.219.177   <none>        8200/TCP,8201/TCP   90s
vhsm-internal   ClusterIP   None            <none>        8200/TCP,8201/TCP   90s

Port forwad the service to access VHSM ui: kubectl port-forward svc/vhsm 8200:8200 8201:8201
You can now go to a browser and access vHSM ui at: http://127.0.0.1:8200/

Note: The vHSM is not initialized, and unsealed by default. You are prompted to initialize and unseal the vHSM. Initialize the VHSM using the command vhsm operator init and then unseal vHSM using the unseal keys by using the command vhsm operator unseal <unsealkey>

Create a docker-compose.yaml

version: "3.8"

services:
  vhsm:
    image: harbor.enclaive.cloud/vhsm/vhsm:latest
    container_name: vhsm-container
    environment:
      - ENCLAIVE_LICENCE=${ENCLAIVE_LICENCE}
    ports:
      - "8200:8200"
      - "8201:8201"
    restart: unless-stopped

2. Set your license key as an environment variable

export ENCLAIVE_LICENCE=<licence-key>

Alternatively, you can create a .env file in the same folder as your compose file with this variable inside:

ENCLAIVE_LICENCE=<licence-key>

Docker Compose will automatically pick it up.

3. Start vHSM with Docker Compose

docker compose up -d

Check if the container is running

docker compose ps

View logs for unseal key and root token

docker compose logs -f vhsm

The output is similar to :

WARNING! dev mode is enabled! In this mode, vHSM runs entirely in-memory
and starts unsealed with a single unseal key. The root token is already
authenticated to the CLI, so you can immediately begin using Vault.

You may need to set the following environment variables:

    $ export VAULT_ADDR='http://0.0.0.0:8200'

The unseal key and root token are displayed below in case you want to
seal/unseal the vHSM or re-authenticate.

Unseal Key: pafYkq2uEVve3FW7n7RM6JUK/MWEHzAxvrEdlrb4QD4=
Root Token: hvs.7oXsG8t8L198HEpB865FdpFG

Development mode should NOT be used in production installations!

Set the environment variables for accessing vHSM. Save the unseal key, and the root token. You will need these key, and token to access the vHSM UI.
You can now go to a browser and access vHSM ui at: http://127.0.0.1:8200/

PreviousInstallation NextCLI

Last updated 2 months ago

Was this helpful?