WORKS Drive Docker Image Archive

목적

WORKS Drive는 Docker Registry HTTP API v2 backend로 직접 사용하지 않는다. 대신 프로덕션 배포용 Docker 이미지를 docker save 결과물로 내보내고, zstd 압축 archive와 검증 파일을 WORKS Shared Drive에 보관하는 CLI 기반 보조 저장소로 사용한다.

이 방식은 다음 상황을 목표로 한다.

Harbor 또는 공용 Registry 장애 시 수동 복구용 이미지 보관
작은 규모의 프로덕션 배포 이미지 이관
docker load 기반 오프라인 배포

저장 구조

기본 최상위 디렉터리는 다음 환경 변수로 지정한다.

WORKS_SHAREDRIVE_DOCKER_IMAGE_DIR=docker-build-image

이미지는 WORKS Shared Drive에서 다음 구조로 저장한다.

docker-build-image/<repository-path>/<tag>/
  image.tar.zst
  image.tar.zst.sha256
  manifest.json

예시:

docker-build-image/baron_sso/backend/v1.2606.ab12/
  image.tar.zst
  image.tar.zst.sha256
  manifest.json

Registry hostname은 저장 경로에서 제외한다. 예를 들어 registry.example/baron_sso/backend:v1.2606.ab12는 baron_sso/backend/v1.2606.ab12 아래에 저장한다.

Manifest

manifest.json에는 다음 정보를 기록한다.

archive format: docker-save-zstd
원본 image_ref
repository path
tag
Docker image id
Git commit
archive 파일명, 크기, sha256
WORKS Drive remote path
복원 명령 예시

복원은 다음 흐름으로 처리한다.

sha256sum -c image.tar.zst.sha256
zstd -d -c image.tar.zst | docker load

업로드 CLI

로컬 컨테이너를 먼저 이미지로 commit한 뒤 업로드하려면 다음처럼 실행한다.

WORKS_SHAREDRIVE_DOCKER_IMAGE_DIR=docker-build-image \
WORKS_DOCKER_COMMIT_CONTAINER=baron_backend \
DOCKER_IMAGE_REF=registry.example/baron_sso/backend:v1.2606.ab12 \
scripts/docker-image/upload_works_drive.sh

이미지가 이미 로컬에 있으면 WORKS_DOCKER_COMMIT_CONTAINER를 생략한다.

DOCKER_IMAGE_REF=registry.example/baron_sso/backend:v1.2606.ab12 \
scripts/docker-image/upload_works_drive.sh

실제 업로드에는 기존 백업 업로드와 같은 WORKS Drive 인증 변수를 사용한다.

WORKS_DRIVE_TARGET=sharedrive
WORKS_DRIVE_SHARED_DRIVE_ID 또는 WORKS_SHAREDRIVE_ID
선택: WORKS_DRIVE_PARENT_FILE_ID
WORKS_DRIVE_ACCESS_TOKEN, WORKS_DRIVE_ACCESS_TOKEN_FILE, WORKS_DRIVE_ACCESS_TOKEN_CMD, WORKS_DRIVE_OAUTH_REFRESH_TOKEN, 또는 서비스 계정 OAuth 변수

업로드 전 packaging만 확인하려면 다음을 사용한다.

WORKS_DRIVE_DRY_RUN=true \
DOCKER_IMAGE_REF=registry.example/baron_sso/backend:v1.2606.ab12 \
scripts/docker-image/upload_works_drive.sh

smoke 검증에는 Alpine 계열보다 운영 환경과 libc/패키지 계열 차이가 적은 Debian slim 계열을 사용한다.

docker create --name baron-works-image-smoke debian:trixie-slim \
  sh -c 'printf works-drive-docker-image-smoke >/works-smoke.txt'
docker start -a baron-works-image-smoke
WORKS_DOCKER_COMMIT_CONTAINER=baron-works-image-smoke \
DOCKER_IMAGE_REF=registry.example/baron_sso/works-smoke:works-test-ab12 \
scripts/docker-image/upload_works_drive.sh

Staging/Production 계약

Action에서 dev 브랜치를 checkout한 뒤 한 번만 이미지를 빌드하고 immutable image_tag를 계산한다. staging과 production은 같은 image_tag를 입력받아 같은 registry image를 pull한다.

dev branch -> publish image tag vX.YYMM.<commit4> -> staging deploy -> production deploy

WORKS Drive archive도 Action에서 push된 이미지를 다시 pull한 뒤 docker save로 만든다. 따라서 WORKS archive, staging, production은 모두 같은 registry image tag를 기준으로 한다.

제한

이 구조는 docker push/docker pull과 호환되는 Registry backend가 아니다.
layer deduplication이 없으므로 같은 기반 이미지가 반복 저장된다.
배포 전에는 반드시 image.tar.zst.sha256 검증 후 docker load를 수행해야 한다.
tag 없는 image ref와 digest-only image ref는 지원하지 않는다.

4.1 KiB Raw Permalink Blame History

WORKS Drive Docker Image Archive

목적

저장 구조

Manifest

업로드 CLI

Staging/Production 계약

제한

4.1 KiB

Raw Permalink Blame History