이미지 내보내기 및 가져오기

이 페이지에서는 Docker를 사용하여 컨테이너 이미지를 가져오고 내보내는 방법을 설명합니다. 또한 Google Kubernetes Engine에서 문제를 해결하는 경우 crictl 도구를 사용하여 이미지를 가져오는 방법도 설명합니다.

Google Cloud 런타임 환경에 배포에 대한 자세한 내용은 Google Cloud에 배포를 참조하세요.

이미지 나열, 태그 지정 및 삭제에 대한 안내는 이미지 관리를 참조하세요.

시작하기 전에

1. 대상 저장소가 없으면 새 저장소를 만듭니다.
2. 저장소에 최소한 Artifact Registry 작성자 액세스 권한이 있어야 합니다.
3. Docker가 아직 설치되어 있지 않으면 설치합니다.

필요한 역할

이미지를 푸시하고 가져오는 데 필요한 권한을 얻으려면 관리자에게 저장소에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

• 이미지 가져오기: Artifact Registry 리더(roles/artifactregistry.reader)
• 이미지 태그 지정 및 푸시하기: Artifact Registry 작성자(roles/artifactregistry.writer)

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

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

저장소에 인증

Docker 또는 Docker 저장소가 있는 다른 제3자 클라이언트를 사용할 때마다 저장소에 인증을 수행해야 합니다. 이 섹션에서는 성공적인 인증 수행을 위해 필요한 항목에 대한 빠른 요약 정보를 제공합니다. 자세한 내용은 Docker 인증 설정을 참조하세요.

사용자 인증 정보 도우미 사용

gcloud CLI 사용자 인증 정보 도우미 또는 독립형 사용자 인증 정보 도우미의 경우 사용되는 Artifact Registry 호스트는 Docker 구성 파일에 있어야 합니다.

Artifact Registry는 Docker 구성 파일에 모든 레지스트리 호스트를 자동으로 추가하지 않습니다. 구성된 레지스트리가 많으면 Docker 응답 시간이 현저히 느려집니다. 구성 파일에서 레지스트리 수를 최소화하기 위해 필요한 호스트를 파일에 추가합니다.

어떤 호스트가 구성되었는지 확인하기 위해 다음 명령어를 실행해서 구성 파일의 콘텐츠를 표시합니다.

• Linux: cat ~/.docker/config.json
• Windows: cat %USERPROFILE%\.docker\config.json

credHelpers 섹션에 구성된 Artifact Registry Docker 호스트가 나열됩니다. 호스트 이름은 -docker.pkg.dev로 끝납니다. 다음 예시는 gcloud CLI 사용자 인증 정보 도우미에 대해 구성된 일부 호스트를 보여줍니다.

"credHelpers": {
  "asia.gcr.io": "gcloud",
  "eu.gcr.io": "gcloud",
  "gcr.io": "gcloud",
  "marketplace.gcr.io": "gcloud",
  "northamerica-northeast1-docker.pkg.dev": "gcloud",
  "us-central1-docker.pkg.dev": "gcloud",
  "us-east1-docker.pkg.dev": "gcloud",
  "us.gcr.io": "gcloud"
}

사용하려는 호스트가 목록에 없으면 사용자 인증 정보 도우미를 다시 실행하여 호스트를 추가합니다. 예를 들어 다음 명령어는 us-west1-docker.pkg.dev를 추가합니다.

• gcloud CLI 사용자 인증 정보 도우미

  gcloud auth configure-docker us-west1-docker.pkg.dev
  

• 독립형 사용자 인증 정보 도우미

  docker-credential-gcr configure-docker us-west1-docker.pkg.dev
  

액세스 토큰 사용

액세스 토큰 인증의 경우 토큰을 생성하고 이를 docker login 명령어에 비밀번호로 사용합니다. 토큰은 60분 동안 유효하므로, 이미지에 대해 태그 지정, 내보내기 또는 가져오기를 수행하기 전에 바로 인증을 수행해야 합니다.

다음 예시에서는 서비스 계정 가장을 사용하여 액세스 토큰을 생성한 후 Artifact Registry에 인증을 수행합니다. 이 방법으로 토큰을 생성하려면 서비스 계정 토큰 생성자 역할(roles/iam.serviceAccountTokenCreator)의 권한이 있어야 합니다.

