Deploy MinIO KMS as a Container

MinIO KMS is licensed under the MinIO Software License.

MinIO Key Management Service (KMS) supports deploying as a container for supporting local development and evaluation.

In this tutorial you will create a single node MinIO KMS cluster that stores cryptographic key data on a host-local storage device. This node has no redundancy outside of that provided by the underlying storage. Local data modification or deletion results in the loss of both local cryptographic keys and remote data encrypted with those keys.

For production environments, use either the Linux or Kubernetes installation procedures.

This procedure assumes you have an existing Docker or Podman installation configured.

Procedure

1. Pull the latest stable image of MinIO KMS

Docker Podman

2. Create directory structure

This procedure uses a folder structure that stores MinIO KMS data and configurations under ${HOME}/minkms. You can modify these paths to reflect your environment.

mkdir -p ${HOME}/minkms/{data,certs}

3. Download `certgen` and create certificates

certgen creates self-signed certificates for TLS encryption suitable for MinIO KMS. Download the binary for your platform from the minio/certgen repository. Either move the binary to a directory in your PATH or specify the path to directly run the binary.

The following command creates a self-signed certificate for localhost and 127.0.0.1. You can modify the --host string to indicate additional hostnames or IP addresses based on your local container environment.

cd ${HOME}/minkms/certs
certgen --host "localhost, 127.0.0.1"

The command outputs a public.crt and private.key in the directory.

4. Create the configuration file

Create a file at ${HOME}/minkms/config.yaml with the following content:

version: v1

tls:
  certs:
  - key: /etc/minkms/certs/private.key
    cert: /etc/minkms/certs/public.crt

The paths specified in the configuration file represent the container’s directory structure.

5. Create the environment file

Create a file at ${HOME}/minkms/minkms.env with the following content:

MINIO_KMS_HSM_KEY=hsm:aes256:KEYVALUE

MINIO_KMS_VOLUME=/mnt/minio-kms

You can generate a new key by running the minkms --soft-hsm command:

Docker Podman

Replace the KEYVALUE with the command output.

6. Start the MinIO KMS server

The following command starts the MinIO KMS server in a container. It maps the files and configurations you created in the previous steps to the container structure.

Docker

docker run \
  --name minio-kms \
  -p 7373:7373 \
  -v ${HOME}/minkms/certs:/etc/minkms/certs \
  -v ${HOME}/minkms/config.yaml:/etc/minkms/config.yaml \
  -v ${HOME}/minkms/data:/mnt/minio-kms \
  --env-file ${HOME}/minkms/minkms.env \
  quay.io/minio/aistor/minkms:latest /mnt/minkms --config /etc/minkms/config.yaml

Podman

podman run \
  --name minio-kms \
  -p 7373:7373 \
  -v ${HOME}/minkms/certs:/etc/minkms/certs \
  -v ${HOME}/minkms/config.yaml:/etc/minkms/config.yaml \
  -v ${HOME}/minkms/data:/mnt/minio-kms \
  --env-file ${HOME}/minkms/minkms.env \
  quay.io/minio/aistor/minkms:latest /mnt/minkms --config /etc/minkms/config.yaml

The command starts the container attached to the current shell session. You can optionally add the run -d flag to run the container in the background.

The output includes the root API Key as k1:VALUE. If you run the container in a detached mode, use the docker|podman logs command to retrieve the API key. Save the value to a secure location for use in the next steps.

7. Connect to the MinIO KMS server.

Follow the MinIO KMS installation instructions to install the minkms binary to your local machine.

After installation, connect to the MinIO KMS server with the following command:

export MINIO_KMS_SERVER=https://127.0.0.1:7373
export MINIO_KMS_API_KEY=k1:VALUE
minkms stat -k

minkms env lists the variables the command line tool reads. MINIO_KMS_SERVER is one of them; MINIO_KMS_ENDPOINT is not. MinIO KMS serves HTTPS only, and certgen issues a self-signed certificate, which is why every command here carries -k.

The command returns the status of the MinIO KMS server.

Use the minkms binary to manage the MinIO KMS server. All changes persist to the mounted location ${HOME}/minkms/data.

8. Create an enclave and identity for AIStor

Each AIStor object store requires an enclave and identity for accessing MinIO KMS and performing cryptographic operations.

Run the following commands to generate the necessary resources. Change ENCLAVE_NAME to reflect the name or label you want to associate with AIStor.

minkms add-enclave -k ENCLAVE_NAME

minkms add-identity -k --enclave ENCLAVE_NAME --admin

The second command returns the API Key and Identity for use with AIStor. This enclave API key is not the same value as the root API key from step 6.

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

Do not reuse the root API key as the object store’s API key. AIStor Object Store logs a warning at startup if the API key it receives has SysAdmin privileges.

9. Create the default server-side encryption key

The object store uses this key to encrypt object data.

minkms add-key -k --enclave ENCLAVE_NAME SSE_KEY_NAME

10. Configure the object store

Set the following environment variables on the AIStor Object Store.

Environment Variable	Value
MINIO_KMS_SERVER	The address the object store uses to reach the container, such as `https://127.0.0.1:7373`
MINIO_KMS_ENCLAVE	The enclave name from step 8
MINIO_KMS_API_KEY	The enclave API key from step 8, not the `root` API key from step 6
MINIO_KMS_SSE_KEY	The encryption key name from step 9

The object store must also trust the MinIO KMS server certificate. Add public.crt to the object store’s certs/CAs directory, not the one inside this container. Depending on your container configuration, you may also need to run AIStor on the same host machine to ensure network access to the container.

Next steps

Setting the environment variables does not by itself encrypt anything. Restart the object store to apply them, then turn on default bucket encryption. AIStor Server Side Encryption covers both steps.