액세스 제어 구성

이 페이지에서는 Container Registry에 대한 액세스를 제어할 수 있는 권한을 설명합니다.

권한을 구성한 후 이미지를 내보내고 가져오는 데 사용하는 Docker 클라이언트에 대해 인증을 구성할 수 있습니다.

일반 액세스 요구사항

Container Registry와 상호작용하는 모든 사용자, 서비스 계정, 기타 ID는 Cloud Storage 저장소에 대한 적절한 ID 및 액세스 관리(IAM) 권한이 있어야 합니다.

Google Kubernetes Engine 클러스터의 VM을 포함하여 Compute Engine VM에서 사용되는 서비스 계정의 경우 IAM 권한과 액세스 범위를 기반으로 합니다.

Container Registry 서비스 계정의 권한

Container Registry 서비스 에이전트는 Google Cloud 서비스와 상호작용할 때 Container Registry를 대신하여 동작하는 Google 관리형 서비스 계정입니다.

최소 권한의 보안 원칙을 적용하도록 이 서비스 계정에 2020년 10월 5일 이후에 Container Registry API가 사용 설정된 프로젝트의 Container Registry 서비스 에이전트 역할이 부여됩니다. 이 역할에는 다음 권한이 있습니다.

  • 주제 게시: pubsub.topics.publish
  • 스토리지 객체 ACL 읽기: storage.objects.getIamPolicy
  • 스토리지 객체 데이터 및 메타데이터 읽기: storage.objects.get
  • 버킷의 스토리지 객체 나열 및 객체 메타데이터 읽기: storage.objects.list

이전에 Container Registry 서비스 계정에 편집자 역할이 부여되었습니다. 편집자 역할은 프로젝트에서 대부분의 리소스를 만들고 삭제할 수 있는 권한을 부여하므로 Container Registry 서비스 계정에 이 역할이 있으면 권한을 제한하는 것이 좋습니다.

Container Registry 서비스 계정의 현재 권한을 확인하려면 다음 명령어를 실행합니다.

gcloud projects get-iam-policy PROJECT-ID  \
--flatten="bindings[].members" \
--format='table(bindings.role)' \
--filter="bindings.members:service-PROJECT-NUMBER@containerregistry.iam.gserviceaccount.com"

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

  • PROJECT-ID는 Google Cloud 프로젝트 ID입니다.
  • PROJECT-NUMBER는 Google Cloud 프로젝트 번호입니다.

Google Cloud Console에서 또는 다음 명령어를 사용하여 프로젝트 ID와 프로젝트 번호를 가져올 수 있습니다.

PROJECT=$(gcloud config get-value project)
echo $PROJECT && gcloud projects list --filter="$PROJECT" --format="value(PROJECT_NUMBER)"

Container Registry 서비스 에이전트 역할을 부여하고 편집자 역할을 취소하려면 다음 안내를 따르세요.

  1. 다음 명령어를 사용하여 Container Registry 서비스 에이전트 역할을 부여합니다.

    gcloud projects add-iam-policy-binding PROJECT-ID \
    --member=serviceAccount:service-PROJECT-NUMBER@containerregistry.iam.gserviceaccount.com --role=roles/containerregistry.ServiceAgent
    
  2. 다음 명령어를 사용하여 편집자 역할을 취소합니다.

    gcloud projects remove-iam-policy-binding PROJECT-ID \
    --member=serviceAccount:service-PROJECT-NUMBER@containerregistry.iam.gserviceaccount.com --role=roles/editor
    

IAM 권한

IAM 권한은 리소스에 액세스할 수 있는 사용자를 결정합니다. Container Registry와 상호작용하는 모든 사용자, 서비스 계정, 기타 ID에는 적절한 Cloud Storage 권한이 있어야 합니다.

기본적으로 Google Cloud는 기본 서비스 계정을 사용하여 동일한 프로젝트 내의 리소스와 상호작용합니다. 예를 들어 Cloud Build 서비스 계정은 Container Registry가 동일한 프로젝트에 있을 때 이미지를 내보내고 가져올 수 있습니다.