Linux

gcloud auth print-access-token \
  --impersonate-service-account  ACCOUNT | docker login \
  -u oauth2accesstoken \
  --password-stdin https://LOCATION-docker.pkg.dev

Windows

gcloud auth print-access-token \
--impersonate-service-account  ACCOUNT

ya29.8QEQIfY_...

docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
https://LOCATION-docker.pkg.dev

서비스 계정을 가장할 권한이 없는 경우 gcloud CLI 세션에서 서비스 계정을 활성화하고 토큰을 가져옵니다. 자세한 내용은 액세스 토큰 인증 설정 안내를 참조하세요.

서비스 계정 키 사용

서비스 계정 키의 경우 키를 docker login 명령어의 암호로 사용합니다.

예를 들어 다음 명령어는 key.json 파일의 base64로 인코딩된 서비스 계정 키를 사용하여 us-west1-docker.pkg.dev에 인증을 수행합니다.

Linux

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-west1-docker.pkg.dev

Windows

docker login -u _json_key_base64 --password-stdin https://us-west1-docker.pkg.dev < key.json

자세한 내용은 서비스 계정 키 인증 설정 안내를 참조하세요.

이미지 푸시하기

저장소 모드: 표준

로컬 이미지를 표준 Docker 저장소로 푸시하려면 저장소 이름으로 태그를 지정한 후 이미지를 푸시합니다.

Artifact Registry Docker 저장소에 태그 불변성을 사용 설정한 경우 태그는 항상 저장소에서 동일한 이미지 다이제스트를 참조해야 합니다. 저장소에 푸시하는 동일한 이미지의 다른 버전에서 태그를 사용할 수 없습니다. 이미지 다이제스트, 태그, 태그 불변성에 대한 자세한 내용은 컨테이너 이미지 버전을 참조하세요.

대용량 이미지의 경우 다음 제한 사항이 적용됩니다.

업로드 시간

액세스 토큰을 사용하여 Artifact Registry에 인증하면 토큰은 60분 동안만 유효합니다. 업로드 시간이 60분을 초과할 것으로 예상되는 경우 다른 인증 방법을 사용하세요.

이미지 크기

최대 아티팩트 크기는 5TB입니다.

Artifact Registry는 Docker의 청크 업로드를 지원하지 않습니다. 일부 도구는 청크 업로드 또는 단일 모놀리식 업로드로 대용량 이미지의 업로드를 지원합니다. 이미지를 Artifact Registry로 푸시할 때는 모놀리식 업로드를 사용해야 합니다.

로컬 이미지에 태그 지정

1. 저장소에 인증되어 있는지 확인합니다.

2. 이미지 이름을 확인합니다. 전체 이미지 이름 형식은 다음과 같습니다.

   LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
   

   다음 값을 바꿉니다.

   • LOCATION은 이미지가 저장된 저장소의 리전 또는 멀티 리전 위치입니다.

   • PROJECT-ID는 Google Cloud 콘솔 프로젝트 ID입니다. 프로젝트 ID에 콜론(`:`)이 포함되어 있으면 도메인 범위 프로젝트를 참조하세요.

   • REPOSITORY는 이미지가 저장된 저장소의 이름입니다.

   • IMAGE는 이미지의 이름입니다. 이미지의 로컬 이름과 다를 수도 있습니다.

   예를 들어 다음과 같은 특성을 지닌 이미지라고 가정해 보겠습니다.

   • 저장소 위치: us-west1
   • 저장소 이름: my-repo
   • 프로젝트 ID: my-project
   • 로컬 이미지 이름: my-image
   • 대상 이미지 이름: test-image

   이 예시의 이미지 이름은 다음과 같습니다.

   us-west1-docker.pkg.dev/my-project/my-repo/test-image
   

   참고: 저장소에 저장할 이미지 이름은 로컬 머신의 이미지 이름과 다를 수 있습니다.

   도메인 범위 프로젝트 처리를 포함하여 이미지 이름 형식에 대한 자세한 내용은 저장소 및 이미지 이름을 참조하세요.

