이미지 관리

이 페이지에서는 Docker 저장소에서 컨테이너 이미지를 관리하는 방법을 설명합니다. 저장소에 이미지 나열, 태그 추가, 태그 삭제, 새 저장소에 이미지 복사, 이미지 삭제 등이 대표적인 이미지 관리 작업입니다.

이미지 가져오기 및 내보내기에 대한 자세한 내용은 이미지 가져오기 및 내보내기를 참조하세요.

참고: Container Registry에서 이미지를 관리하려면 Google Cloud 콘솔 또는 gcloud container images 명령어에서 Container Registry 이미지 목록을 사용합니다.

시작하기 전에

1. 대상 저장소가 없으면 새 저장소를 만듭니다.
2. 저장소에 대해 필요한 권한이 있는지 확인합니다.
3. (선택사항) gcloud 명령어의 기본값을 구성합니다.

필요한 역할

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

• 이미지, 이미지의 파일, 태그 보기: Artifact Registry 리더(roles/artifactregistry.reader)
• Artifact Registry를 사용하여 이미지에 태그 지정 또는 태그 수정: Artifact Registry 작성자(roles/artifactregistry.writer)
• 이미지 삭제 또는 태그 삭제: Artifact Registry 저장소 관리자(roles/artifactregistry.repoAdmin)

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

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

이미지 나열

저장소 모드: 표준, 원격

Google Cloud 콘솔 또는 gcloud CLI를 사용하여 이미지를 나열할 수 있습니다.

저장소 목록에는 Artifact Registry 및 Container Registry 저장소 모두가 포함됩니다. Container Registry 저장소의 이미지를 사용하려면 이미지 관리에 대한 Container Registry 문서를 참조하세요.

콘솔

저장소의 이미지를 보려면 다음 안내를 따르세요.

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

   저장소 페이지 열기

2. 컨테이너 이미지가 있는 저장소를 클릭합니다.

3. 이미지를 클릭하여 버전을 확인합니다.

gcloud

기본값이 구성된 경우 기본 프로젝트, 저장소, 위치의 모든 이미지를 나열하려면 다음 명령어를 실행합니다.

gcloud artifacts docker images list

특정 위치에 있는 저장소의 모든 이미지를 나열하려면 다음 명령어를 실행합니다.

gcloud artifacts docker images list LOCATION-docker.pkg.dev/PROJECT/REPOSITORY

특정 이미지의 모든 다이제스트 및 태그를 나열하려면 다음 명령어를 실행합니다.

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

다음 값을 바꿉니다.

• LOCATION은 저장소의 리전 또는 멀티 리전 위치입니다.
• PROJECT는 Google Cloud 프로젝트 ID입니다. 프로젝트 ID에 콜론(`:`)이 포함되어 있으면 도메인 범위 프로젝트를 참조하세요.
• REPOSITORY는 이미지가 저장된 저장소의 이름입니다.
• IMAGE는 저장소의 이미지 이름입니다.
• --include-tags는 다이제스트와 태그를 포함하여 모든 버전의 이미지를 표시합니다. 이 플래그를 생략하면 반환되는 목록에 최상위 컨테이너 이미지만 포함됩니다.

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

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

전체 저장소 이름은 다음과 같습니다.

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

전체 이미지 이름은 다음과 같습니다.

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

이미지 이름 형식에 대한 자세한 내용은 저장소 및 이미지 이름을 참조하세요.

파일 나열

저장소 모드: 표준, 원격

저장소의 파일, 지정된 컨테이너 이미지의 모든 버전에 있는 파일, 이미지의 특정 버전에 있는 파일을 나열할 수 있습니다.

다음 모든 명령어에 대해 --limit 플래그를 명령어에 추가하여 반환할 최대 파일 수를 설정할 수 있습니다.

기본값이 구성된 경우 기본 프로젝트, 저장소, 위치의 모든 파일을 나열하려면 다음 명령어를 실행합니다.

gcloud artifacts files list

지정된 프로젝트, 저장소, 위치의 파일을 나열하려면 다음 명령어를 실행합니다.

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

특정 컨테이너 이미지의 모든 버전에 대한 파일을 나열하려면 다음 명령어를 실행합니다.

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE

특정 컨테이너 이미지 버전의 파일을 나열하려면 다음 명령어를 실행합니다.

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --version=VERSION

특정 태그의 파일을 나열하려면 다음을 실행합니다.

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --tag=TAG

