Skip to content

docs: Add external property back to compose and add swarm secrets example using compose #25522

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aevesdocker merged 2 commits into from
Aug 27, 2026
Merged

docs: Add external property back to compose and add swarm secrets example using compose #25522

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0d0e6f6
docs: Add `external` property back to compose and add swarm secrets e…
deahtstroke Jul 8, 2026
4b2d876
Apply suggestions from code review
aevesdocker Aug 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 29 additions & 6 deletions content/manuals/engine/swarm/secrets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,35 @@ Use these links to read about specific commands, or continue to the
- [`--secret`](/reference/cli/docker/service/create/#secret) flag for `docker service create`
- [`--secret-add` and `--secret-rm`](/reference/cli/docker/service/update/#secret-add) flags for `docker service update`

## Defining and using secrets in Compose files

Using secrets in a Compose file alongside Docker Swarm is as simple as defining a secret
using `docker secret create`.

```console
$ printf "my-secret" | docker secret create some_secret -
```

In the `compose.yml` file you can declare the secret as `external` in the top-level `secrets` attribute.

```yaml
services:
api:
image: my-web-app
environment:
MY_ENV: /run/secrets/some_secret
secrets:
- some_secret

secrets:
some_secret:
external: true
```

Both the `docker compose` and `docker stack` commands support defining secrets
in a Compose file. See
[the Compose file reference](/reference/compose-file/secrets.md) for details.

## Examples

This section includes three graduated examples which illustrate how to use
Expand All @@ -139,12 +168,6 @@ a similar way, see
> simplicity. The examples use Linux containers, but Windows containers also
> support secrets. See [Windows support](#windows-support).

### Defining and using secrets in compose files

Both the `docker-compose` and `docker stack` commands support defining secrets
in a compose file. See
[the Compose file reference](/reference/compose-file/secrets.md) for details.

### Simple example: Get started with secrets

This simple example shows how secrets work in just a few commands. For a
Expand Down