diff --git a/docs/images/docker-swarm-secrets-complete.png b/docs/images/docker-swarm-secrets-complete.png new file mode 100644 index 000000000..28b439445 Binary files /dev/null and b/docs/images/docker-swarm-secrets-complete.png differ diff --git a/docs/infisical-agent/guides/docker-swarm-with-agent.mdx b/docs/infisical-agent/guides/docker-swarm-with-agent.mdx new file mode 100644 index 000000000..b73d5ad63 --- /dev/null +++ b/docs/infisical-agent/guides/docker-swarm-with-agent.mdx @@ -0,0 +1,164 @@ +--- +title: 'Docker Swarm' +description: "How to manage secrets in Docker Swarm services" +--- + +In this guide, we'll demonstrate how to use Infisical for managing secrets within Docker Swarm. +Specifically, we'll set up a sidecar container using the [Infisical Agent](/infisical-agent/overview), which authenticates with Infisical to retrieve secrets and access tokens. +These secrets are then stored in a shared volume accessible by other services in your Docker Swarm. + +## Prerequisites +- Infisical 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 [Infisical Agent](/infisical-agent/overview) + +## Objective +Our goal is to deploy an Nginx instance in your Docker Swarm cluster, configured to display Infisical secrets on its landing page. This will provide hands-on experience in fetching and utilizing secrets from Infisical within Docker Swarm. The principles demonstrated here are also applicable to Docker Compose deployments. + + + + Start by cloning the [Infisical guide assets repository](https://github.com/Infisical/infisical-guides.git) from Github. This repository includes necessary assets for this and other Infisical guides. Focus on the `docker-swarm-with-agent` sub-directory, which we'll use as our working directory. + + + + To allow the Infisical agent to your Infisical 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. + + + + Copy the client ID and client secret obtained in the previous step into the `client-id` and `client-secret` text files, respectively. + + + + The Infisical 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 Infisical project to the secret template. + + + + ```yaml infisical-agent-config + infisical: + address: "https://app.infisical.com" + auth: + type: "universal-auth" + config: + client-id: "/run/secrets/infisical-universal-auth-client-id" + client-secret: "/run/secrets/infisical-universal-auth-client-secret" + remove_client_secret_on_read: false + sinks: + - type: "file" + config: + path: "/infisical-secrets/access-token" + templates: + - source-path: /run/secrets/nginx-home-page-template + destination-path: /infisical-secrets/index.html + config: + polling-interval: 60s + ``` + + 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). + + + + ```html nginx-home-page-template + + + +

This file is rendered by Infisical agent template engine

+

Here are the secrets that have been fetched from Infisical and stored in your volume mount

+
    + {{- with secret "7df67a5f-d26a-4988-a375-7153c08149da" "dev" "/" }} + {{- range . }} +
  1. {{ .Key }}={{ .Value }}
    2. + {{- end }} + {{- end }} +
+ + + ``` + + + + + + Define the `infisical-agent` and `nginx` services in your Docker Compose file. `infisical-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: + infisical-agent: + container_name: infisical-agnet + image: infisical/cli:0.18.0 + command: agent --config=/run/secrets/infisical-agent-config + volumes: + - infisical-agent:/infisical-secrets + secrets: + - infisical-universal-auth-client-id + - infisical-universal-auth-client-secret + - infisical-agent-config + - nginx-home-page-template + networks: + - infisical_network + + nginx: + image: nginx:latest + ports: + - "80:80" + volumes: + - infisical-agent:/usr/share/nginx/html + networks: + - infisical_network + + volumes: + infisical-agent: + + secrets: + infisical-universal-auth-client-id: + file: ./client-id + infisical-universal-auth-client-secret: + file: ./client-secret + infisical-agent-config: + file: ./infisical-agent-config + nginx-home-page-template: + file: ./nginx-home-page-template + + + networks: + infisical_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 Infisical secrets displayed on the Nginx landing page. + + ![Nginx displaying Infisical secrets](/images/docker-swarm-secrets-complete.png) + + + + ``` + 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. \ No newline at end of file diff --git a/docs/mint.json b/docs/mint.json index 8f1835d5f..cb6ce08ac 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -228,12 +228,27 @@ { "group": "Agent", "pages": [ - "infisical-agent/overview" + "infisical-agent/overview", + { + "group": "Use cases", + "pages": [ + "infisical-agent/guides/docker-swarm-with-agent", + "integrations/platforms/ecs-with-agent" + ] + } ] }, { "group": "Infrastructure Integrations", "pages": [ + { + "group": "Container orchestrators", + "pages": [ + "integrations/platforms/kubernetes", + "infisical-agent/guides/docker-swarm-with-agent", + "integrations/platforms/ecs-with-agent" + ] + }, { "group": "Docker", "pages": [ @@ -243,10 +258,8 @@ "integrations/platforms/docker-compose" ] }, - "integrations/platforms/kubernetes", "integrations/frameworks/terraform", - "integrations/platforms/ansible", - "integrations/platforms/ecs-with-agent" + "integrations/platforms/ansible" ] }, {