다음 값을 바꿉니다.

• LOCATION은 저장소의 리전 또는 멀티 리전 위치입니다.
• PROJECT: Google Cloud 프로젝트 ID 프로젝트 ID에 콜론(`:`)이 포함되어 있으면 도메인 범위 프로젝트를 참조하세요.
• REPOSITORY: 이미지가 저장된 저장소의 이름입니다.
• PACKAGE: 이미지의 이름입니다.
• VERSION: sha256:으로 시작하는 문자열인 이미지 다이제스트입니다.
• TAG: 컨테이너 이미지와 연결된 태그입니다.

예시

다음 이미지 정보를 살펴보세요.

• 프로젝트: my-project
• 저장소: my-repo
• 저장소 위치: us-west1
• 이미지: my-app

다음 명령어는 기본 프로젝트 내의 us-west1 위치에 있는 my-repo 저장소의 모든 파일을 나열합니다.

gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo

다음 명령어는 다이제스트 sha256:88b205d7995332e10e836514fbfd59ecaf8976fc15060cd66e85cdcebe7fb356이 있는 이미지 버전의 파일을 나열합니다.

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --version=sha256:88b205d7995332e10e836514fbfd59ecaf8976fc15060cd66e85cdcebe7fb356

다음 명령어는 1.0-dev 태그가 있는 이미지 버전의 파일을 나열합니다.

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --tag=1.0-dev

이미지에 태그 지정

Artifact Registry 저장소의 기존 이미지에 태그를 지정하거나 이미지를 저장소로 내보내기 전에 태그를 지정할 수 있습니다.

저장소의 이미지 태그 지정

저장소 모드: 표준

Google Cloud 콘솔 또는 명령줄을 사용하여 Artifact Registry 저장소의 이미지에 태그를 추가할 수 있습니다. 저장소에서 태그는 이미지 버전별로 고유합니다. 따라서 한 이미지의 버전이 여러 개라면, 각 태그는 하나의 버전에만 적용됩니다. 이미지에 이미 사용 중인 태그를 지정하면, 태그는 원래 버전에서 새로 태그가 지정된 버전으로 이동합니다.

콘솔

저장소의 이미지를 태그하려면 다음 안내를 따르세요.

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

   저장소 페이지 열기

2. 이미지를 클릭하여 이미지의 버전을 확인합니다.

3. 태그할 이미지 버전을 선택합니다.

4. 선택한 버전 행에서 작업 더보기()를 클릭한 후 태그 수정을 클릭합니다.

5. 입력란에 새 태그를 입력하고 저장을 클릭합니다.

gcloud

저장소의 이미지를 태그하려면 이미지 다이제스트 또는 태그를 사용하여 이미지 버전을 지정한 후 추가할 태그를 지정합니다. 다음 명령어 중 하나를 실행합니다.

gcloud artifacts docker tags add IMAGE-VERSION TAG

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

• IMAGE-VERSION은 이미지 다이제스트 또는 이미지 버전의 기존 태그를 사용하여 태그를 지정할 이미지 버전의 전체 이름입니다.
• TAG는 추가할 태그의 전체 이름입니다.

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

• 저장소 위치: us-west1
• 저장소 이름: my-repo
• 프로젝트 ID: my-project
• 이미지 이름: my-image
• 기존 태그: iteration6-final
• 추가할 태그: release-candidate

release-candidate 태그를 iteration6-final 태그가 있는 이미지 버전에 추가하려면 다음을 실행합니다.

gcloud artifacts docker tags add \
us-west1-docker.pkg.dev/my-project/my-repo/my-image:iteration6-final \
us-west1-docker.pkg.dev/my-project/my-repo/my-image:release-candidate

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

로컬 이미지에 태그 지정

로컬 이미지를 Artifact Registry로 내보내려면 먼저 레지스트리 이름으로 태그를 지정한 다음 이미지를 내보내야 합니다. 자세한 내용은 내보내기 및 가져오기를 참조하세요.

이미지 태그 해제

저장소 모드: 표준

Google Cloud 콘솔 또는 명령줄을 사용하여 Artifact Registry의 이미지에서 태그를 삭제할 수 있습니다.

콘솔

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

   저장소 페이지 열기

2. 이미지를 클릭하여 이미지의 버전을 확인합니다.

3. 태그를 삭제할 이미지 버전을 선택합니다.

