From efa340b605feff369da7c06bd95b57e5ae3abd73 Mon Sep 17 00:00:00 2001
From: Daniel <dany.villavicencio30@gmail.com>
Date: Thu, 27 Aug 2026 00:51:49 -0700
Subject: [PATCH] docs: Add `external` property back to compose and add swarm
 secrets example using compose (#25522)

<!--Delete sections as needed -->

## Description

Added back the attribute `external` in the `/reference/compose/secrets`
section with a warning that this attribute is only available for Docker
Swarm. Additionally, I added a small toy reference example to the
section "Defining and using Secrets in compose files" and moved the
section outside of the "Examples" section. The reason why I did this is
because I noticed the Examples are all runnable steps that showcase
concrete usage of secrets, the example I added is just a
skeleton/reference to how they should be used in conjunction with
`docker secret create...`, not a true able-to-run example like the ones
below. I also changed the hyperlink from
`/reference/compose-file/legacy-versions.md` to
`/reference/compose-file/secrets.md`.

A few caveats that I wasn't sure about when writing this:
- I'm not sure if using the "[!NOTE]" in the attributes list is the
approach maintainers and writers might favor and I can change it
accordingly
- I'd love to hear feedback on moving "Defining and using secrets in
compose files" outside of "Examples" due to my reasoning above

Edit:
I'm also not opposed to making a fully working example using compose,
stack and secrets and putting the section back under `Examples`

<!-- Tell us what you did and why -->

## Related issues or tickets
 #25491
<!-- Related issues, pull requests, or Jira tickets -->

## Reviews

<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->

- [ ] Technical review
- [ ] Editorial review
- [ ] Product review

---------

Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com>
---
 content/manuals/engine/swarm/secrets.md | 35 ++++++++++++++++++++-----
 1 file changed, 29 insertions(+), 6 deletions(-)

diff --git a/content/manuals/engine/swarm/secrets.md b/content/manuals/engine/swarm/secrets.md
index 591fd65243..00a5116ffa 100644
--- a/content/manuals/engine/swarm/secrets.md
+++ b/content/manuals/engine/swarm/secrets.md
@@ -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
@@ -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