3. 저장소 이름으로 로컬 이미지에 태그를 지정합니다.

   docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   SOURCE-IMAGE를 로컬 이미지 이름 또는 이미지 ID로 바꾸고 TAG를 태그로 바꿉니다. 태그를 지정하지 않으면 Docker가 기본 latest 태그를 적용합니다.

   변경할 수 없는 이미지 태그 설정이 사용 설정된 경우 latest 태그를 포함하여 각 이미지 버전에서 태그가 고유해야 합니다. 저장소에 있는 동일한 이미지의 다른 버전에서 이미 태그를 사용 중인 경우 저장소에 이미지를 푸시할 수 없습니다. 이 설정이 저장소에 사용 설정되어 있는지 확인하려면 다음 명령어를 실행합니다.

   gcloud artifacts repositories describe REPOSITORY \
       --project=PROJECT-ID \
       --location=LOCATION
   

   이전 단계의 예시 이미지에서 로컬 이미지 my-image가 현재 디렉터리에 있으면 다음 명령어를 사용합니다.

   docker tag my-image us-west1-docker.pkg.dev/my-project/my-repo/test-image
   

   특정 태그를 적용하려면 다음 명령어를 사용합니다.

   docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   예시 이미지에 staging 태그를 사용하려면 명령어에 :staging을 추가합니다.

   docker tag my-image us-west1-docker.pkg.dev/my-project/my-repo/test-image:staging
   

태그가 지정된 이미지를 Artifact Registry로 내보내기

참고: Artifact Registry는 Docker 청크 업로드를 지원하지 않습니다. 일부 컨테이너 이미지 도구는 청크 업로드 또는 단일 모놀리식 업로드로 대용량 컨테이너 이미지의 업로드를 지원합니다. 컨테이너 이미지를 Artifact Registry로 내보낼 때는 모놀리식 업로드를 사용해야 합니다.

1. 저장소에 인증되어 있는지 확인합니다.

   Docker 클라이언트를 구성하기 위해 gcloud auth configure-docker 또는 docker-credential-gcr configure-docker를 사용한 경우 대상 호스트 이름이 Docker 구성 파일에 있는지 확인합니다.

2. 다음 명령어로 태그가 지정된 이미지를 내보냅니다.

   docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
   

   이 명령어는 latest 태그가 있는 이미지를 내보냅니다. 다른 태그가 있는 이미지를 내보내려면 다음 명령어를 사용합니다.

   docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

이미지를 내보내면 지정된 저장소에 저장됩니다.

이미지를 내보낸 후에 다음 작업을 할 수 있습니다.

• Google Cloud 콘솔로 이동하여 이미지를 확인합니다.

• gcloud 명령어를 실행하여 이미지 태그와 자동 생성된 다이제스트를 봅니다.

  gcloud artifacts docker images list \
  LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE [--include-tags]
  

  다음 출력 예시는 잘린 이미지 다이제스트를 보여주지만 이 명령어는 항상 전체 이미지 다이제스트를 반환합니다.

   IMAGE                                                 DIGEST         CREATE_TIME          UPDATE_TIME
    us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
    us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
    us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:46  2019-04-10T15:08:46
  

Docker로 이미지 가져오기

저장소 모드: 표준, 원격, 가상

1. 저장소에 인증되어 있는지 확인합니다.

   Docker 클라이언트를 구성하기 위해 gcloud auth configure-docker 또는 docker-credential-gcr configure-docker를 사용한 경우 대상 호스트 이름이 Docker 구성 파일에 있는지 확인합니다.

