From d853a19408e6bfd23537fe47decfa7ac88a4bdfe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Gro=C3=9Fmann?= Date: Wed, 27 May 2026 10:58:46 +0200 Subject: [PATCH] feat(docker-pass): update docs --- data/cli/secrets/docker_pass.yaml | 217 +++++++++++++++++- data/cli/secrets/docker_pass_get.yaml | 7 +- data/cli/secrets/docker_pass_ls.yaml | 7 +- data/cli/secrets/docker_pass_plugins.yaml | 40 ++++ .../docker_pass_plugins_1password.yaml | 42 ++++ .../docker_pass_plugins_1password_purge.yaml | 15 ++ .../docker_pass_plugins_1password_setup.yaml | 17 ++ .../secrets/docker_pass_plugins_disable.yaml | 11 + .../secrets/docker_pass_plugins_enable.yaml | 11 + data/cli/secrets/docker_pass_plugins_ls.yaml | 11 + data/cli/secrets/docker_pass_rm.yaml | 22 +- data/cli/secrets/docker_pass_run.yaml | 56 +++++ data/cli/secrets/docker_pass_set.yaml | 55 ++++- 13 files changed, 485 insertions(+), 26 deletions(-) create mode 100644 data/cli/secrets/docker_pass_plugins.yaml create mode 100644 data/cli/secrets/docker_pass_plugins_1password.yaml create mode 100644 data/cli/secrets/docker_pass_plugins_1password_purge.yaml create mode 100644 data/cli/secrets/docker_pass_plugins_1password_setup.yaml create mode 100644 data/cli/secrets/docker_pass_plugins_disable.yaml create mode 100644 data/cli/secrets/docker_pass_plugins_enable.yaml create mode 100644 data/cli/secrets/docker_pass_plugins_ls.yaml create mode 100644 data/cli/secrets/docker_pass_run.yaml diff --git a/data/cli/secrets/docker_pass.yaml b/data/cli/secrets/docker_pass.yaml index be7381bc20bf..adfb6739307b 100644 --- a/data/cli/secrets/docker_pass.yaml +++ b/data/cli/secrets/docker_pass.yaml @@ -1,23 +1,232 @@ command: docker pass short: Manage your local OS keychain secrets. -long: "Docker Pass is a helper for securely storing secrets in your local OS keychain and injecting them into containers when needed. \nIt uses platform-specific credential storage:\n\n - Windows: Windows Credential Manager API\n - macOS: Keychain services API\n - Linux: org.freedesktop.secrets API (requires DBus + gnome-keyring or kdewallet)\n\nSecrets can be injected into running containers at runtime using the se:// URI scheme." -usage: docker pass set|get|ls|rm +long: |- + Docker Pass is a helper for securely retrieving secrets from a range of + backends, such as your local OS keychain, password managers, or remote + vaults, and injecting them into containers and host commands when + needed. Each backend is implemented as a plugin. + + ## Secret References + + A secret reference is written using the `se://` URI scheme and either + identifies a specific secret or matches multiple secrets through a + pattern over the realm structure. For example: + + - `se://docker/auth/hub/alice` — resolves to a specific secret, Alice's + Docker Hub credential. + - `se://docker/auth/hub/*` — matches every credential stored directly under + Docker Hub. + - `se://docker/auth/**` — matches every Docker auth secret across all + registries. + + Resolution fans out across every plugin whose pattern matches the + reference, so even a specific ID can return multiple values if more + than one plugin has stored a secret under that ID. + The same reference can be reused across environments and storage + backends without rewriting Compose files or application + configuration. For example, it may resolve against your local OS + keychain in development and against a production vault in CI or on a + server. + + The engine resolves these references in two contexts: + + ### Containers + + Anywhere Docker accepts an environment-variable value, write + `se://` and the engine resolves it just before the container + starts. + + With `docker run -e`: + + ```sh + docker run --rm -e OPENAI_API_KEY=se://openai/api-key busybox sh -c 'echo "$OPENAI_API_KEY"' + ``` + + In a Compose file under `environment:`: + + ```yaml + services: + app: + image: your/image + environment: + DB_PASSWORD: se://postgres/prod/app-user + ``` + + ### Host commands + + `docker pass run` wraps any host process and resolves `se://` + references in its environment before exec'ing it. Any env variable + whose value has the form `se://` is replaced with the + resolved secret; everything else is passed through untouched. + + ```sh + GH_TOKEN=se://gh-token docker pass run -- gh repo list + ``` + + ### Identifiers + + Secret IDs are hierarchical, path-like strings. Components are separated + by `/`; each component may contain `A-Z`, `a-z`, `0-9`, `.`, `-`, `_`, + or `:`. No leading, trailing, or empty components. Matching is + case-sensitive. A predictable realm/namespace structure + (e.g. `docker/auth/`, `docker/db//password`) makes + automation and access control easier. + + ### Patterns + + Patterns follow the same rules as identifiers, with two extra tokens: + + - `*` — matches exactly one component. + - `**` — matches zero or more components. + + Wildcards must occupy a whole component (e.g. `auth/*/token` is valid; + `auth/foo*` is not), and a single component may contain at most one of + `*` or `**`. + + Example patterns: + + - `docker/auth/**` — every Docker auth secret in any sub-realm. + - `myrealm/*/password` — password entries one level deep under + `myrealm`. + - `**` — catch-all. + + ### Routing + + When a container references `se://`, the engine fans the lookup out + to every plugin whose declared pattern matches `` and merges their + responses. If no plugin matches, the lookup fails and the container + does not start. + + ## Plugin Management + + Use the CLI to inspect loaded and available plugins: + + ```sh + docker pass plugins ls + ``` + + Plugins marked as **configurable** can be enabled or disabled at runtime: + + ```sh + docker pass plugins enable + docker pass plugins disable + ``` + + ## Plugins + + ### OS Keychain + + - **Plugin name:** `docker-pass` + - **Storage backend:** the local OS keychain, accessed via + platform-specific APIs: + - **Windows:** Windows Credential Manager API + - **macOS:** Keychain Services API + - **Linux:** `org.freedesktop.secrets` API (requires DBus and a + Secret Service provider such as `gnome-keyring` or `kdewallet`) + - **Use:** holds secrets you store directly with `docker pass` (and + internal secrets used by other plugins, such as the 1Password service + account token). Always on; not configurable. + + ### 1Password (configurable) + + Each item matches the requested pattern under up to three candidate IDs: + + 1. **Raw item ID** — the opaque alphanumeric ID that 1Password assigns + (e.g. `alphanumeric_26char`). + 2. **`/`** — the vault's ID joined with the item's + normalized title. + 3. **`<vault-name>/<title>`** — the vault's display name joined with + the item's normalized title. + + Normalization (applied to vault names and titles) follows 1Password's + [secret-reference syntax](https://developer.1password.com/docs/cli/secret-reference-syntax/): + spaces become `-`, `(` and `)` are stripped, `/` and `&` become `_`, + any remaining character outside `[a-zA-Z0-9-._]` is removed, and the + result is lowercased. Following 1Password's matching rules makes the + plugin case-insensitive, so existing `op://` references can be reused + as-is. + + Candidates that don't produce a valid ID are skipped silently, so + items with unusual names are still matchable through one of the other + forms. + + #### CLI version + + - **Plugin name:** `1password-cli` + - **How it authenticates:** delegates to the [`op` CLI](https://developer.1password.com/docs/cli/). + You need `op` installed and an active 1Password session. On macOS + this typically means the 1Password desktop app with biometric unlock + enabled; on other platforms, `op signin`. + - **Setup:** no tokens to manage. If your local `op` is signed in, the + plugin can resolve secrets. + - **Behavior:** when Docker Desktop starts, the plugin performs an + initial fetch of all items, which triggers a 1Password authorization + prompt. The resulting cache is then refreshed periodically. + - **Fatal errors:** the plugin treats a few conditions as + unrecoverable and stops itself instead of retrying: + - the `op` binary cannot be found on `PATH`, + - the user dismisses or lets the 1Password authorization prompt + time out. + + When this happens the plugin is reported as crashed in + `docker pass plugins ls`. Resolve the underlying issue (install + `op`, sign in, accept the prompt) and re-enable the plugin with + `docker pass plugins enable 1password-cli`. + - **Enable / disable:** + ```sh + docker pass plugins enable 1password-cli + docker pass plugins disable 1password-cli + ``` + + #### Service account token version + + - **Plugin name:** `1password-sdk` + - **How it authenticates:** uses the official 1Password Go SDK with a + [service account token](https://developer.1password.com/docs/service-accounts/get-started/) + scoped to the vaults you want to expose. + - **Setup:** supply the token once on stdin. It is stored in the OS + keychain and the plugin is enabled in the same step: + ```sh + echo "$OP_SERVICE_ACCOUNT_TOKEN" | docker pass plugins 1password setup + ``` + - **Teardown:** remove the token and disable the plugin: + ```sh + docker pass plugins 1password purge + ``` + + ### HashiCorp Vault (configurable) + + Coming soon. + + ## Feedback and SDK + + Use the Go SDK at + [github.com/docker/secrets-engine](https://github.com/docker/secrets-engine) + to integrate secret resolution into your own code, build custom + clients, or write new plugins. + + Have a feature request or hit a bug? File an issue at [github.com/docker/secrets-engine/issues](https://github.com/docker/secrets-engine/issues). +usage: docker pass set|get|ls|rm|run pname: docker plink: docker.yaml cname: - docker pass get - docker pass ls + - docker pass plugins - docker pass rm + - docker pass run - docker pass set clink: - docker_pass_get.yaml - docker_pass_ls.yaml + - docker_pass_plugins.yaml - docker_pass_rm.yaml + - docker_pass_run.yaml - docker_pass_set.yaml deprecated: false hidden: false -experimental: true -experimentalcli: true +experimental: false +experimentalcli: false kubernetes: false swarm: false examples: |- diff --git a/data/cli/secrets/docker_pass_get.yaml b/data/cli/secrets/docker_pass_get.yaml index dee06e69f981..cc5dc2db18e7 100644 --- a/data/cli/secrets/docker_pass_get.yaml +++ b/data/cli/secrets/docker_pass_get.yaml @@ -1,12 +1,13 @@ command: docker pass get short: Get a secret from a keystore. -long: Retrieves a named secret from the local OS keychain. The secret value is masked in output. +long: |- + Retrieves a named secret from the local OS keychain. The secret value is masked in output. usage: docker pass get NAME pname: docker pass plink: docker_pass.yaml deprecated: false hidden: false -experimental: true -experimentalcli: true +experimental: false +experimentalcli: false kubernetes: false swarm: false diff --git a/data/cli/secrets/docker_pass_ls.yaml b/data/cli/secrets/docker_pass_ls.yaml index 12c067de1ebf..877e649cc25b 100644 --- a/data/cli/secrets/docker_pass_ls.yaml +++ b/data/cli/secrets/docker_pass_ls.yaml @@ -1,12 +1,13 @@ command: docker pass ls short: List all secrets from local keychain. -long: Lists the names of all secrets stored in the local OS keychain. +long: |- + Lists the names of all secrets stored in the local OS keychain. usage: docker pass ls pname: docker pass plink: docker_pass.yaml deprecated: false hidden: false -experimental: true -experimentalcli: true +experimental: false +experimentalcli: false kubernetes: false swarm: false diff --git a/data/cli/secrets/docker_pass_plugins.yaml b/data/cli/secrets/docker_pass_plugins.yaml new file mode 100644 index 000000000000..87104358352e --- /dev/null +++ b/data/cli/secrets/docker_pass_plugins.yaml @@ -0,0 +1,40 @@ +command: docker pass plugins +short: Manage secrets engine plugins. +long: |- + Manage the plugins that the secrets engine uses to resolve secret references. + + Each plugin declares its scope through a pattern, and the engine routes every lookup to the plugins whose pattern matches the requested identifier. A plugin registered with `**` receives every request, while a plugin scoped to `docker/auth/**` only serves Docker auth lookups. + + Use the subcommands to inspect which plugins are registered and their current status, to enable or disable configurable plugins at runtime, and to set up or tear down plugin-specific credentials (such as the 1Password service account token). +usage: docker pass plugins +pname: docker pass +plink: docker_pass.yaml +cname: + - docker pass plugins 1password + - docker pass plugins disable + - docker pass plugins enable + - docker pass plugins ls +clink: + - docker_pass_plugins_1password.yaml + - docker_pass_plugins_disable.yaml + - docker_pass_plugins_enable.yaml + - docker_pass_plugins_ls.yaml +deprecated: false +hidden: false +experimental: true +experimentalcli: true +kubernetes: false +swarm: false +examples: |- + List all registered plugins and their status: + + ```sh + docker pass plugins ls + ``` + + Enable or disable a configurable plugin: + + ```sh + docker pass plugins enable 1password-cli + docker pass plugins disable 1password-cli + ``` diff --git a/data/cli/secrets/docker_pass_plugins_1password.yaml b/data/cli/secrets/docker_pass_plugins_1password.yaml new file mode 100644 index 000000000000..0e6b9bf6106b --- /dev/null +++ b/data/cli/secrets/docker_pass_plugins_1password.yaml @@ -0,0 +1,42 @@ +command: docker pass plugins 1password +short: Manage the 1Password SDK plugin. +long: |- + Manage the `1password-sdk` plugin, which resolves secret references against 1Password through the official 1Password SDK. + + The plugin authenticates with a [service account token](https://developer.1password.com/docs/service-accounts/get-started/) scoped to the vaults you want to expose. The token is stored in the local OS keychain. Use the subcommands to install the token (and enable the plugin) or to remove it (and disable the plugin). + + Items reachable through this plugin are matched under any of: + + - the raw 1Password item ID, + - `<vault-id>/<title>`, + - `<vault-name>/<title>`, + - a native 1Password secret-reference path (`<vault>/<item>/<field>` or `<vault>/<item>/<section>/<field>`), resolved directly via the SDK as if prefixed with `op://`. + + Matching for the title-based forms follows 1Password's normalization rules and is case-insensitive, so existing `op://` references can be reused as-is. +usage: docker pass plugins 1password +pname: docker pass plugins +plink: docker_pass_plugins.yaml +cname: + - docker pass plugins 1password purge + - docker pass plugins 1password setup +clink: + - docker_pass_plugins_1password_purge.yaml + - docker_pass_plugins_1password_setup.yaml +deprecated: false +hidden: false +experimental: true +experimentalcli: true +kubernetes: false +swarm: false +examples: |- + Install the service account token and enable the plugin: + + ```sh + echo "$OP_SERVICE_ACCOUNT_TOKEN" | docker pass plugins 1password setup + ``` + + Remove the token and disable the plugin: + + ```sh + docker pass plugins 1password purge + ``` diff --git a/data/cli/secrets/docker_pass_plugins_1password_purge.yaml b/data/cli/secrets/docker_pass_plugins_1password_purge.yaml new file mode 100644 index 000000000000..4985759ef480 --- /dev/null +++ b/data/cli/secrets/docker_pass_plugins_1password_purge.yaml @@ -0,0 +1,15 @@ +command: docker pass plugins 1password purge +short: Disable the plugin and remove the stored 1Password service account token. +long: |- + Disable the `1password-sdk` plugin on the running secrets-engine daemon and remove the service account token from the local OS keychain. + + After purge, the plugin no longer participates in secret resolution and the token is gone from local storage. Run `setup` again to re-enable it. +usage: docker pass plugins 1password purge +pname: docker pass plugins 1password +plink: docker_pass_plugins_1password.yaml +deprecated: false +hidden: false +experimental: true +experimentalcli: true +kubernetes: false +swarm: false diff --git a/data/cli/secrets/docker_pass_plugins_1password_setup.yaml b/data/cli/secrets/docker_pass_plugins_1password_setup.yaml new file mode 100644 index 000000000000..9dfe9857cc22 --- /dev/null +++ b/data/cli/secrets/docker_pass_plugins_1password_setup.yaml @@ -0,0 +1,17 @@ +command: docker pass plugins 1password setup +short: Set the 1Password service account token and enable the plugin. +long: |- + Store a 1Password [service account token](https://developer.1password.com/docs/service-accounts/get-started/) in the local OS keychain and enable the `1password-sdk` plugin. + + The token is read from STDIN and replaces any previously stored token. Once it is stored, the secrets engine is asked to enable the plugin so subsequent lookups resolve against 1Password. + + Service account tokens are scoped to a fixed set of vaults; only items in those vaults are reachable through the plugin. +usage: docker pass plugins 1password setup +pname: docker pass plugins 1password +plink: docker_pass_plugins_1password.yaml +deprecated: false +hidden: false +experimental: true +experimentalcli: true +kubernetes: false +swarm: false diff --git a/data/cli/secrets/docker_pass_plugins_disable.yaml b/data/cli/secrets/docker_pass_plugins_disable.yaml new file mode 100644 index 000000000000..527a6a722089 --- /dev/null +++ b/data/cli/secrets/docker_pass_plugins_disable.yaml @@ -0,0 +1,11 @@ +command: docker pass plugins disable +short: Disable a secrets engine plugin. +usage: docker pass plugins disable <name> +pname: docker pass plugins +plink: docker_pass_plugins.yaml +deprecated: false +hidden: false +experimental: true +experimentalcli: true +kubernetes: false +swarm: false diff --git a/data/cli/secrets/docker_pass_plugins_enable.yaml b/data/cli/secrets/docker_pass_plugins_enable.yaml new file mode 100644 index 000000000000..e912538cdfc2 --- /dev/null +++ b/data/cli/secrets/docker_pass_plugins_enable.yaml @@ -0,0 +1,11 @@ +command: docker pass plugins enable +short: Enable a secrets engine plugin. +usage: docker pass plugins enable <name> +pname: docker pass plugins +plink: docker_pass_plugins.yaml +deprecated: false +hidden: false +experimental: true +experimentalcli: true +kubernetes: false +swarm: false diff --git a/data/cli/secrets/docker_pass_plugins_ls.yaml b/data/cli/secrets/docker_pass_plugins_ls.yaml new file mode 100644 index 000000000000..08b04b777906 --- /dev/null +++ b/data/cli/secrets/docker_pass_plugins_ls.yaml @@ -0,0 +1,11 @@ +command: docker pass plugins ls +short: List registered secrets engine plugins. +usage: docker pass plugins ls +pname: docker pass plugins +plink: docker_pass_plugins.yaml +deprecated: false +hidden: false +experimental: true +experimentalcli: true +kubernetes: false +swarm: false diff --git a/data/cli/secrets/docker_pass_rm.yaml b/data/cli/secrets/docker_pass_rm.yaml index 588fb1232295..03a3685f5707 100644 --- a/data/cli/secrets/docker_pass_rm.yaml +++ b/data/cli/secrets/docker_pass_rm.yaml @@ -1,8 +1,7 @@ command: docker pass rm short: Remove secrets from local keychain. long: |- - Removes one or more named secrets from the local OS keychain. - Use --all to remove every stored secret at once. + Removes one or more named secrets from the local OS keychain. Use `--all` to remove every stored secret at once. usage: docker pass rm name1 name2 ... [flags] pname: docker pass plink: docker_pass.yaml @@ -19,16 +18,25 @@ options: swarm: false deprecated: false hidden: false -experimental: true -experimentalcli: true +experimental: false +experimentalcli: false kubernetes: false swarm: false examples: |- ### Remove a specific secret: - docker pass rm GH_TOKEN + + ```console + $ docker pass rm GH_TOKEN + ``` ### Remove multiple secrets: - docker pass rm GH_TOKEN NPM_TOKEN + + ```console + $ docker pass rm GH_TOKEN NPM_TOKEN + ``` ### Remove all secrets: - docker pass rm --all + + ```console + $ docker pass rm --all + ``` diff --git a/data/cli/secrets/docker_pass_run.yaml b/data/cli/secrets/docker_pass_run.yaml new file mode 100644 index 000000000000..32bf976f3b9a --- /dev/null +++ b/data/cli/secrets/docker_pass_run.yaml @@ -0,0 +1,56 @@ +command: docker pass run +short: Run a command with `se://` environment references resolved. +long: |- + Scans the current environment (plus any `--env-file` inputs) for variables + whose value is exactly `se://<ID|pattern>`. Each reference is resolved through the + secrets-engine daemon and the resolved value is passed to the child process. + The child inherits stdin, stdout, and stderr. + + Requires the secrets-engine daemon (Docker Desktop) to be running. + + If any reference cannot be resolved, the command fails before the child is + started and exits non-zero. +usage: docker pass run -- CMD [ARGS...] [flags] +pname: docker pass +plink: docker_pass.yaml +options: + - option: env-file + value_type: stringArray + default_value: '[]' + description: Read environment variables from a dotenv-formatted file. Repeatable; later files override earlier files and the process environment. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: true +experimentalcli: true +kubernetes: false +swarm: false +examples: |- + ### Run a command with one secret in its environment: + + ```console + $ SE_TOKEN=se://gh-token docker pass run -- gh repo list + ``` + + ### Multiple references: + + ```console + $ DB_PASSWORD=se://myapp/postgres/password API_KEY=se://myapp/anthropic/api-key docker pass run -- ./my-binary + ``` + + ### Resolve references from a dotenv file: + + ```console + $ docker pass run --env-file .env -- ./my-binary + ``` + + ### Multiple files (later overrides earlier; files override the process environment): + + ```console + $ docker pass run --env-file .env --env-file .env.local -- ./my-binary + ``` diff --git a/data/cli/secrets/docker_pass_set.yaml b/data/cli/secrets/docker_pass_set.yaml index 0e831cf54b54..1f0e7e7c33df 100644 --- a/data/cli/secrets/docker_pass_set.yaml +++ b/data/cli/secrets/docker_pass_set.yaml @@ -1,12 +1,31 @@ command: docker pass set short: Set a secret long: |- - Stores a secret in the local OS keychain. The secret value can be - provided inline (NAME=VALUE) or piped via STDIN. + Stores a secret in the local OS keychain. The secret value can be provided inline (`NAME=VALUE`) or piped via STDIN. + + Behavior when a secret with the same id already exists is platform-dependent: + - macOS (Keychain): the command fails with a duplicate-item error. + - Linux (Secret Service) and Windows (Credential Manager): the existing + value is silently overwritten. + + Pass `--force` to overwrite an existing secret. On Linux and Windows the + replacement is performed atomically. On macOS the Keychain API requires + a delete-then-add sequence. usage: docker pass set id[=value] [flags] pname: docker pass plink: docker_pass.yaml options: + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Overwrite existing secret if it already exists + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: metadata value_type: stringArray default_value: '[]' @@ -19,20 +38,38 @@ options: swarm: false deprecated: false hidden: false -experimental: true -experimentalcli: true +experimental: false +experimentalcli: false kubernetes: false swarm: false examples: |- ### Set a secret: - docker pass set POSTGRES_PASSWORD=my-secret-password + + ```console + $ docker pass set POSTGRES_PASSWORD=my-secret-password + ``` ### Or pass the secret via STDIN: - echo my-secret-password > pwd.txt - cat pwd.txt | docker pass set POSTGRES_PASSWORD + + ```console + $ echo my-secret-password > pwd.txt + $ cat pwd.txt | docker pass set POSTGRES_PASSWORD + ``` ### Set a secret with metadata: - docker pass set POSTGRES_PASSWORD=my-secret-password --metadata owner=alice --metadata expiry=2027-03-01 + + ```console + $ docker pass set POSTGRES_PASSWORD=my-secret-password --metadata owner=alice --metadata expiry=2027-03-01 + ``` ### Or pass a JSON payload with secret and metadata via STDIN: - echo '{"secret":"my-secret-password","metadata":{"owner":"alice"}}' | docker pass set POSTGRES_PASSWORD + + ```console + $ echo '{"secret":"my-secret-password","metadata":{"owner":"alice"}}' | docker pass set POSTGRES_PASSWORD + ``` + + ### Overwrite an existing secret: + + ```console + $ docker pass set POSTGRES_PASSWORD=new-secret-password --force + ```