From 15928d9f8bd24502155c9381df0d1289459a0df2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Gro=C3=9Fmann?= Date: Wed, 10 Jun 2026 09:57:59 +0200 Subject: [PATCH] feat(docker-pass): update docs --- data/cli/secrets/docker_pass.yaml | 66 +++++++++++++++++++ data/cli/secrets/docker_pass_plugins.yaml | 2 + .../docker_pass_plugins_1password.yaml | 42 ++++++++++++ .../docker_pass_plugins_1password_purge.yaml | 15 +++++ .../docker_pass_plugins_1password_setup.yaml | 17 +++++ 5 files changed, 142 insertions(+) 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 diff --git a/data/cli/secrets/docker_pass.yaml b/data/cli/secrets/docker_pass.yaml index e2c7989b5550..e93db92dcf34 100644 --- a/data/cli/secrets/docker_pass.yaml +++ b/data/cli/secrets/docker_pass.yaml @@ -127,6 +127,72 @@ long: |- 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 + ``` + ### Feedback and SDK Use the Go SDK at diff --git a/data/cli/secrets/docker_pass_plugins.yaml b/data/cli/secrets/docker_pass_plugins.yaml index e2b9da8b5501..87104358352e 100644 --- a/data/cli/secrets/docker_pass_plugins.yaml +++ b/data/cli/secrets/docker_pass_plugins.yaml @@ -10,10 +10,12 @@ 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 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