docker pass

docker pass 명령은 로컬 OS 키체인 시크릿을 관리합니다.

출처: 문서

본문

Docker Pass는 로컬 OS 키체인, 비밀번호 매니저, 원격 볼트 같은 다양한 백엔드에서 시크릿을 안전하게 검색하고 필요할 때 컨테이너와 호스트 명령에 주입하는 헬퍼예요. 각 백엔드는 플러그인으로 구현돼요.

구분	내용
Description	로컬 OS 키체인 시크릿 관리
Usage	`docker pass set\|get\|ls\|rm\|run`

설치 (Installation)

Docker Desktop에서는 Secrets Engine과 docker pass가 기본으로 통합돼 있어요. Docker CE의 경우 Docker 공식 저장소에서 패키지를 별도로 설치해요. Docker Engine(dockerd) 29.2.0 이상이 필요해요. 해당 저장소에서 Docker Engine을 설치하지 않았다면 공식 편의 스크립트로 추가해요:

curl -fsSL https://get.docker.com | sh -s -- --setup-repo

apt (Debian/Ubuntu):

sudo apt-get update
sudo apt-get install docker-secrets-engine docker-secrets-engine-plugins

dnf (Fedora):

sudo dnf install docker-secrets-engine docker-secrets-engine-plugins

그런 다음 사용자용 서비스를 활성화해요:

systemctl --user daemon-reload
systemctl --user enable --now docker-secrets-engine.service

전체 지침은 Secrets Engine README를 참고해요.

시크릿 참조 (Secret References)

시크릿 참조는 se:// URI 스킴으로 작성하며, 특정 시크릿을 식별하거나 레일름 구조 위의 패턴을 통해 여러 시크릿을 매칭해요. 예를 들면:

se://docker/auth/hub/alice — 특정 시크릿, Alice의 Docker Hub 자격 증명으로 해석
se://docker/auth/hub/* — Docker Hub 아래에 직접 저장된 모든 자격 증명 매칭
se://docker/auth/** — 모든 레지스트리의 모든 Docker auth 시크릿 매칭

해석은 참조와 매칭되는 패턴을 가진 모든 플러그인에 펼쳐져서, 두 개 이상의 플러그인이 같은 ID 아래에 시크릿을 저장했다면 특정 ID조차 여러 값을 반환할 수 있어요. 같은 참조는 Compose 파일이나 애플리케이션 구성을 다시 쓰지 않고도 여러 환경과 스토리지 백엔드에서 재사용할 수 있어요. 예를 들어 개발 환경에서는 로컬 OS 키체인에 대해, CI나 서버에서는 프로덕션 볼트에 대해 해석될 수 있어요.

엔진은 두 가지 컨텍스트에서 참조를 해석해요:

컨테이너 (Containers)

Docker가 환경변수 값을 받아들이는 어디든 se://<id|pattern>을 쓰면, 엔진이 컨테이너가 시작되기 직전에 해석해요.

docker run -e 사용:

docker run --rm -e OPENAI_API_KEY=se://openai/api-key busybox sh -c 'echo "$OPENAI_API_KEY"'

Compose 파일의 environment:에서:

services:
  app:
    image: your/image
    environment:
      DB_PASSWORD: se://postgres/prod/app-user

참고: docker compose build는 아직 지원되지 않아요.

호스트 명령 (Host commands)

docker pass run은 호스트 프로세스를 감싸고, exec 전에 그 환경의 se:// 참조를 해석해요. 값이 se://<id|pattern> 형식인 환경변수는 해석된 시크릿으로 대체되고, 나머지는 그대로 통과돼요.

GH_TOKEN=se://gh-token docker pass run -- gh repo list

식별자 (Identifiers)

시크릿 ID는 계층적이고 경로 같은 문자열이에요. 구성 요소는 /로 구분되며, 각 구성 요소는 A-Z, a-z, 0-9, ., -, _, :를 포함할 수 있어요. 앞·뒤·빈 구성 요소는 허용되지 않아요. 매칭은 대소문자를 구분해요. 예측 가능한 레일름/네임스페이스 구조(예: docker/auth/<registry>, docker/db/<env>/password)는 자동화와 접근 제어를 더 쉽게 만들어요.

패턴 (Patterns)

패턴은 식별자와 같은 규칙을 따르되, 추가 토큰 두 개가 있어요:

* — 구성 요소 정확히 하나 매칭
** — 구성 요소 0개 이상 매칭