다음과 같은 경우에는 직접 권한을 구성하거나 수정해야 합니다.

  • 한 프로젝트의 서비스 계정을 사용하여 다른 프로젝트의 Container Registry에 액세스하는 경우
  • 스토리지에 대한 읽기 전용 액세스 권한이 있는 기본 서비스 계정을 사용 중이지만 이미지를 가져오거나 내보내려는 경우
  • 커스텀 서비스 계정을 사용하여 Container Registry와 상호작용

VM 및 클러스터의 액세스 범위

GKE 클러스터의 VM을 포함하여 Compute Engine VM과 연결된 서비스 계정의 경우, 스토리지에 대한 액세스는 IAM 권한과 구성된 스토리지 액세스 범위를 기반으로 합니다.

Compute Engine 기본 서비스 계정은 VM과 동일한 프로젝트에서 이미지를 가져오도록 구성됩니다. 다른 프로젝트에서 이미지를 가져오거나 Container Registry와 상호작용하기 위해 VM 또는 GKE 클러스터가 필요한 경우 Google Cloud에서 Container Registry 사용을 참조하세요.

IAM 권한 구성

Container Registry는 Cloud Storage 버킷을 컨테이너 이미지의 기본 스토리지로 사용합니다. 사용자, 그룹, 서비스 계정 또는 기타 ID에 적절한 Cloud Storage 권한을 부여하여 이미지에 대한 액세스를 제어할 수 있습니다.

프로젝트 수준에서 부여된 Cloud Storage 권한은 Container Registry에서 사용하는 버킷뿐만 아니라 프로젝트의 모든 스토리지 버킷에 적용됩니다. Container Registry와 관련된 권한을 구성하려면 레지스트리에서 사용하는 스토리지 버킷에 대한 권한을 부여합니다. Container Registry는 스토리지 버킷 내의 개별 객체에 설정된 권한을 무시합니다.

프로젝트 수준 역할 Owner, Editor, Viewer를 사용하여 액세스 권한을 부여할 수도 있지만 Cloud Storage 역할을 사용하면 최소 권한의 보안 원칙을 적용하여 사용자와 서비스 계정은 필요한 권한만 가지고 있습니다.

Google Cloud와 상호작용하는 Google Cloud 제품 및 애플리케이션은 서비스 계정을 사용하여 Container Registry와 상호작용합니다. 서비스 계정 액세스에는 다음 고려사항이 적용됩니다.

  • 기본적으로 몇 가지 일반적인 통합에 대한 서비스 계정은 동일한 프로젝트 내의 Container Registry에 대한 액세스 권한으로 구성됩니다. 예를 들어 기본적으로 Cloud Build 서비스 계정은 동일한 프로젝트에서 이미지를 내보내고 가져올 수 있습니다.
  • 서비스 계정이 다른 프로젝트의 Container Registry에 액세스해야 하는 경우 Container Registry를 사용하여 프로젝트에 필요한 권한을 부여해야 합니다.
  • Google Kubernetes Engine 클러스터의 인스턴스를 포함한 VM 인스턴스에는 이미지를 내보내거나 가져오도록 구성된 올바른 스토리지 액세스 범위가 있어야 합니다. 기본적으로 VM은 Container Registry가 동일한 프로젝트에 있을 때 이미지를 가져올 수 있습니다.

권한 및 역할

아래 표에는 Container Registry 작업에 필요한 권한과 역할이 설명되어 있습니다.

Cloud Storage 역할 및 권한에 대한 자세한 내용은 Cloud Storage 문서를 참조하세요.

작업 권한 역할 역할 이름
내보내기(읽기 및 쓰기)

storage.buckets.create

storage.buckets.delete

storage.buckets.get

storage.buckets.list

storage.buckets.update

storage.objects.create

storage.objects.delete

storage.objects.get

storage.objects.list

storage.objects.update

roles/storage.admin 스토리지 관리자
가져오기(읽기 전용)

storage.objects.get

storage.objects.list

roles/storage.objectViewer 스토리지 객체 뷰어

