웍스 드라이브 구조 변경

docs/works-drive-docker-image-archive.md

@@ -18,9 +18,9 @@ Gitea Actions의 shared image publish workflow는 `baron_sso/<service>:<image_ta
 
 업로드를 실행하려면 최소한 다음 값을 등록해야 한다.
 
-- variable `WORKS_SHAREDRIVE_DOCKER_IMAGE_DIR=docker-build-image`
-- variable `WORKS_DRIVE_SHARED_DRIVE_ID`
-- 선택 variable `WORKS_DRIVE_PARENT_FILE_ID`
+- 선택 variable `WORKS_DRIVE_DOCKER_IMAGE_DIR=baron-sso`
+- variable `WORKS_DRIVE_DOCKER_IMAGE_DRIVE_ID`
+- 선택 variable `WORKS_DRIVE_DOCKER_IMAGE_PARENT_FILE_ID`
 - secret `WORKS_DRIVE_ACCESS_TOKEN`, 또는 variable `WORKS_DRIVE_ACCESS_TOKEN_FILE`, 또는 variable `WORKS_DRIVE_ACCESS_TOKEN_CMD`, 또는 refresh-token 방식의 secret `WORKS_DRIVE_REFRESH_TOKEN`
 - refresh-token 방식을 쓸 경우 secret `WORKS_DRIVE_OAUTH_CLIENT_ID`, secret `WORKS_OAUTH_CLIENT_SECRET`
 
@@ -49,32 +49,32 @@ Refresh Token Rotation이 켜져 있으면 WORKS가 refresh 응답에 새 Refres
 기본 최상위 디렉터리는 다음 환경 변수로 지정한다.
 
 ```dotenv
-WORKS_SHAREDRIVE_DOCKER_IMAGE_DIR=docker-build-image
+WORKS_DRIVE_DOCKER_IMAGE_DIR=baron-sso
 ```
 
 이미지는 WORKS Shared Drive에서 다음 구조로 저장한다.
 
 ```text
-docker-build-image/<repository-path>/<tag>/
-  image.tar.zst
-  image.tar.zst.sha256
-  manifest.json
+baron-sso/<tag>/
+  <service>.<tag>.tar.zst
+  <service>.<tag>.sha256
+  manifest.<tag>.json
 ```
 
 예시:
 
 ```text
-docker-build-image/baron_sso/backend/v1.2606.ab12/
-  image.tar.zst
-  image.tar.zst.sha256
-  manifest.json
+baron-sso/v1.2606.ab12/
+  backend.v1.2606.ab12.tar.zst
+  backend.v1.2606.ab12.sha256
+  manifest.v1.2606.ab12.json
 ```
 
-Registry hostname은 저장 경로에서 제외한다. 예를 들어 `registry.example/baron_sso/backend:v1.2606.ab12`는 `baron_sso/backend/v1.2606.ab12` 아래에 저장한다.
+Registry hostname과 image namespace는 저장 경로에서 제외한다. 예를 들어 `registry.example/baron_sso/backend:v1.2606.ab12`는 `baron-sso/v1.2606.ab12/backend.v1.2606.ab12.tar.zst`로 저장한다.
 
 ## Manifest
 
-`manifest.json`에는 다음 정보를 기록한다.
+`manifest.<tag>.json`에는 다음 정보를 기록한다.
 
 - archive format: `docker-save-zstd`
 - 원본 `image_ref`
@@ -83,14 +83,15 @@ Registry hostname은 저장 경로에서 제외한다. 예를 들어 `registry.e
 - Docker image id
 - Git commit
 - archive 파일명, 크기, sha256
+- 서비스별 archive 정보 (`images.<service>`)
 - WORKS Drive remote path
 - 복원 명령 예시
 
 복원은 다음 흐름으로 처리한다.
 
 ```bash
-sha256sum -c image.tar.zst.sha256
-zstd -d -c image.tar.zst | docker load
+sha256sum -c backend.v1.2606.ab12.sha256
+zstd -d -c backend.v1.2606.ab12.tar.zst | docker load
 ```
 
 ## 업로드 CLI
@@ -98,7 +99,7 @@ zstd -d -c image.tar.zst | docker load
 로컬 컨테이너를 먼저 이미지로 commit한 뒤 업로드하려면 다음처럼 실행한다.
 
 ```bash
-WORKS_SHAREDRIVE_DOCKER_IMAGE_DIR=docker-build-image \
+WORKS_DRIVE_DOCKER_IMAGE_DIR=baron-sso \
 WORKS_DOCKER_COMMIT_CONTAINER=baron_backend \
 DOCKER_IMAGE_REF=registry.example/baron_sso/backend:v1.2606.ab12 \
 scripts/docker-image/upload_works_drive.sh
@@ -111,11 +112,11 @@ DOCKER_IMAGE_REF=registry.example/baron_sso/backend:v1.2606.ab12 \
 scripts/docker-image/upload_works_drive.sh
 ```
 