와일드카드는 구성 요소 전체를 차지해야 해요 (예: auth/*/token은 유효하고 auth/foo*는 아님), 그리고 단일 구성 요소에는 * 또는 ** 중 하나만 올 수 있어요.

패턴 예시:

docker/auth/** — 하위 레일름의 모든 Docker auth 시크릿
myrealm/*/password — myrealm 아래 한 단계 깊이의 패스워드 항목
** — 포괄 매칭

라우팅 (Routing)

컨테이너가 se://<id|pattern>을 참조하면 엔진은 선언된 패턴이 <id|pattern>과 매칭되는 모든 플러그인에 조회를 펼치고 응답을 병합해요. 매칭되는 플러그인이 없으면 조회가 실패하고 컨테이너가 시작되지 않아요.

플러그인 관리 (Plugin Management)

CLI를 사용해 로드되고 사용 가능한 플러그인을 검사해요:

docker pass plugins ls

configurable로 표시된 플러그인은 런타임에 활성화하거나 비활성화할 수 있어요:

docker pass plugins enable <name>
docker pass plugins disable <name>

플러그인 (Plugins)

OS 키체인 (OS Keychain)

플러그인 이름: docker-pass
스토리지 백엔드: 플랫폼별 API로 접근하는 로컬 OS 키체인
- Windows: Windows Credential Manager API
- macOS: Keychain Services API
- Linux: org.freedesktop.secrets API (DBus와 gnome-keyring 또는 kdewallet 같은 Secret Service 공급자 필요)
용도: docker pass로 직접 저장한 시크릿(및 1Password 서비스 계정 토큰 같은 다른 플러그인이 쓰는 내부 시크릿)을 보유. 항상 켜져 있으며 구성 불가.

1Password (configurable)

각 항목은 최대 세 개의 후보 ID 아래에서 요청된 패턴과 매칭돼요:

원시 항목 ID — 1Password가 할당하는 불투명한 영숫자 ID (예: alphanumeric_26char)
<vault-id>/<title> — 볼트의 ID와 항목의 정규화된 제목 결합
<vault-name>/<title> — 볼트의 표시 이름과 항목의 정규화된 제목 결합

정규화(볼트 이름과 제목에 적용)는 1Password의 시크릿 참조 구문을 따라요: 공백은 -가 되고, (와 )는 제거되며, /와 &는 _가 되고, [a-zA-Z0-9-._] 밖의 나머지 문자는 제거되며, 결과는 소문자로 변환돼요. 1Password의 매칭 규칙을 따르므로 플러그인은 대소문자를 구분하지 않으며, 기존 op:// 참조를 그대로 재사용할 수 있어요. 유효한 ID를 만들지 못하는 후보는 조용히 건너뛰므로, 특이한 이름의 항목도 다른 형식 중 하나로는 매칭될 수 있어요.

CLI 버전 (CLI version)

플러그인 이름: 1password-cli
인증 방법: op CLI에 위임. op가 설치되고 활성 1Password 세션이 있어야 해요. macOS에서는 보통 생체 인식 잠금 해제가 활성화된 1Password 데스크톱 앱을 의미하고, 다른 플랫폼에서는 op signin을 의미해요.
설정: 관리할 토큰이 없어요. 로컬 op가 로그인되어 있으면 플러그인이 시크릿을 해석할 수 있어요.
동작: Docker Desktop이 시작되면 플러그인이 모든 항목을 처음에 가져와 1Password 인증 프롬프트를 트리거해요. 그 결과 캐시는 주기적으로 새로고침돼요.
치명적 오류: 플러그인은 몇 가지 조건을 복구 불가로 간주하고 재시도 대신 스스로 중지해요:
- PATH에서 op 바이너리를 찾을 수 없음,
- 사용자가 1Password 인증 프롬프트를 취소하거나 타임아웃시킴. 이 경우 플러그인은 docker pass plugins ls에서 crashed로 보고돼요. 근본 문제를 해결(op 설치, 로그인, 프롬프트 수락)하고 docker pass plugins enable 1password-cli로 플러그인을 다시 활성화해요.

활성화 / 비활성화:

docker pass plugins enable 1password-cli
docker pass plugins disable 1password-cli

서비스 계정 토큰 버전 (Service account token version)

플러그인 이름: 1password-sdk
인증 방법: 노출하려는 볼트로 범위가 한정된 서비스 계정 토큰과 함께 공식 1Password Go SDK 사용
설정: 토큰을 stdin으로 한 번 제공해요. OS 키체인에 저장되고 같은 단계에서 플러그인이 활성화돼요:
```
echo "$OP_SERVICE_ACCOUNT_TOKEN" | docker pass plugins 1password setup
```
정리: 토큰을 제거하고 플러그인을 비활성화해요:
```
docker pass plugins 1password purge
```

피드백 및 SDK (Feedback and SDK)

github.com/docker/secrets-engine의 Go SDK를 사용해 자체 코드에 시크릿 해석을 통합하고, 사용자 정의 클라이언트를 만들거나 새 플러그인을 작성할 수 있어요.

기능 요청이나 버그가 있으면 github.com/docker/secrets-engine/issues에 이슈를 제출해요.

예시 (Examples)

컨테이너에서 키체인 시크릿 사용

시크릿 생성:

$ docker pass set GH_TOKEN=123456789

STDIN에서 시크릿 생성:

echo "my_val" | docker pass set GH_TOKEN

시크릿을 사용하는 컨테이너 실행:

$ docker run -e GH_TOKEN= -dt --name demo busybox

컨테이너 안에서 시크릿 검사:

$ docker exec demo sh -c 'echo $GH_TOKEN'
123456789

시크릿을 다른 환경변수에 명시적으로 할당:

$ docker run -e GITHUB_TOKEN=se://GH_TOKEN -dt --name demo busybox

Compose에서 키체인 시크릿 사용

시크릿 저장:

$ docker pass set myapp/anthropic/api-key=sk-ant-...
$ docker pass set myapp/postgres/password=s3cr3t

services:
  api:
    image: service1
    environment:
      - ANTHROPIC_API_KEY=se://myapp/anthropic/api-key
      - POSTGRES_PASSWORD=se://myapp/postgres/password

  worker:
    image: service2
    command: worker
    environment:
      - ANTHROPIC_API_KEY=se://myapp/anthropic/api-key

  db:
    image: postgres:17
    environment:
      - POSTGRES_PASSWORD=se://myapp/postgres/password

하위 명령 (Subcommands)

명령	설명
`docker pass get`	키스토어에서 시크릿 가져오기
`docker pass ls`	로컬 키체인의 모든 시크릿 나열
`docker pass plugins`	시크릿 엔진 플러그인 관리
`docker pass rm`	로컬 키체인에서 시크릿 제거
`docker pass run`	`se://` 환경 참조를 해석해 명령 실행
`docker pass set`	시크릿 설정