Deploy MinIO KMS as a Container

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_ENDPOINT=http://localhost:7373
export MINIO_KMS_API_KEY=k1:VALUE
minkms stat -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 object-store-name to reflect the name or label you want to associate with AIStor.

export MINIO_KMS_SERVER=127.0.0.1:7373

minkms add-enclave -k object-store-name

minkms add-identity -k --enclave object-store-name --admin

The command returns the API Key and Identity for use with AIStor. Copy the k1: prefixed value for use when enabling AIStor Server-Side Encryption.

Next Steps

Once you have configured an enclave and identity, you can use the k1:APIKEY value to enable AIStor Server Side Encryption.

Before enabling AIStor SSE, you must add the public.crt to the /certs/CAs folder to allow validation of the MinIO KMS server certificate. Depending on your container configuration, you may also need to run AIStor on the same host machine to ensure network access to the container.