Docker Swarm

In this guide, we'll demonstrate how to use Hanzo KMS for managing secrets within Docker Swarm. Specifically, we'll set up a sidecar container using the KMS Agent, which authenticates with Hanzo KMS to retrieve secrets and access tokens. These secrets are then stored in a shared volume accessible by other services in your Docker Swarm.

Prerequisites

Hanzo KMS account

Docker version 20.10.24 or newer

Basic knowledge of Docker Swarm

Git installed on your system

Familiarity with the KMS Agent

Objective

Our goal is to deploy an Nginx instance in your Docker Swarm cluster, configured to display Hanzo KMS secrets on its landing page. This will provide hands-on experience in fetching and utilizing secrets from Hanzo KMS within Docker Swarm. The principles demonstrated here are also applicable to Docker Compose deployments.

Start by cloning the Hanzo KMS guide assets repository from Github. This repository includes necessary assets for this and other Hanzo KMS guides. Focus on the docker-swarm-with-agent sub-directory, which we'll use as our working directory.

To allow the agent to fetch your Hanzo KMS secrets, choose an authentication method for the agent. For this guide, we will use Universal Auth for authentication. Follow the instructions here to generate a client ID and client secret.

Copy the client ID and client secret obtained in the previous step into the client-id and client-secret text files, respectively.

The KMS Agent will authenticate using Universal Auth and retrieve secrets for rendering as specified in the template(s). Adjust the polling-interval to control the frequency of secret updates.

In the example template, the secrets are rendered as an HTML page, which will be set as Nginx's home page to demonstrate successful secret retrieval and utilization.

Remember to add your project id, environment slug and path of corresponding Hanzo KMS project to the secret template.

kms:
address: "https://app.kms.hanzo.ai"
auth:
  type: "universal-auth"
  config:
    client-id: "/run/secrets/kms-universal-auth-client-id"
    client-secret: "/run/secrets/kms-universal-auth-client-secret"
    remove_client_secret_on_read: false
sinks:
  - type: "file"
    config:
      path: "/kms-secrets/access-token"
templates:
  - source-path: /run/secrets/nginx-home-page-template
    destination-path: /kms-secrets/index.html
    config:
      polling-interval: 60s

Some paths contain /run/secrets/ because the contents of those files reside in a Docker secret.

<!DOCTYPE html>
<html lang="en">
<body>
    <h1>This file is rendered by Hanzo KMS agent template engine</h1>
    <p>Here are the secrets that have been fetched from Hanzo KMS and stored in your volume mount</p>
    <ol>
      {{- with secret "7df67a5f-d26a-4988-a375-7153c08149da" "dev" "/" }}
      {{- range . }}
      <li>{{ .Key }}={{ .Value }}</li>
      {{- end }}
      {{- end }}
    </ol>
</body>
</html>

Define the kms-agent and nginx services in your Docker Compose file. kms-agent will handle secret retrieval and storage. These secrets are stored in a volume, accessible by other services like Nginx.

version: "3.1"

services:
  kms-agent:
    container_name: kms-agnet
    image: kms/cli:0.18.0
    command: agent --config=/run/secrets/kms-agent-config
    volumes:
      - kms-agent:/kms-secrets
    secrets:
      - kms-universal-auth-client-id
      - kms-universal-auth-client-secret
      - kms-agent-config
      - nginx-home-page-template
    networks:
      - kms_network

  nginx:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - kms-agent:/usr/share/nginx/html
    networks:
      - kms_network

volumes:
  kms-agent: 

secrets:
  kms-universal-auth-client-id:
    file: ./client-id
  kms-universal-auth-client-secret:
    file: ./client-secret
  kms-agent-config:
    file: ./kms-agent-config
  nginx-home-page-template:
    file: ./nginx-home-page-template
    

networks:
  kms_network:

docker swarm init

docker stack deploy -c docker-compose.yaml agent-demo

To confirm that secrets are properly rendered and accessible, navigate to http://localhost. You should see the Hanzo KMS secrets displayed on the Nginx landing page.

Nginx displaying Hanzo KMS secrets

docker stack rm agent-demo

Considerations

Secret Updates: Applications that access secrets directly from the volume mount will receive updates in real-time, in accordance with the polling-interval set in agent config.

In-Memory Secrets: If your application loads secrets into memory, the new secrets will be available to the application on the next deployment.

Prerequisites

Objective

Considerations

On this page