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

이미지 내보내기(업로드) 및 가져오기(다운로드)는 가장 일반적인 두 가지 Container Registry 태스크입니다. 이 문서에서는 Docker를 사용하여 이미지를 내보내고 가져오는 방법을 주로 설명합니다.

Cloud Build를 사용하는 경우 컨테이너를 Container Registry에 빌드하고 푸시하는 방법은 Cloud Build 문서를 참조하세요.

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

시작하기 전에

다음 사항을 확인하세요.

  1. 프로젝트에서 Container Registry를 사용 설정했는지 여부

  2. Docker를 설치하고 구성했는지 여부

레지스트리 추가

다음 Container Registry 레지스트리를 프로젝트에 추가할 수 있습니다.

호스트 이름 스토리지 위치
gcr.io 미국 내 데이터 센터에 이미지 저장
asia.gcr.io 아시아의 데이터 센터에 이미지 저장
eu.gcr.io 유럽 연합 회원국 내 데이터 센터에 이미지 저장
us.gcr.io 미국 내 데이터 센터에 이미지 저장

첫 번째 이미지를 호스트 이름으로 내보내면 프로젝트와 해당 Cloud Storage 스토리지 버킷에서 레지스트리가 생성됩니다. 이 초기 내보내기에는 스토리지 버킷을 만들 수 있는 프로젝트 전체 권한이 필요합니다.

프로젝트에 레지스트리 호스트가 있으면 스토리지 버킷에 대한 권한을 구성하여 레지스트리의 이미지에 대한 액세스를 제어할 수 있습니다.

레지스트리를 추가하고 권한을 구성하려면 다음 안내를 따르세요.

  1. 필수 권한이 있는지 확인합니다. 스토리지 관리자 역할(roles/storage.admin)이나 같은 권한이 있는 커스텀 역할 또는 사전 정의된 역할이 있어야 합니다.

    프로젝트 수준에서 스토리지 관리자 역할을 부여하는 방법은 IAM 문서를 참조하세요.

  2. 초기 이미지를 호스트로 내보냅니다. 예를 들어 다음 명령어를 실행합니다.

    • Docker Hub에서 busybox 이미지 가져오기
    • gcr.io 레지스트리 호스트와 프로젝트 ID my-project를 포함하여 Container Registry의 대상 경로로 이미지에 태그 지정
    • 레지스트리로 이미지 푸시
    docker pull busybox
docker tag busybox gcr.io/my-project/busybox
docker push gcr.io/my-project/busybox

Container Registry는 프로젝트에 레지스트리를 추가하고 레지스트리의 스토리지 버킷을 만들며 이미지를 저장합니다.

이제 레지스트리 스토리지 버킷에서 액세스 제어를 구성하여 다른 사용자에게 레지스트리 액세스 권한을 부여할 수 있습니다.

이미지를 레지스트리로 내보내기

Docker 또는 다른 타사 도구를 사용하여 로컬 이미지를 Container Registry로 내보내려면 먼저 레지스트리 이름으로 이미지에 태그를 지정한 후 이미지를 내보내야 합니다.

대용량 이미지 업로드에는 다음과 같은 요인이 영향을 미칠 수 있습니다.

업로드 시간
Container Registry로 전송되는 모든 요청에는 2시간 제한 시간 한도가 있습니다. 액세스 토큰을 사용하여 Container Registry에 인증하면 토큰은 60분 후에 만료됩니다. 업로드 시간이 60분을 초과할 것으로 예상되면 다른 인증 방법을 사용합니다.
이미지 크기
Container Registry는 각 레지스트리의 기본 스토리지에 Cloud Storage를 사용합니다. Cloud Storage 할당량 및 한도는 스토리지의 객체 최대 크기 5TB를 포함하여 각 레지스트리에 적용됩니다.
Container Registry에서는 Docker 청크 업로드를 지원하지 않습니다. 일부 도구에서는 청크 업로드나 단일 모놀리식 업로드로 대용량 이미지를 업로드할 수 있습니다. 이미지를 Container Registry로 내보내려면 모놀리식 업로드를 사용해야 합니다.

필수 권한

