forked from baron/baron-sso
122 lines
4.1 KiB
Markdown
122 lines
4.1 KiB
Markdown
# 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` 기반 오프라인 배포
|
|
|
|
## 저장 구조
|
|
|
|
기본 최상위 디렉터리는 다음 환경 변수로 지정한다.
|
|
|
|
```dotenv
|
|
WORKS_SHAREDRIVE_DOCKER_IMAGE_DIR=docker-build-image
|
|
```
|
|
|
|
이미지는 WORKS Shared Drive에서 다음 구조로 저장한다.
|
|
|
|
```text
|
|
docker-build-image/<repository-path>/<tag>/
|
|
image.tar.zst
|
|
image.tar.zst.sha256
|
|
manifest.json
|
|
```
|
|
|
|
예시:
|
|
|
|
```text
|
|
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
|
|
- 복원 명령 예시
|
|
|
|
복원은 다음 흐름으로 처리한다.
|
|
|
|
```bash
|
|
sha256sum -c image.tar.zst.sha256
|
|
zstd -d -c image.tar.zst | docker load
|
|
```
|
|
|
|
## 업로드 CLI
|
|
|
|
로컬 컨테이너를 먼저 이미지로 commit한 뒤 업로드하려면 다음처럼 실행한다.
|
|
|
|
```bash
|
|
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`를 생략한다.
|
|
|
|
```bash
|
|
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만 확인하려면 다음을 사용한다.
|
|
|
|
```bash
|
|
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 계열을 사용한다.
|
|
|
|
```bash
|
|
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한다.
|
|
|
|
```text
|
|
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는 지원하지 않는다.
|