Install

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. You also need access to enclaive repository to download the precompiled binary. Contact support to get an enterprise licence.

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

Docker

1. Login to the enclaive repository and enter user and password: docker login harbor.enclaive.cloud

The output is similar to:

Username: <username>
Password: <password>
Login Succeeded 

1. Pull the latest image: docker pull harbor.enclaive.cloud/enclaive-dev/vhsm:latest

2. Set the enterprise license key that you received as an environment variable: export ENCLAIVE_LICENCE=<licence-key>

3. Start a docker container named vhsm-containerwith 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/enclaive-dev/vhsm:latest

1. Check if the container is running:docker ps

2. 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!

1. 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.

2. You can now go to a browser and access vHSM ui at: http://127.0.0.1:8200/

Kubernetes

1. Login to the enclaive repository and enter user and password:

helm registry login harbor.enclaive.cloud

The output is similar to:

Username: <username>
Password: <password>
Login Succeeded 

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

export ENCLAIVE_LICENCE=<licence-key>

1. Install vHSM in the Kubernetes cluster using helm.

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

The output is similar to:

Pulled: harbor.enclaive.cloud/enclaive-dev/vhsm:0.28.1
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

1. 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

1. 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

1. Port forwad the service to access VHSM ui: kubectl port-forward svc/vhsm 8200:8200 8201:8201

2. 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>

Compile from source

Prerequisites

Ensure that you have the following installed and properly configured:

• Go with the GOPATH environment variable set

• Git available in your system's PATH

• Set the enterprise license key that you received as an environment variable: export ENCLAIVE_LICENCE=<licence-key>

To compile vHSM from source.

1. Navigate to your GOPATH and create the necessary directory structure:

   mkdir -p $GOPATH/src/github.com/enclaive && cd $_

2. Clone the vHSM repository from GitHub:

   git clone https://github.com/enclaive/vhsm.git

3. Navigate into the cloned repository:

   cd vhsm

4. Bootstrap the project to download and compile the required libraries and tools for building vHSM.

   make bootstrap

5. Build vHSM for your current system and place the binary in the ./bin/ directory:

   make dev

6. If you need to build vHSM with the UI, use:

   make dev-ui

7. Check if vHSM is installed: vhsm -h

If you receive an error stating that vhsm is not found, ensure that the binary is in your system’s PATH. You can add it temporarily with:

export PATH=$GOPATH/src/github.com/enclaive/vhsm/bin:$PATH

1. 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.

2. You can now go to a browser and access vHSM ui at: http://127.0.0.1:8200/

AWS Marketplace

Prerequisites

• Create a EC2 instance and ensure that the Instance type is one of these supported configurations.
• Ensure your EC2 instance has proper IAM permissions to pull images from ECR.
• Make sure your EC2 instance's security group allows communication on the required ports.

• Depending on your setup, you may need to expose specific ports for accessing services within the container.

To install and run the vhsm-aws container from Amazon ECR on your EC2 instance, follow these steps:

1. Connect to your EC2 instance.

Install and configure Docker on your EC2 instance.

sudo apt update
sudo apt install docker.io

2. Install AWS CLI on your EC2 instance.

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

3. Configure AWS credentials.

aws configure

where

• AWS Access Key ID: (Get from your AWS IAM)

• AWS Secret Access Key: (Get from your AWS IAM)

• Default region name: us-east-1 (or the region you are using)

• Default output format: Leave it as None

4. Authenticate Docker to Amazon ECR registry where the vhsm container image is stored.

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 709825985650.dkr.ecr.us-east-1.amazonaws.com

5. Pull the vhsm-aws image from ECR.

For example, to pull the image tagged as 1.4.1-0:

docker pull 709825985650.dkr.ecr.us-east-1.amazonaws.com/enclaive/vhsm:1.4.1-0

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

Downloading the CLI

To interact with vHSM you can use the Hashicorp Vault CLI or enclaive vHSM CLI.

enclaive vHSM CLI

Download the Linux CLI from the vHSM server

wget https://vhsm.enclaive.cloud/static/vhsm

Hashicorp Vault CLI

To ensure easy compatibility, enclaive vHSM inntegrates seamlessly with the HashiCorp Vault CLI. Follow the instructions in the Official Packaging Guide to install the HashiCorp GPG key, verify the key's fingerprint, and install Vault.

Ubuntu/Debian

Update the package manager and install GPG and wget.

sudo apt update && sudo apt install gpg wget

Download the keyring

wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg

Verify the keyring

gpg --no-default-keyring --keyring /usr/share/keyrings/hashicorp-archive-keyring.gpg --fingerprint

Add the HashiCorp repository.

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list

Install Vault.

sudo apt update && sudo apt install vault

Fedora

Install dnf config-manager to manage your repositories.

sudo dnf install -y dnf-plugins-core

Use dnf config-manager to add the official HashiCorp Linux repository.

sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/fedora/hashicorp.repo

Install Vault.

sudo dnf -y install vault

Amazon Linux

Install yum-config-manager to manage your repositories.

$ sudo yum install -y yum-utils

Use yum-config-manager to add the official HashiCorp Linux repository.

$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo

Install Vault.

$ sudo yum -y install vault