이미지를 내보내려면 다음 Cloud Storage 역할 중 하나나 같은 권한이 있는 역할이 필요합니다.

프로젝트의 레지스트리로 첫 번째 이미지 내보내기

역할: Google Cloud 프로젝트 수준에서 스토리지 관리자(roles/storage.admin) 사전 정의된 소유자 역할에는 이러한 권한이 포함됩니다.

프로젝트의 레지스트리 호스트(예: gcr.io)로 이미지를 처음 내보내면 Container Registry에서 레지스트리의 스토리지 버킷을 만듭니다. 스토리지 관리자 역할에는 스토리지 버킷을 만드는 데 필요한 권한이 있습니다.

프로젝트의 기존 레지스트리에 이미지 내보내기

역할: 레지스트리 스토리지 버킷에 대한 스토리지 기존 버킷 작성자(roles/storage.legacyBucketWriter)

이 역할에는 프로젝트의 기존 레지스트리 호스트의 이미지를 내보내고 가져올 수 있는 권한이 있습니다. 예를 들어 프로젝트에 gcr.io 레지스트리만 있는 경우 스토리지 기존 버킷 작성자 역할이 있는 사용자는 이미지를 gcr.io로 내보낼 수 있지만 asia.gcr.io로 내보낼 수는 없습니다.

레지스트리에 권한을 부여하는 방법은 액세스 제어 구성을 참조하세요.

레지스트리 이름으로 로컬 이미지에 태그 지정하기

이미지에 태그를 지정하려면 다음 안내를 따르세요.

  1. Container Registry에 대한 인증이 구성되었는지 확인합니다.

  2. Container Registry의 이미지 이름을 결정합니다.

    1. 이미지를 저장할 위치를 지정하는 호스트 이름을 선택합니다.

      • gcr.io는 이미지를 미국의 데이터 센터에서 호스팅하지만 나중에 위치가 변경될 수 있습니다.
      • us.gcr.io는 이미지를 미국의 데이터 센터에서, gcr.io에서 호스팅하는 이미지와 별도의 스토리지 버킷에 호스팅합니다.
      • eu.gcr.io는 유럽 연합 내 이미지를 호스팅합니다.
      • asia.gcr.io는 이미지를 아시아의 데이터 센터에서 호스팅합니다.

      이 위치는 Cloud Storage 스토리지 버킷의 멀티 리전에 해당합니다. 이미지를 새로운 호스트 이름으로 레지스트리에 내보내면 Container Registry는 지정된 멀티 리전에 스토리지 버킷을 만듭니다. 이 버킷은 레지스트리의 기본 스토리지입니다. 프로젝트 내에서 호스트 이름이 동일한 모든 레지스트리는 하나의 스토리지 버킷을 공유합니다.

      콘솔에서 이미지의 호스트 이름은 위치에 나열됩니다.

    2. 대상 이미지 이름을 선택합니다. 로컬 머신의 이미지 이름과 다를 수도 있습니다. 예를 들어 로컬 이미지 이름은 web-image이지만 Container Registry에 web-site 형식으로 저장하려 합니다.

    3. 호스트 이름, Google Cloud 콘솔 프로젝트 ID, 대상 이미지 이름을 결합합니다.

      HOSTNAME/PROJECT-ID/TARGET-IMAGE

      다음 예시를 참조하세요.

      • 호스트 이름: gcr.io
      • Google Cloud 프로젝트: my-project
      • 대상 이미지 이름: web-site

      호스트 이름, 프로젝트, 대상 이미지 이름을 결합하여 태그에 사용할 전체 이미지 경로를 얻을 수 있습니다.

      gcr.io/my-project/web-site

      프로젝트 ID에 콜론(:)이 포함되어 있으면 도메인 범위 프로젝트를 참조하세요.

  3. 이전 단계의 이름으로 로컬 이미지를 태그합니다. 태그로 이 버전의 이미지에 라벨을 지정하려면 태그 이름을 포함하세요.

    docker tag SOURCE_IMAGE HOSTNAME/PROJECT-ID/TARGET-IMAGE:TAG

    다음을 바꿉니다.

    • 여기서 SOURCE_IMAGE는 로컬 이미지 이름 또는 이미지 ID입니다.
    • HOSTNAME은 2단계에서 선택한 레지스트리 호스트입니다.
    • PROJECT는 Google Cloud 프로젝트 ID입니다.
    • TARGET-IMAGE는 Container Registry에 저장될 때의 이미지 이름입니다.
    • TAG는 이 이미지 버전과 연결할 태그입니다.

    예를 들어 이 명령어는 로컬 이미지 web-image를 Container Registry에서 v1.5 태그를 사용해 gcr.io/my-project/web-site로 태그합니다.

    docker tag web-image gcr.io/my-project/web-site:v1.5

    태그를 지정하지 않으면 Docker가 기본 latest 태그를 추가합니다. latest는 기본 태그이므로 latest 태그로 가장 최근에 태그된 이미지 버전을 나타내며 이미지의 최신 버전은 아닐 수도 있습니다.

