컨테이너 메타데이터 관리

이 페이지에서는 컨테이너화하고, Artifact Registry에 업로드하고, Artifact Registry에 저장된 컨테이너 이미지에 대한 메타데이터를 첨부파일로 관리하는 방법을 설명합니다.

첨부파일은 OCI 아티팩트이며 Docker 형식 저장소에만 저장할 수 있습니다.

시작하기 전에

아직 만들지 않았으면 Docker 형식 표준 저장소를 만듭니다.
(선택사항) Google Cloud CLI 명령어의 기본값을 구성합니다.

필요한 역할

첨부파일을 관리하는 데 필요한 권한을 얻으려면 관리자에게 저장소에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

첨부파일 보기 및 다운로드: Artifact Registry 리더(roles/artifactregistry.reader)
첨부파일 만들기: Artifact Registry 작성자(roles/artifactregistry.writer)
첨부파일 삭제: Artifact Registry 저장소 관리자(roles/artifactregistry.repoAdmin)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

Oras 설정(선택사항)

gcloud CLI를 사용하는 것 외에도 원하는 경우 Oras를 사용하여 첨부파일을 만들고, 나열하고, 다운로드할 수 있습니다.

Oras 1.2 이상을 설치합니다. 버전을 확인하려면 oras version 명령어를 실행합니다.
Artifact Registry로 인증하도록 Oras를 구성합니다.

첨부파일 만들기

gcloud CLI 또는 Oras를 사용하여 첨부파일을 만들 수 있습니다.

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

ATTACHMENT: 첨부파일의 정규화된 이름입니다. 예를 들면 projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment입니다. 또는 첨부파일 ID만 제공하고 --location 및 --repository 플래그를 사용합니다.
TARGET: 첨부파일이 참조하는 아티팩트의 정규화된 버전 이름 또는 Artifact Registry URI입니다. 다이제스트 또는 태그 중 하나를 사용할 수 있습니다. 예를 들면 us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1입니다.
TYPE: 첨부파일의 type 속성입니다. 이는 artifactType 속성에 대한 OCI 사양을 준수해야 합니다.
ATTACHMENT_NAMESPACE: 첨부파일 데이터 소스를 식별하는 첨부파일 관련 변수입니다. 예를 들면 example.com입니다.
FILES: 첨부파일에 포함할 로컬 파일의 쉼표로 구분된 목록입니다.

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud artifacts attachments create ATTACHMENT \
    --target=TARGET \
    --type=TYPE \
    --attachment-namespace=ATTACHMENT_NAMESPACE \
    --files=FILES

Windows(PowerShell)

gcloud artifacts attachments create ATTACHMENT `
    --target=TARGET `
    --type=TYPE `
    --attachment-namespace=ATTACHMENT_NAMESPACE `
    --files=FILES

Windows(cmd.exe)

gcloud artifacts attachments create ATTACHMENT ^
    --target=TARGET ^
    --type=TYPE ^
    --attachment-namespace=ATTACHMENT_NAMESPACE ^
    --files=FILES

gcloud artifacts attachments create

Oras

Oras로 첨부파일을 만들 때 Artifact Registry는 첨부파일 이름으로 사용할 임의의 UUID를 생성합니다.

명령어를 실행하기 전에 다음을 바꿉니다.

ARTIFACT_TYPE: 첨부파일의 artifactType입니다.
IMAGE_URI: 첨부파일이 참조하는 이미지 컨테이너의 URI입니다.
FILE: 첨부파일에 메타데이터로 포함할 로컬 파일입니다.
MEDIA_TYPE: 레이어의 mediaType입니다.

  oras attach --artifact-type ARTIFACT_TYPE IMAGE_URI FILE:MEDIA_TYPE

다음 예시에서는 URI 및 태그로 식별되는 컨테이너 이미지 my-image를 참조하는 파일 hello-world.txt로 구성된 첨부파일을 만듭니다.

  oras attach --artifact-type doc/example \
  us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 \
  hello-world.txt:application/vnd.me.hi

각 항목의 의미는 다음과 같습니다.

doc/example은 첨부파일의 artifactType 속성을 정의합니다.
us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1은 첨부파일이 참조하는 컨테이너 이미지 버전의 태그를 포함하는 URI입니다.
hello-world.txt는 첨부파일이 데이터로 포함하는 로컬 파일입니다.
application/vnd.me.hi는 레이어의 mediaType을 정의합니다.

전체 가이드와 더 많은 예시는 oras attach 문서를 참조하세요.

첨부파일 나열

컨테이너 이미지에는 이를 참조하는 첨부파일이 여러 개 있을 수 있습니다. Google Cloud 콘솔, gcloud CLI 또는 Oras를 사용하여 첨부파일을 나열할 수 있습니다.

콘솔

Google Cloud 콘솔에서 저장소 페이지를 엽니다.

저장소 페이지 열기
저장소 이름을 클릭하여 저장소의 이미지를 확인합니다.
이미지 버전을 보려면 이미지 이름을 클릭합니다.
적절한 이미지 버전을 클릭합니다.
해당 버전의 첨부파일을 보려면 첨부파일 탭을 클릭합니다.

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

TARGET: 첨부파일을 나열할 아티팩트의 정규화된 버전 이름 또는 Artifact Registry URI입니다. 다이제스트 또는 태그 중 하나를 사용할 수 있습니다. 예를 들면 us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1입니다.

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud artifacts attachments list \
    --target=TARGET

