ローカル環境でシークレットを管理できる docker pass コマンド

はじめに

docker pass コマンドを使うとローカル環境でシークレットを管理できる．macOS だとデフォルトでは「キーチェーン」にシークレットが保存されて，Docker コンテナや Docker Compose に se:// というスキームでシークレットの参照を渡せるようになる．.env ファイルを使わなくて良くなる!?

docs.docker.com

docker pass コマンドを試してみた＼( 'ω')／

環境

macOS Tahoe
Docker Desktop 4.85.0

Docker Desktop だと docker pass コマンドは同梱されていてセットアップは不要だった．ドキュメントを見ると Docker CE の場合は別途 docker-secrets-engine と docker-secrets-engine-plugins のパッケージを入れておく必要がありそうだった👌

$ ocker pass --help
Docker Pass CLI - Manage your local secrets.

Usage: docker pass set|get|ls|rm|run

Available Commands:
  get         Get a secret from a keystore.
  ls          List all secrets from local keychain.
  plugins     Manage secrets engine plugins.
  rm          Remove secrets from local keychain.
  run         Run a command with `se://` environment references resolved.
  set         Set a secret

docker pass コマンド

現状だと6種類のコマンドがある．

コマンド	概要
`docker pass get`	シークレットを取得する
`docker pass ls`	シークレットを一覧する
`docker pass plugins`	Secrets Engine のプラグインを管理する
`docker pass rm`	シークレットを削除する
`docker pass run`	`se://` 参照を渡して任意のコマンドを実行する
`docker pass set`	シークレットを登録する

シークレットの操作を試す

1. docker pass set

まずは docker pass set コマンドでシークレットを登録する．

$ docker pass set MY_TEST_SECRET=my-test-secret

ちなみに --metadata オプションを使うとシークレットに関する任意のメタデータも一緒に登録できる．今回はドキュメントに載っていた owner と expiry を登録してみた．

$ docker pass set MY_TEST_SECRET_WITH_METADATA=my-test-secret-with-metadata \
  --metadata owner=alice \
  --metadata expiry=2027-03-01

docs.docker.com

2. docker pass ls

そして docker pass ls コマンドを実行すると登録した2つのシークレットを確認できた👌

$ docker pass ls
MY_TEST_SECRET
MY_TEST_SECRET_WITH_METADATA

docs.docker.com

3. docker pass get

docker pass get コマンドを実行するとシークレットを取得できる．とは言えシークレット値はマスクされて表示される仕様になっていて，シークレット値を表示するオプションもなさそうだった．よって「シークレットが登録されていることを確認する」という感じで使うコマンドのようだった．

$ docker pass get MY_TEST_SECRET
ID: MY_TEST_SECRET
Value: **********

docs.docker.com

4. docker pass run

docker pass run コマンドを使うと，se:// 参照を渡して任意のコマンドを実行できる．たとえば以下のような感じでシークレットを直接 echo で出力できる．あくまで検証だから本当はやらないように🚨

$ MY_TEST_SECRET=se://MY_TEST_SECRET docker pass run -- sh -c 'echo "MY_TEST_SECRET: ${MY_TEST_SECRET}"'
MY_TEST_SECRET: my-test-secret

5. docker pass plugins

docker pass plugins コマンドには Secrets Engine のプラグインを管理するサブコマンドがある．

$ docker pass plugins --help
Docker Pass CLI - Manage your local secrets.

Usage: docker pass plugins

Available Commands:
  1password   Manage the 1Password SDK plugin.
  disable     Disable a secrets engine plugin.
  enable      Enable a secrets engine plugin.
  ls          List registered secrets engine plugins.

試しに docker pass plugins ls コマンドを実行すると以下のようになっていた．デフォルトのキーチェーン以外に 1Password を選べるのはなるほど💡

$ docker pass plugins ls
     NAME                          VERSION  PATTERN                  STATUS              CONFIGURABLE  TYPE
  ○  1password-cli                 v0.0.6   **                       stopped (disabled)  yes           builtin
  ○  1password-sdk                 v0.0.7   **                       stopped (disabled)  yes           builtin
  ●  docker-auth                   v0.1.1   docker/auth/**           running             no            builtin
  ●  docker-desktop-mcp-dcr        v0.0.1   docker/mcp/oauth-dcr/**  running             no            builtin
  ●  docker-desktop-mcp-oauth      v0.0.1   docker/mcp/oauth/**      running             no            builtin
  ●  docker-mcp-credential-helper  v0.0.7   docker/mcp/**            running             no            builtin
  ●  docker-pass                   v0.2.1   **                       running             no            builtin

docs.docker.com

6. docker pass rm

最後は docker pass rm コマンドでシークレットを削除できる．

$ docker pass rm MY_TEST_SECRET
RM: MY_TEST_SECRET

$ docker pass rm MY_TEST_SECRET_WITH_METADATA
RM: MY_TEST_SECRET_WITH_METADATA

docs.docker.com

Docker コンテナにシークレットを渡す

Docker コンテナを起動するときにシークレットを渡すことができる．以下のように docker run コマンドの環境変数に se:// 参照を渡せば OK👌コンテナの中に入って環境変数を表示できた．

$ docker pass set MY_TEST_SECRET=my-test-secret

$ docker run -e MY_TEST_SECRET=se://MY_TEST_SECRET -dt --name sandbox-docker-pass busybox
ba0d4ca66ac7c1acb681017cc8a628d253c2458cd63056a817291b00149ada9a

$ docker exec -it sandbox-docker-pass sh

/ # echo ${MY_TEST_SECRET}
my-test-secret

Docker Compose と組み合わせる

今度は Docker Compose で PostgreSQL を起動して POSTGRES_PASSWORD 環境変数に se:// 参照を渡す．

$ docker pass set POSTGRES_PASSWORD=my-postgres-password

次に Docker Compose の compose.yml を作る．POSTGRES_PASSWORD に se://POSTGRES_PASSWORD を設定した．

services:
  postgres:
    image: postgres:17-alpine@sha256:742f40ea20b9ff2ff31db5458d127452988a2164df9e17441e191f3b72252193
    environment:
      POSTGRES_PASSWORD: se://POSTGRES_PASSWORD
    ports:
      - 5432:5432

Docker Compose を起動して，PostgreSQL の PGPASSWORD 環境変数にシークレットを渡して psql コマンドを実行できた👏

$ docker compose up -d

$ PGPASSWORD=se://POSTGRES_PASSWORD docker pass run -- psql -h 127.0.0.1 -p 5432 -U postgres -c 'SELECT current_user'
 current_user
--------------
 postgres
(1 row)