Docker는 명령어에 지정한 이미지 이름과 태그로 이미지를 태그합니다.

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

  1. Container Registry에 대한 인증이 구성되었는지 확인합니다.

  2. 태그된 이미지를 Container Registry로 내보냅니다.

    다음 명령어를 실행하여 특정 태그가 있는 이미지를 푸시합니다.

    docker push HOSTNAME/PROJECT-ID/IMAGE:TAG

    :TAG를 생략하면 Docker가 latest로 태그된 이미지 버전을 푸시합니다.

    예를 들어 이 명령어는 v1.5 태그가 있는 gcr.io/my-project/web-site 이미지를 푸시합니다.

    docker push gcr.io/my-project/web-site:v1.5

프로젝트에 아직 없는 레지스트리 호스트로 이미지를 푸시하면 Container Registry가 레지스트리 호스트의 스토리지 버킷을 만듭니다.

내보낸 이미지를 보려면 다음 안내를 따르세요.

  • Google Cloud 콘솔로 이동하여 레지스트리와 이미지를 봅니다.

  • gcloud container images list-tags를 실행하여 이미지 태그와 자동으로 생성된 다이제스트를 봅니다.

    gcloud container images list-tags HOSTNAME/PROJECT-ID/IMAGE

    명령어 결과는 다음과 비슷합니다.

    DIGEST        TAGS        TIMESTAMP
44bde...      test        2017-..-..

이미지를 레지스트리에서 가져오기

이미지를 가져오려면 레지스트리 스토리지 버킷에 대한 스토리지 객체 뷰어나 같은 권한이 있는 역할이 필요합니다.

Container Registry에서 이미지를 가져오려면 다음 명령어를 사용하세요.

docker pull HOSTNAME/PROJECT-ID/IMAGE:TAG

또는

docker pull HOSTNAME/PROJECT-ID/IMAGE@IMAGE_DIGEST

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

  • HOSTNAME은 콘솔의 위치에 나열됩니다. 4가지 옵션인 gcr.io, us.gcr.io, eu.gcr.io 또는 asia.gcr.io 중 하나입니다.
  • PROJECT-ID는 Google Cloud 콘솔 프로젝트 ID입니다. 프로젝트 ID에 콜론(:)이 포함되어 있으면 도메인 범위 프로젝트를 참조하세요.
  • IMAGE는 Container Registry에 있는 이미지의 이름입니다.
  • TAG는 이미지에 적용된 태그입니다. 레지스트리에서 태그는 이미지별로 고유합니다.
  • IMAGE_DIGEST는 이미지 콘텐츠의 sha256 해시 값입니다. Google Cloud 콘솔에서 특정 이미지를 클릭하면 이미지의 메타데이터를 볼 수 있습니다. 다이제스트는 이미지 다이제스트로 나열됩니다.

특정 이미지에 대한 가져오기 명령어를 얻는 방법:

  1. 이미지 이름을 클릭해 특정 레지스트리로 이동합니다.

  2. 레지스트리에서, 가져올 이미지의 버전 옆에 있는 체크박스를 선택합니다.

  3. 페이지 상단에서 가져오기 명령어 표시를 클릭합니다.

  4. 태그나 다이제스트를 이용해 이미지를 식별하는 가져오기 명령어를 복사합니다.

다음 단계