mirror of
https://github.com/hanzoai/kms.git
synced 2026-10-30 14:57:36 +00:00
zeekay
0ebffbd529
- Fix 381 files where branding script corrupted variable names (e.g. isHanzo KMSTemplate -> isKmsTemplate) - Rebrand from "Hanzo KMS" to just "KMS" for white-label support (allows Lux KMS, Hanzo KMS, etc. via configuration) - 856 files, purely string replacements, no logic changes
165 lines
6.3 KiB
Plaintext
165 lines
6.3 KiB
Plaintext
---
|
|
title: 'Docker Swarm'
|
|
description: "Learn how to manage secrets in Docker Swarm services."
|
|
---
|
|
|
|
In this guide, we'll demonstrate how to use KMS for managing secrets within Docker Swarm.
|
|
Specifically, we'll set up a sidecar container using the [KMS Agent](/integrations/platforms/kms-agent), which authenticates with 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
|
|
- KMS account
|
|
- Docker version 20.10.24 or newer
|
|
- Basic knowledge of Docker Swarm
|
|
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed on your system
|
|
- Familiarity with the [KMS Agent](/integrations/platforms/kms-agent)
|
|
|
|
## Objective
|
|
Our goal is to deploy an Nginx instance in your Docker Swarm cluster, configured to display KMS secrets on its landing page. This will provide hands-on experience in fetching and utilizing secrets from KMS within Docker Swarm. The principles demonstrated here are also applicable to Docker Compose deployments.
|
|
|
|
<Steps>
|
|
<Step title="Cloning the Guide Assets Repository">
|
|
Start by cloning the [KMS guide assets repository](https://github.com/hanzoai/kms-guides.git) from Github. This repository includes necessary assets for this and other KMS guides. Focus on the `docker-swarm-with-agent` sub-directory, which we'll use as our working directory.
|
|
</Step>
|
|
|
|
<Step title="Setting Up Authentication with KMS">
|
|
To allow the agent to fetch your KMS secrets, choose an authentication method for the agent. For this guide, we will use [Universal Auth](/documentation/platform/identities/universal-auth) for authentication. Follow the instructions [here](/documentation/platform/identities/universal-auth) to generate a client ID and client secret.
|
|
</Step>
|
|
|
|
<Step title="Entering Universal Auth Credentials">
|
|
Copy the client ID and client secret obtained in the previous step into the `client-id` and `client-secret` text files, respectively.
|
|
</Step>
|
|
|
|
<Step title="Configuring the KMS Agent">
|
|
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.
|
|
|
|
<Tip>
|
|
Remember to add your project id, environment slug and path of corresponding KMS project to the secret template.
|
|
</Tip>
|
|
<Tabs>
|
|
<Tab title="Agent Configuration">
|
|
```yaml kms-agent-config
|
|
kms:
|
|
address: "https://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
|
|
```
|
|
<Info>
|
|
Some paths contain `/run/secrets/` because the contents of those files reside in a [Docker secret](https://docs.docker.com/engine/swarm/secrets/#how-docker-manages-secrets).
|
|
</Info>
|
|
</Tab>
|
|
<Tab title="Secret Template for Agent">
|
|
```html nginx-home-page-template
|
|
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<body>
|
|
<h1>This file is rendered by KMS agent template engine</h1>
|
|
<p>Here are the secrets that have been fetched from 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>
|
|
```
|
|
</Tab>
|
|
</Tabs>
|
|
</Step>
|
|
|
|
<Step title="Creating the Docker Compose File">
|
|
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.
|
|
|
|
```yaml docker-compose.yaml
|
|
version: "3.1"
|
|
|
|
services:
|
|
kms-agent:
|
|
container_name: kms-agnet
|
|
image: ghcr.io/hanzoai/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:
|
|
```
|
|
</Step>
|
|
|
|
<Step title="Initializing Docker Swarm">
|
|
```
|
|
docker swarm init
|
|
```
|
|
</Step>
|
|
|
|
<Step title="Deploying the Docker Stack">
|
|
```
|
|
docker stack deploy -c docker-compose.yaml agent-demo
|
|
```
|
|
</Step>
|
|
|
|
<Step title="Verifying Secret Consumption">
|
|
To confirm that secrets are properly rendered and accessible, navigate to `http://localhost`. You should see the KMS secrets displayed on the Nginx landing page.
|
|
|
|
|
|
</Step>
|
|
|
|
<Step title="Clean up">
|
|
```
|
|
docker stack rm agent-demo
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
## 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.
|