Install MinIO KMS on OpenShift

MinIO KMS is licensed under the MinIO Software License.

This page documents the installation and management of MinIO Key Management Service (KMS) using MinIO’s Red Hat OpenShift-certified operator. You can alternatively install MinIO KMS using our Helm charts.

This procedure assumes that the user interacting with the OpenShift cluster has authorization to perform the following tasks:

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

This section installs the OpenShift certified operator. You must complete this section before proceeding to deploying MinIO KMS.

As an alternative to the procedure below, you can install the Operator using the OpenShift Operator Hub. Search for ‘MinIO’, select the KMS operator for installation, then follow the displayed instructions.

1. Create the MinIO KMS namespace

   Use the oc command to create a new project for MinIO KMS:

   oc new-project minkms
   

2. Create the Operator manifest and install to the namespace

   Use the following file as a template for the operator bundle:

   # subscription.yaml
   
   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
      name: minio-minkms-operator
   spec:
      channel: stable
      installPlanApproval: Automatic
      name: minio-minkms-operator
      source: certified-operators
      sourceNamespace: openshift-marketplace
      startingCSV: minio-minkms-operator.v2026.4.13102716
   ---
   apiVersion: operators.coreos.com/v1
   kind: OperatorGroup
   metadata:
      name: minkms-group
   

   Apply the manifest to the minkms namespace:

   oc apply -f subscription.yaml -n minkms
   

3. Next Steps

   You can now deploy a KMS resource to your Open Shift cluster using either of the following methods:

   • Deploy using Helm Charts.
   • Deploy using Operator Hub and the MinIO KMS CRD.

This procedure documents installation on OpenShift using the Operator Hub UI. You must first install the KMS Operator before proceeding.

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

2. Open the OperatorHub UI and navigate to the KMS Operator

   Use your preferred browser to access Operator Hub for your OpenShift installation. Select the MinIO KMS Operator from the list of installed operators.

3. Create the MinIO KMS configuration secret

   The MinKMS resource references a Kubernetes Secret that holds the server configuration file. The Secret must store the configuration under the data key server-config.yaml. If the key is missing or named differently, the Operator reports an error of the form secret "<name>" found but no "server-config.yaml" key present and the deployment does not progress.

   The Operator merges its own TLS settings and admin identity into this file at reconcile time, so you do not need to specify tls:, admin:, or address: here. At least one HSM source is required: either an HSM secret referenced by spec.hsmSecret on the MinKMS resource, or an hsm: block inside server-config.yaml.

   For deployments that use a soft (static) HSM key through spec.hsmSecret, the file contains only version: v1. See the bundled example in the next step for the rendered Secret.

   For deployments that point to an external HSM backend (another MinIO KMS cluster, HashiCorp Vault, or Entrust KeyControl), add the matching hsm: block. For step by step procedures on each backend, see HSM Management on Kubernetes. For the full configuration file schema, see the MinIO KMS Configuration File reference.

   The Secret manifest is included in the bundled example in the next step.

4. Create a new KMS instance

   The UI provides a tab for deploying new KMS resources. Use either the UI or the YAML editor to construct the KMS definition. See the MinIO KMS CRD for guidance in configuration.

   You can use the following example YAML as a baseline for further customization.

   apiVersion: minkms.min.io/v1alpha1
   kind: MinKMS
   metadata:
     name: my-kms
     namespace: ns-1
   spec:
     configuration:
       name: my-kms-server-config
     hsmSecret:
       name: my-kms-hsm
     apiKeySecret:
       name: my-api-key
     replicas: 2
     imagePullSecrets:
       - name: registry-creds
     volumeClaimTemplate:
       metadata:
         name: minkms-volume
       spec:
         accessModes:
           - ReadWriteOnce
         resources:
           requests:
             storage: 100Mi
         storageClassName: standard # Replace with an appropriate storage class to meet the requested value
   ---
   apiVersion: v1
   kind: Secret
   metadata:
     name: my-kms-server-config
     namespace: ns-1
   type: Opaque
   stringData:
     server-config.yaml: |
       version: v1    
   ---
   apiVersion: v1
   kind: Secret
   metadata:
     name: my-kms-hsm
     namespace: ns-1
   type: Opaque
   data:
     hsm: <BASE64-encoded HSM>
   

This procedure documents installation on Kubernetes with the Helm Charts. You must first install the KMS Operator before proceeding.

1. Add the AIStor Helm Repository

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

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

3. 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>"
   

   The command outputs instructions for connecting an AIStor object store to MinIO KMS. AIStor can then use MinIO KMS to enable Server Side Encryption of objects.

   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.