-실제 업로드에는 기존 백업 업로드와 같은 WORKS Drive 인증 변수를 사용한다.
+실제 업로드에는 기존 백업 업로드와 같은 WORKS Drive 인증 변수를 사용하되, Docker image archive 대상 drive/folder는 백업 변수와 분리한다.
 
 - `WORKS_DRIVE_TARGET=sharedrive`
-- `WORKS_DRIVE_SHARED_DRIVE_ID` 또는 `WORKS_SHAREDRIVE_ID`
-- 선택: `WORKS_DRIVE_PARENT_FILE_ID`
+- `WORKS_DRIVE_DOCKER_IMAGE_DRIVE_ID`
+- 선택: `WORKS_DRIVE_DOCKER_IMAGE_PARENT_FILE_ID`
 - `WORKS_DRIVE_ACCESS_TOKEN`, `WORKS_DRIVE_ACCESS_TOKEN_FILE`, `WORKS_DRIVE_ACCESS_TOKEN_CMD`, `WORKS_DRIVE_OAUTH_REFRESH_TOKEN`, 또는 서비스 계정 OAuth 변수
 
 업로드 전 packaging만 확인하려면 다음을 사용한다.
@@ -133,9 +134,9 @@ dry-run도 실제 `docker save`, `zstd`, checksum, manifest 생성을 수행한
 WORKS Drive에서 다음 세 파일을 같은 로컬 디렉터리로 내려받은 뒤 검증한다.
 
 ```text
-image.tar.zst
-image.tar.zst.sha256
-manifest.json
+backend.v1.2606.ab12.tar.zst
+backend.v1.2606.ab12.sha256
+manifest.v1.2606.ab12.json
 ```
 
 checksum, manifest, zstd stream 무결성만 확인하려면 다음을 실행한다.
@@ -160,13 +161,20 @@ scripts/docker-image/verify_archive.sh /path/to/downloaded/archive
 
 검증은 다음 조건을 모두 확인한다.
 
-- `image.tar.zst.sha256` checksum 성공
-- `manifest.json`의 `schema_version=1`, `format=docker-save-zstd`
+- `<service>.<tag>.sha256` checksum 성공
+- `manifest.<tag>.json`의 `schema_version=1`, `format=docker-save-zstd`
 - manifest의 archive 파일명, sha256, size와 실제 파일 일치
 - `zstd -t` 무결성 성공
 - 선택적으로 `docker load` 성공
 
-현재 repo에는 WORKS Drive API에서 파일을 자동 다운로드하는 CLI는 없다. 따라서 자동 다운로드 스크립트를 만들기 전까지는 WORKS Drive UI 또는 운영자가 승인한 API 도구로 세 파일을 내려받고, 위 검증 CLI로 복원 가능성을 확인한다.
+현재 repo의 `scripts/docker-image/download_works_drive.sh`는 `WORKS_DRIVE_DOCKER_IMAGE_DRIVE_ID`와 `IMAGE_TAG`를 사용해 `baron-sso/<tag>/`의 archive, checksum, manifest를 내려받고 checksum/manifest 검증 후 `docker load`를 수행한다.
+
+```bash
+WORKS_DRIVE_DOCKER_IMAGE_DRIVE_ID=@2001000000547281 \
+WORKS_DRIVE_ACCESS_TOKEN=<access-token> \
+IMAGE_TAG=v1.2606.ab12 \
+scripts/docker-image/download_works_drive.sh
+```
 
 API로 다운로드할 때는 대상 archive 폴더의 children을 조회해 각 파일의 `fileId`를 얻은 뒤 다음 endpoint를 호출한다.
 
@@ -179,7 +187,7 @@ GET /v1.0/sharedrives/<sharedDriveId>/files/<fileId>/download
 ```bash
 curl -sS -L --location-trusted \
   -H "Authorization: Bearer <access-token>" \
-  -o image.tar.zst \
+  -o backend.v1.2606.ab12.tar.zst \
   "https://www.worksapis.com/v1.0/sharedrives/<sharedDriveId>/files/<fileId>/download"
 ```
 
@@ -224,5 +232,5 @@ WORKS Drive archive는 Action에서 로컬로 빌드된 이미지를 `docker sav
 
 - 이 구조는 `docker push`/`docker pull`과 호환되는 Registry backend가 아니다.
 - layer deduplication이 없으므로 같은 기반 이미지가 반복 저장된다.
-- 배포 전에는 반드시 `image.tar.zst.sha256` 검증 후 `docker load`를 수행해야 한다.
+- 배포 전에는 반드시 `<service>.<tag>.sha256` 검증 후 `docker load`를 수행해야 한다.
 - tag 없는 image ref와 digest-only image ref는 지원하지 않는다.