DHI CLI 사용하기

DHI CLI 사용하기

docker dhi 명령줄 인터페이스(CLI)를 설치·구성하고, 카탈로그 탐색, attestation 조회, 이미지 미러링·커스터마이즈, 엔터프라이즈 패키지 인증, 빌드 모니터링 등을 수행하는 방법을 알아봐요.

출처: 문서

본문

docker dhi CLI는 Docker Hardened Images를 관리하는 도구예요.

  • 사용 가능한 DHI 이미지와 그 메타데이터의 카탈로그 탐색
  • SBOM과 provenance를 포함한 DHI 이미지의 attestation 조회
  • DHI 이미지를 Docker Hub 조직으로 미러링
  • DHI 이미지의 커스터마이즈 생성 및 관리
  • 엔터프라이즈 패키지 저장소용 인증 생성
  • 커스터마이즈 빌드 모니터링

설치(Installation)

docker dhi CLI는 Docker Desktop 버전 4.65 이상에서 사용할 수 있어요. 독립형 dhictl 바이너리를 설치할 수도 있어요.

Docker Desktop

docker dhi 명령은 Docker Desktop 4.65 이상에 포함되어 있어요. 추가 설치가 필요 없어요.

독립형 바이너리(Standalone binary)

  1. releases 페이지에서 플랫폼용 dhictl 바이너리를 다운로드해요.
  2. PATH에 있는 디렉터리로 이동해요.
    • _Linux_와 _macOS_에서는 mv dhictl /usr/local/bin/
    • _Windows_에서는 dhictl.exe를 PATH에 있는 디렉터리로 이동

사용법(Usage)

모든 명령에는 --help 플래그로 접근할 수 있는 내장 도움말이 있어요.

$ docker dhi --help
$ docker dhi catalog list --help

DHI 카탈로그 탐색

사용 가능한 모든 DHI 이미지 나열:

$ docker dhi catalog list

유형, 이름, 컴플라이언스로 필터링:

$ docker dhi catalog list --type image
$ docker dhi catalog list --filter golang
$ docker dhi catalog list --fips
$ docker dhi catalog list --stig

사용 가능한 태그와 CVE 수를 포함한 특정 이미지의 세부 정보 가져오기:

$ docker dhi catalog get <image-name>

Attestation 조회

DHI 이미지에 첨부된 모든 attestation 나열:

$ docker dhi attestation list dhi/nginx:1.27
$ docker dhi attestation list dhi/nginx:1.27 --platform linux/amd64
$ docker dhi attestation list dhi/nginx:1.27 --predicate-type https://slsa.dev/provenance/v1
$ docker dhi attestation list dhi/nginx:1.27 --json

referrer digest로 특정 attestation 가져오기:

$ docker dhi attestation get dhi/nginx:1.27 sha256:<digest>
$ docker dhi attestation get dhi/nginx:1.27 sha256:<digest> -o provenance.json

이미지의 SPDX SBOM 표시:

$ docker dhi attestation sbom dhi/nginx:1.27
$ docker dhi attestation sbom dhi/nginx:1.27 --platform linux/amd64

DHI 이미지 미러링

하나 이상의 DHI 이미지를 Docker Hub 조직으로 미러링 시작:

$ docker dhi mirror start --org my-org \
  dhi/golang,my-org/dhi-golang \
  dhi/nginx,my-org/dhi-nginx \
  dhi/prometheus-chart,my-org/dhi-prometheus-chart

의존성과 함께 미러링:

$ docker dhi mirror start --org my-org dhi/golang,my-org/dhi-golang --dependencies

조직의 미러링된 이미지 나열:

$ docker dhi mirror list --org my-org

미러링된 이미지를 이름이나 유형으로 필터링:

$ docker dhi mirror list --org my-org --filter python
$ docker dhi mirror list --org my-org --type image
$ docker dhi mirror list --org my-org --type helm-chart

하나 이상의 이미지 미러링 중지:

$ docker dhi mirror stop dhi-golang --org my-org
$ docker dhi mirror stop dhi-python dhi-golang --org my-org

미러링 중지 및 저장소 삭제:

$ docker dhi mirror stop dhi-golang --org my-org --delete
$ docker dhi mirror stop dhi-golang --org my-org --delete --force

DHI 이미지 커스터마이즈

CLI를 사용해 DHI 이미지 커스터마이즈를 생성·관리할 수 있어요. GUI로 커스터마이즈를 만드는 자세한 지침은 Customize a Docker Hardened Image 문서를 봐요.

다음은 CLI 명령에 대한 빠른 참조예요. 모든 옵션과 플래그의 전체 세부 정보는 CLI reference를 봐요.

# 단일 커스터마이즈 스캐폴드 준비
$ docker dhi customization prepare golang 1.25 \
  --org my-org \
  --destination my-org/dhi-golang \
  --name "golang with git" \
  > my-customization.yaml