IAM 권한 부여

Container Registry에서 사용하는 스토리지 버킷에 대한 권한을 부여합니다.

권한 부여

  1. Container Registry 호스트 위치(gcr.io, asia.gcr.io, eu.gcr.io, us.gcr.io)가 프로젝트에 없는 경우, 소유자, 편집자 또는 스토리지 관리자 권한이 있는 사용자가 이미지를 호스트에 푸시하여 스토리지 버킷을 만들어야 합니다.
  2. Container Registry가 있는 프로젝트에서 호스트 이름에 사용되는 Cloud Storage 버킷에 대한 적절한 권한을 부여합니다.

    이미지를 저장하는 버킷 이름 BUCKET-NAME은 다음과 같은 형식입니다.

    • artifacts.PROJECT-ID.appspot.com - 호스트 gcr.io의 레지스트리로 내보낸 이미지의 경우
    • STORAGE-REGION.artifacts.PROJECT-ID.appspot.com

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

    • PROJECT-ID는 Google Cloud Console 프로젝트 ID입니다.
    • STORAGE-REGION은 스토리지 버킷의 위치입니다.
      • us - us.gcr.io 호스트의 레지스트리
      • eu - eu.gcr.io 호스트의 레지스트리
      • asia - asia.gcr.io 호스트의 레지스트리

    Google Cloud Console 또는 gsutil 명령줄 도구를 사용하여 버킷에 권한을 부여할 수 있습니다.

    Console

    1. Cloud Console에서 Cloud Storage 페이지를 방문합니다.
    2. 버킷의 링크 artifacts.PROJECT-ID.appspot.com 또는 STORAGE-REGION.artifacts.PROJECT-ID.appspot.com을 클릭합니다.

      여기에서 PROJECT-ID는 Container Registry를 호스팅하는 프로젝트의 Google Cloud 프로젝트 ID이며 STORAGE-REGION은 이미지를 호스팅하는 레지스트리의 멀티 리전(asia, eu 또는 us)입니다.

    3. 권한 탭을 선택합니다.

    4. 멤버 추가를 클릭합니다.

    5. 표시되는 메뉴 중 멤버 입력란에 권한이 필요한 사용자의 이메일 주소를 쉼표로 구분해서 입력합니다. 이 이메일 주소는 다음 중 하나일 수 있습니다.

      • Google 계정(예: someone@example.com)
      • Google 그룹(예: my-developer-team@googlegroups.com)
      • IAM 서비스 계정
      • 다른 프로젝트의 Compute Engine 기본 서비스 계정. 이 계정은 Google Kubernetes Engine이 컨테이너 이미지 클러스터를 가져올 때 기본적으로 사용하는 계정입니다. PROJECT-NUMBER-compute@developer.gserviceaccount.com 형식입니다. 여기서 PROJECT-NUMBER는 Google Kubernetes Engine 클러스터를 실행 중인 프로젝트의 Google Cloud 프로젝트 번호입니다.
    6. 역할 선택 드롭다운 메뉴에서 스토리지 카테고리를 선택한 다음 적절한 권한을 선택합니다.

      • 스토리지 객체 뷰어: 이미지만 가져오기
      • 스토리지 관리자: 이미지 내보내기 및 가져오기
    7. 추가를 클릭합니다.

    gsutil

    1. 다음 명령어를 실행하여 프로젝트의 버킷을 나열합니다.

      gsutil ls
      

      응답은 다음 예와 같습니다.

      gs://[BUCKET_NAME1]/
      gs://[BUCKET_NAME2]/
      gs://[BUCKET_NAME3]/ ...
      
    2. 셸 또는 터미널 창에서 다음 명령어를 실행합니다.

      gsutil iam ch TYPE:EMAIL-ADDRESS:ROLE gs://BUCKET_NAME
      

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

      • TYPE은 다음 중 하나일 수 있습니다.
        • EMAIL-ADDRESS에 서비스 계정이 지정된 경우 serviceAccount
        • EMAIL-ADDRESS가 Google 계정인 경우 user
        • EMAIL-ADDRESS가 Google 그룹인 경우 group
      • EMAIL-ADDRESS은 다음 중 하나일 수 있습니다.
        • Google 계정(예: someone@example.com)
        • Google 그룹(예: my-developer-team@googlegroups.com)
        • IAM 서비스 계정
        • 다른 프로젝트의 Compute Engine 기본 서비스 계정. 이 계정은 Google Kubernetes Engine이 컨테이너 이미지 클러스터를 가져올 때 기본적으로 사용하는 계정입니다. PROJECT_NUMBER-compute@developer.gserviceaccount.com 형식입니다. 여기서 PROJECT_NUMBER는 Google Kubernetes Engine 클러스터를 실행 중인 프로젝트의 Google Cloud 프로젝트 번호입니다.
      • ROLE은 부여할 Cloud Storage 역할입니다.
        • objectViewer: 이미지 가져오기
        • objectAdmin: 이미지 내보내고 가져오기
      • BUCKET_NAME은 Cloud Storage 버킷의 이름이며 artifacts.PROJECT-ID.appspot.com 또는 STORAGE-REGION.artifacts.PROJECT-ID.appspot.com 양식입니다.

    gsutil iam ch 명령어는 레지스트리가 호스팅되는 스토리지 버킷의 IAM 권한을 변경합니다. 계정에 objectViewer 권한을 부여하면 해당 계정은 레지스트리에서 이미지를 가져올 수 있습니다.

    명령어에 대한 자세한 내용은 gsutil iam 문서를 참조하세요.

  3. Compute Engine과 Google Kubernetes Engine은 기본적으로 동일한 프로젝트의 Container Registry에서 이미지를 가져올 수 있는 권한으로 구성됩니다. 이러한 통합에 대한 다른 요구사항이 있는 경우 Google Cloud 서비스와 통합을 참조하세요.

