Install MinIO KMS on Upstream Kubernetes

MinIO KMS is licensed under the MinIO Software License.

This section documents steps for installing and managing MinIO Key Management Service (KMS) on Kubernetes infrastructure using a distribution that follows the upstream API and functionality.

This procedure assumes that the user interacting with the Kubernetes cluster has authorization to:

• Install Kubernetes operators and associated resources including CustomResourceDefinitions, Statefulsets, and secrets into new or existing namespaces and
• Perform operations as a user that has broad permissions to create resources within multiple namespaces.

This procedure documents installation on Kubernetes with the Helm Charts.

1. Add the AIStor Helm Repository

   helm repo add minio https://helm.min.io/
   

2. Configure and install the minio/minkms-operator chart

   This chart contains the necessary Kubernetes resources for deploying MinIO KMS resources through the minkms chart.

   To customize the chart, create a YAML manifest for the chart named minkms-operator-values.yaml. You must at least replace the LICENSE-STRING at global.license with your SUBNET license.

   license: "LICENSE-STRING"
   

   The operator chart supports hierarchical configuration where you can set values globally under global.operator.* that apply to all operators, then override specific values for individual operators under operators.<operator-name>.*. Individual operator settings take precedence over global settings. If you do not specify settings at either the individual or global level, then the operator uses the default settings value in the chart template. See Configuration Precedence for details.

3. Install the chart to the minkms-operator namespace:

   helm install minkms-operator minio/minkms-operator \
     -n minkms-operator --create-namespace \
     -f minkms-operator-values.yaml
   

   If successful, the command outputs a summary of installed resources.

   To validate the installation, run kubectl get all -n minkms-operator and check the status of deployed resources. The chart creates a Deployment, ReplicaSet, Service, and Pod within the namespace.

4. Generate a root encryption key for MinIO KMS

   MinIO KMS uses a Root Encryption Key (REK) for encrypting all stored cryptographic data. To generate a key, use the following command:

   docker run quay.io/minio/aistor/minkms:latest --soft-hsm
   

   The output resembles the following:

   hsm:ALGORITHM:<KEYSTRING>
   

   Save the output to a secure location such as a dedicated secrets manager or password vault.

5. Deploy the minio/minkms chart

   The following command deploys MinIO KMS with the name and namespace of minkms.

      helm install minkms minio/minkms \
        -n minkms --create-namespace \
        --set "minkms.hsm.key=hsm:ALGORITHM:<KEYSTRING>"
   

   Helm prints instructions for connecting a MinIO AIStor object store to MinIO KMS. The object store can then use MinIO KMS to enable server-side encryption of objects. A tool that installs the chart on your behalf, such as Argo CD, does not show those instructions. Connect an AIStor object store to MinIO KMS documents the same steps.

   By default, MinIO KMS deploys with 3 replicas. Each replica requires 25MiB of storage and uses the default storage class on the cluster. For more complete documentation, see Server Side Encryption with MinIO KMS.

Give the object store its own enclave, an admin identity within that enclave, and a default encryption key. Complete the steps in order. Each step produces a value the later steps need.

The commands below use the release name and namespace minkms from the procedure above. The Pod name follows the release name, and the service address follows the release name and the namespace. Adjust the Pod name and the address if you installed the chart with different values. On OpenShift, run oc in place of kubectl.

1. Obtain the admin API key

   Pass the root encryption key you generated earlier to the identity command. The command computes the key locally and does not contact the cluster.

   docker run --rm quay.io/minio/aistor/minkms:latest identity "hsm:ALGORITHM:KEYSTRING"
   

   The command prints an API key and the identity of that key. That API key is the admin API key, written below as ADMIN_API_KEY. The commands in steps 2 through 4 authenticate with it.

   This step applies when you passed a root encryption key through minkms.hsm.key. For the hardware security module (HSM) configurations MinIO KMS supports on Kubernetes, see HSM Management on Kubernetes.

2. Create an enclave for the object store

   An enclave isolates a group of keys and identities from every other enclave. Give the object store one of its own.

   kubectl exec -n minkms minkms-0 -- \
     /minkms add-enclave --api-key ADMIN_API_KEY ENCLAVE_NAME
   

3. Create an admin identity within that enclave

   The object store uses this identity to manage its own keys.

   kubectl exec -n minkms minkms-0 -- \
     /minkms add-identity --api-key ADMIN_API_KEY --enclave ENCLAVE_NAME --admin
   

   The command prints a second API key and its identity. This one is the enclave API key, and it is not the same value as ADMIN_API_KEY.

   Record the enclave API key now. The command prints it once at creation. The server never stores it and cannot show it again.

4. Create the default server-side encryption key

   The object store uses this key to encrypt object data.

   kubectl exec -n minkms minkms-0 -- \
     /minkms add-key --api-key ADMIN_API_KEY --enclave ENCLAVE_NAME SSE_KEY_NAME
   

5. Create the object store

   Create the AIStor object store with the following environment variables. An object store that already exists needs the same variables.

   Environment Variable	Value
   MINIO_KMS_SERVER	https://minkms-minkms.minkms.svc.cluster.local:7373
   MINIO_KMS_ENCLAVE	The enclave name from step 2
   MINIO_KMS_API_KEY	The enclave API key from step 3, not the admin API key from step 1
   MINIO_KMS_SSE_KEY	The encryption key name from step 4