Windows(PowerShell)

gcloud artifacts attachments list `
    --target=TARGET

Windows(cmd.exe)

gcloud artifacts attachments list ^
    --target=TARGET

자세한 내용은 gcloud artifacts attachments list 명령어를 참조하세요.

Oras

명령어를 실행하기 전에 다음을 바꿉니다.

IMAGE_URI: 나열된 첨부파일에서 참조하는 타겟 이미지의 URI입니다.

oras discover --distribution-spec v1.1-referrers-api IMAGE_URI

다음 예시에서는 URI 및 태그로 식별되는 컨테이너 이미지 my-image의 첨부파일을 보여줍니다.

oras discover --distribution-spec v1.1-referrers-api \
us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1

각 항목의 의미는 다음과 같습니다.

v1.1-referrers-api는 사용된 Referrer API입니다. 자세한 내용은 배포 사양의 세부정보를 참조하세요.
us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1은 첨부파일을 나열할 컨테이너 이미지 버전의 태그를 포함하는 URI입니다.

전체 가이드와 더 많은 예시는 oras discover 문서를 참조하세요.

첨부파일 다운로드

gcloud CLI 또는 Oras를 사용하여 첨부파일을 다운로드할 수 있습니다.

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

ATTACHMENT: 첨부파일의 정규화된 이름입니다. 예를 들면 projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment입니다. 또는 여기에 첨부파일 ID만 제공하고 --location 및 --repository 플래그를 사용합니다.
DESTINATION: 로컬 파일 시스템에서 첨부파일을 다운로드할 경로입니다.

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud artifacts attachments download ATTACHMENT \
    --destination=DESTINATION

Windows(PowerShell)

gcloud artifacts attachments download ATTACHMENT `
    --destination=DESTINATION

Windows(cmd.exe)

gcloud artifacts attachments download ATTACHMENT ^
    --destination=DESTINATION

ATTACHMENT를 제공하는 대신 --oci-version-name 플래그와 첨부파일의 정식 버전 이름 또는 Artifact Registry URI를 차례로 제공할 수 있습니다. 다이제스트 또는 태그 중 하나를 사용할 수 있습니다. 예를 들면 projects/my-project/locations/us-west1/repositories/my-repo/packages/my-package/versions/sha256:abc123입니다.

자세한 내용은 gcloud artifacts attachments download 명령어를 참조하세요.

Oras

명령어를 실행하기 전에 다음을 바꿉니다.

DESTINATION: 첨부파일의 대상 디렉터리입니다.
ATTACHMENT_URI: 다운로드할 첨부파일의 URI입니다. 첨부파일이 참조하는 이미지 컨테이너의 URI이며 그 뒤에 첨부파일의 고유 SHA가 옵니다.

oras pull -o DESTINATION ATTACHMENT_URI

다음 예시에서는 URI 및 다이제스트로 식별된 첨부파일을 다운로드합니다.

oras pull -o . us-west1-docker.pkg.dev/my-project/my-repo/my-image@sha256:xxxx

각 항목의 의미는 다음과 같습니다.

-o .는 현재 디렉터리를 다운로드 대상으로 이름을 지정합니다.
us-west1-docker.pkg.dev/my-project/my-repo/my-image@sha256:xxxx는 다운로드할 첨부파일의 다이제스트를 포함하는 이미지 URI입니다.

전체 가이드와 더 많은 예시는 oras pull 문서를 참조하세요.

첨부파일 삭제

Google Cloud 콘솔 또는 gcloud CLI를 사용하여 첨부파일을 직접 삭제할 수 있습니다. 참조하는 컨테이너 이미지를 삭제하여 첨부파일을 간접적으로 삭제할 수 있습니다.

직접적으로 첨부파일 삭제

다음 옵션 중 하나를 사용하여 첨부파일을 직접 삭제할 수 있습니다.

콘솔

Google Cloud 콘솔에서 저장소 페이지를 엽니다.

저장소 페이지 열기
저장소 이름을 클릭하여 저장소의 이미지를 확인합니다.
이미지 이름을 클릭하여 이미지의 버전을 확인합니다.
첨부파일을 보려는 이미지의 버전을 클릭합니다.
첨부파일 탭을 클릭하여 해당 버전의 첨부파일을 확인합니다.
삭제할 첨부파일의 다이제스트를 클릭합니다.
삭제를 클릭합니다.
확인 대화상자에서 삭제를 클릭합니다.

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

ATTACHMENT: 첨부파일의 정규화된 이름입니다. 예를 들면 projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment입니다. 또는 여기에 첨부파일 ID만 제공하고 --location 및 --repository 플래그를 사용합니다.

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud artifacts attachments delete ATTACHMENT

Windows(PowerShell)

gcloud artifacts attachments delete ATTACHMENT

Windows(cmd.exe)

gcloud artifacts attachments delete ATTACHMENT

자세한 내용은 gcloud artifacts attachments list 명령어를 참조하세요.

간접적으로 첨부파일 삭제

컨테이너 이미지가 삭제되면 참조하는 모든 첨부파일도 삭제됩니다. 이는 컨테이너 이미지의 수동 삭제와 삭제 정책으로 인한 삭제 모두에 적용됩니다.