이미지에 대한 공개 액세스 구성

호스트 위치의 기본 스토리지 버킷에 공개적으로 액세스할 수 있다면 Container Registry에도 공개적으로 액세스할 수 있습니다. 프로젝트 내에서 각 호스트 위치에 있는 모든 이미지는 공개일 수도 있고 비공개일 수도 있습니다. 프로젝트의 호스트에서 특정 이미지만 공개적으로 제공할 수는 없습니다. 특정 이미지만 공개하고 싶다면 다음 방법을 이용하세요.

  • 공개로 설정할 별도의 호스트 위치에 해당 이미지를 유지하거나
  • 공개적으로 액세스할 수 있는 이미지를 저장할 새 프로젝트를 만듭니다.

컨테이너 이미지를 공개적으로 제공하려면 다음 단계에 따라 기본 스토리지 버킷을 공개적으로 액세스할 수 있도록 설정합니다.

Console

  1. 기본 스토리지 버킷이 존재하도록 이미지를 Container Registry에 내보냈는지 확인합니다.

  2. Cloud Console에서 Container Registry 페이지를 엽니다.

    Container Registry 페이지 열기

  3. 왼쪽 패널에서 설정을 클릭합니다.

  4. 공개 액세스설정 페이지에서 공개 상태를 공개 또는 비공개로 전환합니다. 이 설정은 기본 스토리지 버킷에 대한 액세스를 제어합니다.

    호스트 공개 상태가 공개이면 해당 호스트 위치에 있는 Google Cloud 프로젝트의 모든 이미지에 공개적으로 액세스할 수 있습니다.

