awatertrevi/infisical
1
0
Fork 0
mirror of https://github.com/awatertrevi/infisical.git synced 2026-10-12 12:29:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(hsm): kubernetes deployment docs

Browse Source
This commit is contained in:
Daniel Hougaard
2025-03-19 23:02:39 +04:00
parent ec31211bca
commit 15999daa24
1 changed files with 417 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/documentation/platform/kms/hsm-integration.mdx
+288 -3
View File
@@ -66,7 +66,7 @@ For organizations that work with US government agencies, FIPS compliance is almo
<Step title="Configure HSM on Infisical"> <Step title="Configure HSM on Infisical">
<Warning> <Warning>
Are you using Docker? If you are using Docker, please follow the instructions in the [Using HSM's with Docker](#using-hsms-with-docker) section. Are you using Docker or Kubernetes for your deployment? If you are using Docker or Kubernetes, please follow the instructions in the [Using HSM's in your Deployment](#using-hsms-in-your-deployment) section.
</Warning> </Warning>
Configuring the HSM on Infisical requires setting a set of environment variables: Configuring the HSM on Infisical requires setting a set of environment variables:
@@ -94,9 +94,13 @@ For organizations that work with US government agencies, FIPS compliance is almo
</Steps> </Steps>
## Using HSMs with Docker ## Using HSMs In Your Deployment
When using Docker, you need to mount the path containing the HSM client files. This section covers how to configure your Infisical instance to use an HSM with Docker.
<Tabs> <Tabs>
<Tab title="Docker">
When using Docker, you need to mount the path containing the HSM client files. This section covers how to configure your Infisical instance to use an HSM with Docker.
<Tabs>
<Tab title="Thales Luna Cloud HSM"> <Tab title="Thales Luna Cloud HSM">
<Steps> <Steps>
<Step title="Create HSM client folder"> <Step title="Create HSM client folder">
@@ -251,8 +255,289 @@ When using Docker, you need to mount the path containing the HSM client files. T
</Steps> </Steps>
After following these steps, your Docker setup will be ready to use HSM encryption. After following these steps, your Docker setup will be ready to use HSM encryption.
</Tab> </Tab>
</Tabs>
</Tab>
<Tab title="Kubernetes">
When you are deploying Infisical with the [Kubernetes self-hosting option](/self-hosting/deployment-options/kubernetes-helm), you can still use HSM encryption, but you need to ensure that the HSM client files are present in the container.
<Tabs>
<Tab title="Thales Luna Cloud HSM">
<Note>
This is only supported on helm chart version `1.4.1` and above. Please see the [Helm Chart Changelog](https://github.com/Infisical/infisical/blob/main/helm-charts/infisical-standalone-postgres/CHANGELOG.md#141-march-19-2025) for more information.
</Note>
<Steps>
<Step title="Create HSM client folder">
When using Kubernetes, you need to mount the path containing the HSM client files. This section covers how to configure your Infisical instance to use an HSM with Kubernetes.
```bash
mkdir /etc/hsm-client
```
After [setting up your Luna Cloud HSM client](https://thalesdocs.com/gphsm/luna/7/docs/network/Content/install/client_install/add_dpod.htm), you should have a set of files, referred to as the HSM client. You don't need all the files, but for simplicity we recommend copying all the files from the client.
A folder structure of a client folder will often look like this:
```
partition-ca-certificate.pem
partition-certificate.pem
server-certificate.pem
Chrystoki.conf
/plugins
libcloud.plugin
/lock
/libs
/64
libCryptoki2.so
/jsp
LunaProvider.jar
/64
libLunaAPI.so
/etc
openssl.cnf
/bin
/64
ckdemo
lunacm
multitoken
vtl
```
The most important parts of the client folder is the `Chrystoki.conf` file, and the `libs`, `plugins`, and `jsp` folders. You need to copy these files to the folder you created in the first step.
```bash
cp -r /<path-to-where-your-hsm-client-is-located> /etc/hsm-client
```
</Step>
<Step title="Update Chrystoki.conf">
The `Chrystoki.conf` file is used to configure the HSM client. You need to update the `Chrystoki.conf` file to point to the correct file paths.
In this example, we will be mounting the `/etc/hsm-client` folder to the Kubernetes deployment under a different path. The path we will use in this example is `/hsm-client`. This means `/etc/hsm-client` will be mounted to `/hsm-client` in the Kubernetes deployment.
An example config file will look like this:
```Chrystoki.conf
Chrystoki2 = {
# This path points to the mounted path, /hsm-client
LibUNIX64 = /hsm-client/libs/64/libCryptoki2.so;
}
Luna = {
DefaultTimeOut = 500000;
PEDTimeout1 = 100000;
PEDTimeout2 = 200000;
PEDTimeout3 = 20000;
KeypairGenTimeOut = 2700000;
CloningCommandTimeOut = 300000;
CommandTimeOutPedSet = 720000;
}
CardReader = {
LunaG5Slots = 0;
RemoteCommand = 1;
}
Misc = {
# Update the paths to point to the mounted path if your folder structure is different from the one mentioned in the previous step.
PluginModuleDir = /hsm-client/plugins;
MutexFolder = /hsm-client/lock;
PE1746Enabled = 1;
ToolsDir = /usr/bin;
}
Presentation = {
ShowEmptySlots = no;
}
LunaSA Client = {
ReceiveTimeout = 20000;
# Update the paths to point to the mounted path if your folder structure is different from the one mentioned in the previous step.
SSLConfigFile = /hsm-client/etc/openssl.cnf;
ClientPrivKeyFile = ./etc/ClientNameKey.pem;
ClientCertFile = ./etc/ClientNameCert.pem;
ServerCAFile = ./etc/CAFile.pem;
NetClient = 1;
TCPKeepAlive = 1;
}
REST = {
AppLogLevel = error
ServerName = <REDACTED>;
ServerPort = 443;
AuthTokenConfigURI = <REDACTED>;
AuthTokenClientId = <REDACTED>;
AuthTokenClientSecret = <REDACTED>;
RestClient = 1;
ClientTimeoutSec = 120;
ClientPoolSize = 32;
ClientEofRetryCount = 15;
ClientConnectRetryCount = 900;
ClientConnectIntervalMs = 1000;
}
XTC = {
Enabled = 1;
TimeoutSec = 600;
}
```
Save the file after updating the paths.
</Step>
<Step title="Creating Persistent Volume Claim (PVC)">
You need to create a Persistent Volume Claim (PVC) to mount the HSM client files to the Infisical deployment.
```bash
kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: infisical-data-pvc
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 500Mi
EOF
```
The above command will create a PVC named `infisical-data-pvc` with a storage size of `500Mi`. You can change the storage size if needed.
Next we need to create a temporary pod to upload the HSM client files to the PVC.
```bash
kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
name: hsm-setup-pod
spec:
containers:
- name: setup
image: busybox
command: ["/bin/sh", "-c", "sleep 3600"]
volumeMounts:
- name: hsm-data
mountPath: /data
volumes:
- name: hsm-data
persistentVolumeClaim:
claimName: infisical-data-pvc
EOF
```
The above command will create a pod named `hsm-setup-pod` with a busybox image. The pod will sleep for 3600 seconds _(one hour)_, which is enough time to upload the HSM client files to the PVC.
Ensure that the pod is running and is healthy by running the following command:
```bash
kubectl wait --for=condition=Ready pod/hsm-setup-pod --timeout=60s
```
Next we need to copy the HSM client files into the PVC.
```bash
kubectl exec hsm-setup-pod -- mkdir -p /data/ # Create the data directory
kubectl cp ./hsm-client/ hsm-setup-pod:/data/ # Copy the HSM client files into the PVC
kubectl exec hsm-setup-pod -- chmod -R 755 /data/ # Set the correct permissions for the HSM client files
```
Finally, we are ready to delete the temporary pod, as we have successfully uploaded the HSM client files to the PVC. This step may take a few minutes to complete.
```bash
kubectl delete pod hsm-setup-pod
```
</Step>
<Step title="Updating your environment variables">
Next we need to update the environment variables used for the deployment. If you followed the [setup instructions for Kubernetes deployments](/self-hosting/deployment-options/kubernetes-helm), you should have a Kubernetes secret called `infisical-secrets`.
We need to update the secret with the following environment variables:
- `HSM_LIB_PATH` - The path to the HSM client library _(mapped to `/hsm-client/libs/64/libCryptoki2.so`)_
- `HSM_PIN` - The PIN for the HSM device that you created when setting up your Luna Cloud HSM client
- `HSM_SLOT` - The slot number for the HSM device that you selected when setting up your Luna Cloud HSM client
- `HSM_KEY_LABEL` - The label for the HSM key. If no key is found with the provided key label, the HSM will create a new key with the provided label.
The following is an example of the secret that you should update:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: infisical-secrets
type: Opaque
stringData:
# ... Other environment variables ...
HSM_LIB_PATH: "/hsm-client/libs/64/libCryptoki2.so" # If you followed this guide, this will be the path of the Luna Cloud HSM client
HSM_PIN: "<your-hsm-device-pin>"
HSM_SLOT: "<hsm-device-slot>"
HSM_KEY_LABEL: "<your-key-label>"
```
Save the file after updating the environment variables, and apply the secret changes
```bash
kubectl apply -f ./secret-file-name.yaml
```
</Step>
<Step title="Updating the Deployment">
After we've successfully configured the PVC and updated our environment variables, we are ready to update the deployment so it can access the HSM client files.
We need to update the Docker image of the deployment to use `infisical/infisical-fips`. The `infisical/infisical-fips` image is a functionally identical image to the `infisical/infisical` image, but it is built with support for HSM encryption.
The image has the same versions as the `infisical/infisical` image, so you don't need to worry about changing the version of the Infisical instance.
```yaml
# ... The rest of the values.yaml file ...
image:
repository: infisical/infisical-fips # Very important: Must use "infisical/infisical-fips"
tag: "v0.117.1-postgres"
pullPolicy: IfNotPresent
extraVolumeMounts:
- name: hsm-data
mountPath: /hsm-client # The path we will mount the HSM client files to
subPath: ./hsm-client
extraVolumes:
- name: hsm-data
persistentVolumeClaim:
claimName: infisical-data-pvc # The PVC we created in the previous step
# ... The rest of the values.yaml file ...
```
</Step>
<Step title="Upgrading the Helm Chart">
After updating the values.yaml file, you need to upgrade the Helm chart in order for the changes to take effect.
```bash
helm upgrade --install infisical infisical-helm-charts/infisical-standalone --values /path/to/values.yaml
```
</Step>
<Step title="Restarting the Deployment">
After upgrading the Helm chart, you need to restart the deployment in order for the changes to take effect.
```bash
kubectl rollout restart deployment/infisical-infisical
```
</Step>
</Steps>
After following these steps, your Kubernetes setup will be ready to use HSM encryption.
</Tab>
</Tabs>
</Tab>
</Tabs> </Tabs>
## Disabling HSM Encryption ## Disabling HSM Encryption
To disable HSM encryption, navigate to Infisical's Server Admin Console and set the KMS encryption strategy to `Software-based Encryption`. This will revert the encryption strategy back to the default software-based encryption. To disable HSM encryption, navigate to Infisical's Server Admin Console and set the KMS encryption strategy to `Software-based Encryption`. This will revert the encryption strategy back to the default software-based encryption.