4. 선택한 버전 행에서 작업 더보기()를 클릭한 후 태그 수정을 클릭합니다.

5. 태그를 삭제하고 저장을 클릭합니다.

gcloud

태그를 삭제하고 이미지에서 삭제하려면 다음 명령어를 실행합니다.

 gcloud artifacts docker tags delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG

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

• LOCATION은 저장소의 리전 또는 멀티 리전 위치입니다.
• PROJECT는 Google Cloud 프로젝트 ID입니다. 프로젝트 ID에 콜론(`:`)이 포함되어 있으면 도메인 범위 프로젝트를 참조하세요.
• REPOSITORY는 이미지가 저장된 저장소의 이름입니다.
• IMAGE는 저장소의 이미지 이름입니다.
• TAG은 삭제할 버전의 태그입니다.

이미지 삭제

저장소 모드: 표준, 원격

전체 컨테이너 이미지를 삭제하거나 태그 또는 다이제스트와 연결된 특정 이미지 버전을 삭제할 수 있습니다.

• 이미지를 삭제한 후에는 작업을 실행취소할 수 없습니다.
• 이미지를 삭제해도 참조 레이어가 즉시 삭제되지 않습니다. 참조되지 않은 레이어는 매일 삭제됩니다.
• 원격 저장소의 경우 이미지의 캐시된 버전이 삭제됩니다. 이미지는 업스트림 소스에서 계속 제공됩니다. 원격 저장소가 동일한 이미지에 대한 새 요청을 받으면 저장소에서 다시 다운로드하고 캐시합니다.

사용하지 않는 이미지를 관리하는 데 도움이 되는 다른 도구도 있습니다. 예를 들어 gcr-cleaner 도구는 다양한 기준에 따라 이전 이미지를 찾고 삭제합니다. 사용하지 않는 이미지를 삭제하면 스토리지 비용을 줄이는 데 도움이 됩니다. gcr-cleaner 도구는 공식 Google 제품이 아닙니다.

Google Cloud 콘솔 또는 gcloud CLI에서 이미지를 삭제하려면 다음 안내를 따르세요.

콘솔

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

   저장소 페이지 열기

2. 이미지 이름을 클릭하여 이미지의 버전을 확인합니다.

3. 삭제할 버전을 선택합니다.

4. 삭제를 클릭합니다.

5. 확인 대화상자에서 삭제를 클릭합니다.

gcloud

이미지와 이미지의 모든 태그를 삭제하려면 다음 명령어를 실행합니다.

gcloud artifacts docker images delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE --delete-tags

특정 이미지 버전을 삭제하려면 다음 명령어 중 하나를 사용합니다.

gcloud artifacts docker images delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG [--delete-tags]

또는

gcloud artifacts docker images delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE@IMAGE-DIGEST [--delete-tags]

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

• LOCATION은 저장소의 리전 또는 멀티 리전 위치입니다.
• PROJECT는 Google Cloud 프로젝트 ID입니다. 프로젝트 ID에 콜론(`:`)이 포함되어 있으면 도메인 범위 프로젝트를 참조하세요.
• REPOSITORY는 이미지가 저장된 저장소의 이름입니다.
• IMAGE는 저장소의 이미지 이름입니다.
• TAG은 삭제할 버전의 태그입니다. 여러 태그가 동일한 이미지 버전과 연결되어 있는 경우 먼저 태그를 삭제하지 않고 이미지 버전을 삭제하기 위해 --delete-tags를 포함해야 합니다.
• IMAGE-DIGEST은 삭제할 버전의 sha256 해시 값입니다. 태그가 이미지 다이제스트와 연결된 경우 먼저 태그를 삭제하지 않고 이미지 버전을 삭제하기 위해 --delete-tags를 포함해야 합니다.
• --delete-tags은 이미지 버전에 적용된 모든 태그를 삭제합니다. 이 플래그를 사용하면 다음과 같은 경우에 이미지 버전을 강제로 삭제할 수 있습니다.
  • 태그를 지정했지만 이미지 버전과 연결된 다른 태그가 있습니다.
  • 태그가 하나 이상 있는 이미지 다이제스트를 지정했습니다.

다음 단계

• Docker 명령어를 사용하지 않고 이미지 내에 저장된 개별 파일을 다운로드합니다. 이 방법은 매니페스트 파일을 빠르게 검사하는 데 유용할 수 있습니다.