gsutil

  1. 기본 스토리지 버킷이 존재하도록 이미지를 Container Registry에 내보냈는지 확인합니다.

  2. 해당 레지스트리에 대한 Cloud Storage 버킷의 이름을 찾습니다. 이렇게 하려면 버킷을 나열해야 합니다.

    gsutil ls
    

    Container Registry 버킷 URL은 gs://artifacts.PROJECT-ID.appspot.com 또는 gs://STORAGE-REGION.artifacts.PROJECT-ID.appspot.com으로 표시됩니다. 각 항목의 의미는 다음과 같습니다.

    • PROJECT-ID는 Google Cloud Console 프로젝트 ID입니다. 도메인 범위 프로젝트의 경우 도메인 이름이 프로젝트 ID의 일부가 됩니다.
    • STORAGE-REGION은 스토리지 버킷의 위치입니다.
      • us - us.gcr.io 호스트의 레지스트리
      • eu - eu.gcr.io 호스트의 레지스트리
      • asia - asia.gcr.io 호스트의 레지스트리
  3. 다음 명령어를 실행하여 Container Registry의 스토리지 버킷에 공개적으로 액세스할 수 있게 합니다. 이 명령어는 버킷의 모든 이미지를 공개적으로 액세스할 수 있게 합니다.

    gsutil iam ch allUsers:objectViewer gs://BUCKET-NAME
    

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

    • gs://BUCKET-NAME은 Container Registry의 버킷 URL입니다.

Container Registry가 공개적으로 액세스 가능한 경우, 모든 사용자가 이미지를 가져올 수 있습니다. 자세한 안내는 레지스트리에서 이미지 가져오기를 참조하세요.

권한 취소

IAM 권한을 취소하려면 다음 단계를 따르세요.

Console

  1. Cloud Console에서 Cloud Storage 페이지를 방문합니다.
  2. 버킷의 링크 artifacts.PROJECT-ID.appspot.com 또는 STORAGE-REGION.artifacts.PROJECT-ID.appspot.com을 클릭합니다. 여기에서 PROJECT-ID는 Container Registry를 호스팅하는 프로젝트의 Google Cloud 프로젝트 ID이며 STORAGE-REGION은 이미지를 호스팅하는 레지스트리의 멀티 리전(asia, eu 또는 us)입니다.

  3. 권한 탭을 선택합니다.

  4. 삭제할 멤버 옆에 있는 휴지통 아이콘을 클릭합니다.

gsutil

셸 또는 터미널 창에서 다음 명령어를 실행합니다.

gsutil iam ch -d MEMBER gs://BUCKET-NAME

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

  • MEMBER는 다음 중 하나일 수 있습니다.
    • Google 계정의 경우 user:EMAIL-ADDRESS
    • IAM 서비스 계정의 경우 serviceAccount:EMAIL-ADDRESS
    • Google 그룹의 경우 group:EMAIL-ADDRESS
    • 공개 액세스를 취소하는 경우 allUsers
  • BUCKET-NAME은 원하는 버킷의 이름입니다.

Google 클라우드 서비스와 통합

기본적으로 일부 일반적인 통합을 위한 서비스 계정은 동일한 프로젝트 내에서 가져오기 또는 가져오기 및 내보내기 액세스 중 하나로 구성됩니다. 액세스는 IAM 권한을 기반으로 하며 서비스 계정이 다른 프로젝트의 Container Registry에 연결하는 경우에만 권한을 구성해야 합니다.

GKE 클러스터의 VM을 포함하여 Compute Engine VM 인스턴스와 연결된 서비스 계정에는 추가 요구사항이 있습니다. 스토리지에 대한 VM 액세스는 부여 된 IAM 권한 및 스토리지 액세스 범위를 기반으로 합니다.

  • IAM 권한은 리소스에 액세스할 수 있는 사용자를 결정합니다.
  • 액세스 범위는 VM 인스턴스에서 gcloud 도구 및 클라이언트 라이브러리를 통해 수행된 요청의 기본 OAuth 범위를 결정합니다. 따라서 액세스 범위는 애플리케이션 기본 사용자 인증 정보로 인증할 때 API 메서드에 대한 액세스를 추가로 제한할 수 있습니다.
    • 비공개 이미지를 가져오려면 VM 서비스 계정에 이미지의 스토리지 버킷에 대한 read 권한이 있어야 합니다.
    • 비공개 이미지를 내보내려면 VM 서비스 계정에 이미지의 스토리지 버킷에 대한 read-write, cloud-platform 또는 full-control 권한이 있어야 합니다.