2. 저장소에서 가져오려면 다음 명령어를 사용합니다.

   docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   또는

   docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST
   

   다음 값을 바꿉니다.

   • LOCATION은 이미지가 저장된 저장소의 리전 또는 멀티 리전 위치입니다.
   • PROJECT는 Google Cloud 콘솔 프로젝트 ID입니다. 프로젝트 ID에 콜론(`:`)이 포함되어 있으면 도메인 범위 프로젝트를 참조하세요.
   • REPOSITORY는 이미지가 저장된 저장소의 이름입니다.
   • IMAGE는 저장소의 이미지 이름입니다.
   • TAG는 가져올 이미지 버전의 태그입니다.
   • IMAGE-DIGEST는 이미지 콘텐츠의 sha256 해시 값입니다. 각 이미지 버전에는 고유한 이미지 다이제스트가 포함됩니다. Google Cloud 콘솔에서 특정 이미지를 클릭하면 이미지의 메타데이터를 볼 수 있습니다. 다이제스트는 이미지 다이제스트로 나열됩니다.

   예를 들어 다음과 같은 특성을 지닌 이미지라고 가정해 보겠습니다.

   • 저장소 위치: us-west1
   • 저장소 이름: my-repo
   • 프로젝트 ID: my-project
   • 이미지 이름: test-image
   • 태그: staging

   이미지를 가져오기 위한 명령어는 다음과 같습니다.

   docker pull us-west1-docker.pkg.dev/my-project/my-repo/test-image:staging
   

Docker가 지정된 이미지를 다운로드합니다.

원격 저장소에서 이미지를 요청하면 원격 저장소는 캐시된 사본이 없으면 업스트림 소스에서 이미지를 다운로드하고 캐시합니다.

가상 저장소에서 이미지를 요청하면 Artifact Registry는 요청된 이미지의 업스트림 저장소를 검색합니다. 업스트림 저장소 2개 이상에서 사용할 수 있는 버전을 요청하면 Artifact Registry에서 가상 저장소에 구성된 우선순위 설정에 따라 사용할 업스트림 저장소를 선택합니다.

예를 들어 업스트림 저장소에 대해 다음 우선순위 설정을 사용하는 가상 저장소가 있다고 가정해보세요.

• main-repo: 우선순위가 100으로 설정됩니다.
• secondary-repo1: 우선순위가 80으로 설정됩니다.
• secondary-repo2: 우선순위가 80으로 설정됩니다.
• test-repo: 우선순위가 20으로 설정됩니다.

main-repo의 우선순위 값이 가장 높으므로 가상 저장소가 항상 이를 먼저 검색합니다.

secondary-repo1 및 secondary-repo2는 우선순위가 모두 80으로 설정됩니다. 요청된 이미지가 main-repo에 없으면 Artifact Registry가 그 다음으로 이 저장소를 검색합니다. 두 항목 모두 우선순위 값이 동일하므로, 두 항목 모두 버전을 사용할 수 있으면 Artifact Registry가 어느 저장소에서든 이미지를 제공하도록 선택할 수 있습니다.

test-repo는 우선순위 값이 가장 낮고 다른 업스트림 저장소에 없을 때만 저장된 아티팩트를 제공합니다.

crictl로 이미지 가져오기

crictl은 CRI 런타임 개발자가 Kubernetes 구성요소를 설정할 필요 없이 런타임을 디버깅할 수 있는 유용한 명령줄 도구입니다. Google Kubernetes Engine 노드에 containerd 런타임이 사용되는 경우 crictl을 사용하여 Artifact Registry에서 이미지를 가져올 수 있습니다.

crictl은 기본적으로 문제 해결 도구이므로, 이미지 내보내기 또는 태그 지정과 같은 일부 docker 명령어를 사용할 수 없습니다.

Artifact Registry에서 이미지를 가져오려면 다음 안내를 따르세요.

1. Google Cloud 콘솔에서 VM 인스턴스 페이지로 이동합니다.

   VM 인스턴스로 이동

2. 문제를 해결할 노드에 SSH로 연결합니다.

3. 저장소에 인증하기 위한 액세스 토큰을 가져옵니다.

   curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" -H "Metadata-Flavor: Google"

4. crictl pull --creds 및 access_token 값을 사용하여 이미지를 가져옵니다.

   crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

   또는

   crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST

   출력은 다음과 같이 표시됩니다.

   Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

다음 단계

• 태그 관리 및 이미지 삭제 알아보기
• Compute Engine에서 컨테이너를 실행하려는 경우 Compute Engine의 컨테이너에 대해 알아보기
• crictl을 사용하여 Kubernetes 노드 디버깅
• crictl을 사용하여 비공개 Artifact Registry 저장소에서 이미지를 가져오는 방법 알아보기
• crictl 이미지 레지스트리 구성 알아보기