Install vHSM on Red Hat OpenShift

Red Hat's OpenShift is a distribution of the Kubernetes platform that provides a number of usability and security enhancements

In this tutorial, you login to an OpenShift cluster, install Vault via the Helm chart and then configure the authentication between Vault and the cluster. Then you deploy two web applications. One that authenticates and requests secrets directly from the Vault server. The other that employs deployment annotations that enable it to remain Vault unaware.

Prerequisites

• RedHat OpenShift Local

• OpenShift command-line interface(CLI)

• Helm CLI

1. Verify the RedHat OpenShift Local version.

   $ crc version
   CRC version: 2.54.0+5d2dd4
   OpenShift version: 4.19.8
   MicroShift version: 4.19.7

2. Verify the Helm version.

   $ helm version
   version.BuildInfo{Version:"v3.17.1", GitCommit:"980d8ac1939e39138101364400756af2bdee1da5", GitTreeState:"clean", GoVersion:"go1.23.6"}

   These are recommended software versions and the output displayed may vary depending on your environment and the software versions you use.

Configure and start the OpenShift cluster

RedHat OpenShift Local provisions and manages the lifecycle of OpenShift clusters running on your local system.

1. Configure RedHat OpenShift Local.

   $ crc setup

2. Start the OpenShift cluster and enter the pull secret.

   $ crc start
   INFO 2 operators are progressing: image-registry, operator-lifecycle-manager-packageserver 
   INFO Operator operator-lifecycle-manager-packageserver is progressing 
   INFO All operators are available. Ensuring stability... 
   INFO Operators are stable (2/3)...                
   INFO Operators are stable (3/3)...                
   INFO Adding crc-admin and crc-developer contexts to kubeconfig... 
   Started the OpenShift cluster.
   
   The server is accessible via web console at:
     https://console-openshift-console.apps-crc.testing
   
   Log in as administrator:
     Username: kubeadmin
     Password: LFHFk-gd8no-dSKnM-WFhd5
   
   Log in as user:
     Username: developer
     Password: developer
   
   Use the 'oc' command line interface:
     $ eval $(crc oc-env)
     $ oc login -u developer https://api.crc.testing:6443

   This secret is generated and stored in your Red Hat account.

   The cluster starts and describes how to setup the environment and login as an administrator.

3. Apply the oc-env into the current shell session.

   $ eval $(crc oc-env)

   The OpenShift CLI is accessed using the command oc. From here, you can administrate the entire OpenShift cluster and deploy new applications. The CLI exposes the underlying Kubernetes orchestration system with the enhancements made by OpenShift.

4. Login to the OpenShift cluster with as the user admin with the command provided by the crc start command. Replace the user (-u), password (-p), and URL with the values from the crc start` command.

   Example:

   $ oc login -u kubeadmin -p LFHFk-gd8no-dSKnM-WFhd5 https://api.crc.testing:6443
   ##...
   Login successful.
   
   You have access to 57 projects, the list has been suppressed. You can list all projects with 'oc projects'
   
   Using project "default".

   The output displays that you are logged in as an admin within the default project.

Install the vHSM Helm chart

The recommended way to run vHSM on OpenShift using the Helm chart. Helm is a package manager that installs and configures all the necessary components to run vHSM in several different modes. To install vHSM using Helm chart in the next step requires that you are logged in as administrator within a project.

1. Add the enclaive vHSM Helm repository.

   $ export ENCLAIVE_LICENCE=435bd99b-6929-47da-9477-462a141f14d5

2. Update all the repositories to ensure helm is aware of the latest versions.

   $ helm repo update
   Hang tight while we grab the latest from your chart repositories...
   ...Successfully got an update from the "hashicorp" chart repository
   Update Complete. ⎈Happy Helming!⎈

3. Install the latest version of the Vault server running in development mode configured to work with OpenShift.

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

   Example output:

   NAME: vhsm
   LAST DEPLOYED: Thu Oct  2 18:13:42 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
   vHSM with Kubernetes available here:
   
   https://docs.enclaive.cloud/virtual-hsm
   
   
   Your release is named vhsm1. To learn more about the release, try:
   
     $ helm status vhsm
     $ helm get manifest vhsm

   The vhsm Pod is deployed in the default namespace.

4. Display all the pods within the default namespace.

   $ oc get pods
   NAME      READY   STATUS             RESTARTS   AGE
   vhsm-0    1/1     ImagePullBackOff   2          2d23h

   The vhsm-0 pod runs a vHSM server in development mode.

   Wait until the vault-0 Pod is running and ready (1/1).