기본적으로 기본 Compute Engine 기본 서비스 계정에는 동일한 프로젝트 및 read-only 스토리지 액세스 범위의 리소스에 대한 편집자 권한이 있습니다. read-only 범위는 VM을 이미지 가져오기로만 제한합니다. 기본 서비스 계정에는 서픽스 @developer.gserviceaccount.com가 있습니다.

다음 설정에서는 기본 권한 또는 범위 구성을 변경해야 합니다.

VM 또는 클러스터에서 이미지 내보내기
이미지를 내보내려면 VM 인스턴스 서비스 계정에 storage-ro 대신 storage-rw 범위가 있어야 합니다.
VM 및 Container Registry가 별도의 프로젝트에 있음
Container Registry에서 사용하는 스토리지 버킷에 액세스 할 수 있는 권한을 IAM이 있는 서비스 계정에 부여해야 합니다.
VM에서 gcloud 명령어 실행
서비스 계정에 cloud-platform 범위가 있어야 합니다. 이 범위는 이미지를 내보내고 가져오고 gcloud 명령어를 실행할 권한을 부여합니다.

권한과 범위를 구성하는 단계는 다음 섹션에 나와 있습니다.

VM의 IAM 권한 구성

기본적으로 Compute Engine VM은 동일한 프로젝트의 스토리지에만 액세스할 수 있습니다. VM이 다른 프로젝트의 Container Registry에 액세스해야 하는 경우 VM 서비스 계정에 권한을 부여해야 합니다.

  1. VM 인스턴스가 있는 프로젝트에서 Compute Engine 기본 서비스 계정의 이름 또는 VM 인스턴스와 연결된 서비스 계정을 가져옵니다. 기본 서비스 계정에는 서픽스 @developer.gserviceaccount.com가 있습니다.

  2. Container Registry가 있는 프로젝트에서 서비스 계정이 Container Registry에 액세스할 수 있도록 권한 부여합니다.

VM의 범위 구성

VM을 만들 때 액세스 범위를 설정하려면 -scopes 옵션을 사용합니다.

gcloud compute instances create INSTANCE --scopes=SCOPE

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

  • INSTANCE는 VM 인스턴스 이름입니다.
  • SCOPE는 VM 서비스 계정에 구성하려는 범위입니다.
    • 이미지 가져오기: storage-ro
    • 이미지 가져오기 및 내보내기: storage-rw
    • 이미지 가져오기 및 내보내기, gcloud 명령어 실행: cloud-platform

기존 VM 인스턴스의 범위를 변경하려면 다음 안내를 따르세요.

--scopes 옵션으로 액세스 범위를 설정합니다.

  1. VM 인스턴스를 중지합니다. 인스턴스 중지를 참조하세요.

  2. 다음 명령어를 사용하여 액세스 범위를 변경합니다.

    gcloud compute instances set-service-account INSTANCE --scopes=SCOPE
    

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

    • INSTANCE는 VM 인스턴스 이름입니다.
    • SCOPE는 VM 서비스 계정에 구성하려는 범위입니다.
      • 이미지 가져오기: storage-ro
      • 이미지 가져오기 및 내보내기: storage-rw
      • 이미지 가져오기 및 내보내기, gcloud 명령어 실행: cloud-platform
  3. VM 인스턴스를 다시 시작합니다. 중지된 인스턴스 시작을 참조하세요.

Google Kubernetes Engine 클러스터의 범위 구성

기본적으로 새 GKE 클러스터는 Cloud Storage 버킷에 대한 읽기 전용 권한을 갖고 생성됩니다.

Google Kubernetes Engine 클러스터를 만들 때 read-write 스토리지 범위를 설정하려면 --scopes 옵션을 사용합니다. 예를 들어 다음 명령어는 범위가 bigquery, storage-rw, compute-ro인 클러스터를 만듭니다.

gcloud container clusters create example-cluster \
--scopes=bigquery,storage-rw,compute-ro

새 클러스터를 만들 때 설정할 수 있는 범위에 대한 자세한 내용은 gcloud container clusters create 명령어에 대한 문서를 참조하세요.