# 벌크 커스터마이즈 스캐폴드 준비(stdin으로 JSON 배열 파이프)
$ echo '[{"destination":"my-org/dhi-golang","tag-definition-id":"golang/alpine-3.23/1.24-dev"}]' \
  | docker dhi customization prepare --name "golang with git" --org my-org \
  > my-customization.yaml

# 커스터마이즈 생성
$ docker dhi customization create my-customization.yaml --org my-org

# 플래그 오버라이드로 생성(플래그가 YAML 파일보다 우선)
$ docker dhi customization create my-customization.yaml --org my-org \
  --destination my-org/dhi-golang \
  --name "golang with git"

# 커스터마이즈 나열
$ docker dhi customization list --org my-org

# 커스터마이즈를 이름, 저장소, 소스로 필터링
$ docker dhi customization list --org my-org --filter git
$ docker dhi customization list --org my-org --repo dhi-golang
$ docker dhi customization list --org my-org --source golang

# ID로 커스터마이즈 가져오기
$ docker dhi customization get <id> --org my-org

# 커스터마이즈 업데이트
# YAML 파일에는 업데이트할 커스터마이즈를 식별하는 'id' 필드가 포함되어야 함
$ docker dhi customization edit my-customization.yaml --org my-org

# ID로 커스터마이즈 삭제
$ docker dhi customization delete <id> --org my-org

# 여러 커스터마이즈 삭제
$ docker dhi customization delete <id1> <id2> --org my-org

# 확인 프롬프트 없이 삭제
$ docker dhi customization delete <id> --org my-org --force

모든 YAML 필드의 전체 참조는 Image customization YAML file을 봐요.

엔터프라이즈 패키지 인증

엔터프라이즈 강화 패키지 저장소에 접근하기 위한 인증 자격 증명을 생성해요. 이 자격 증명은 패키지 매니저를 구성해 규정 준수·보안 패치된 패키지를 자체 이미지에 설치할 때 사용돼요. 자세한 지침은 Enterprise repository를 봐요.

Alpine 기반 이미지의 경우:

$ docker dhi auth apk

Debian 기반 이미지의 경우:

$ docker dhi auth deb

커스터마이즈 빌드 모니터링

커스터마이즈의 빌드 나열:

$ docker dhi customization build list <customization-id> --org my-org
$ docker dhi customization build list <customization-id> --org my-org --json

특정 빌드의 세부 정보 가져오기:

$ docker dhi customization build get <customization-id> <build-id> --org my-org
$ docker dhi customization build get <customization-id> <build-id> --org my-org --json

빌드 로그 보기:

$ docker dhi customization build logs <customization-id> <build-id> --org my-org
$ docker dhi customization build logs <customization-id> <build-id> --org my-org --json

JSON 출력

대부분의 list 및 get 명령은 기계가 읽을 수 있는 출력을 위한 --json 플래그를 지원해요.

$ docker dhi catalog list --json
$ docker dhi catalog get golang --json
$ docker dhi attestation list dhi/nginx:1.27 --json
$ docker dhi mirror list --org my-org --json
$ docker dhi mirror start --org my-org dhi/golang,my-org/dhi-golang --json
$ docker dhi customization list --org my-org --json
$ docker dhi customization build list <customization-id> --org my-org --json

구성(Configuration)

docker dhi CLI는 다음 위치의 YAML 파일로 구성할 수 있어요.

  • _Linux_와 _macOS_에서는 $HOME/.config/dhictl/config.yaml
  • _Windows_에서는 %USERPROFILE%\.config\dhictl\config.yaml

$XDG_CONFIG_HOME이 설정되어 있으면 구성 파일은 $XDG_CONFIG_HOME/dhictl/config.yaml에 위치해요.

사용 가능한 구성 옵션:

옵션 환경 변수 설명
org DHI_ORG 미러 및 커스터마이즈 명령의 기본 Docker Hub 조직.
api_token DHI_API_TOKEN 개인 액세스 토큰(PAT) 또는 조직 액세스 토큰(OAT)을 액세스 토큰으로 교환해 얻는 인증용 액세스 토큰.

환경 변수가 구성 파일 값보다 우선해요.

액세스 토큰을 얻으려면 개인 액세스 토큰(PAT) 또는 조직 액세스 토큰(OAT)을 교환해요.

$ export DHI_API_TOKEN=$(curl -s -X POST https://hub.docker.com/v2/auth/token \
  -H "Content-Type: application/json" \
  -d '{"identifier": "<identifier>", "secret": "<token>"}' \
  | jq -r .access_token)

PAT의 경우 identifier에 Docker Hub 사용자 이름을, OAT의 경우 조직 이름을 사용해요.

더 알아보기 (Learn more)