인증 방식

이 페이지에서는 Container Registry에 대한 인증을 구성하는 방법을 설명합니다.

시작하기 전에

다음 사항을 확인하세요.

  1. gcloud 명령줄 도구가 포함된 최신 버전의 Cloud SDK를 설치했는지 여부

  2. Docker를 설치했는지 여부

인증 방식 선택

다음 인증 방법을 사용할 수 있습니다.

gcloud를 사용자 인증 정보 도우미로 사용(권장)
gcloud에서 직접 Docker에서 사용할 수 있도록 Container Registry 사용자 인증 정보를 구성합니다. 프로젝트 리소스에 대한 안전하고 일시적인 액세스가 가능한 경우에 이 방법을 사용합니다. 이 옵션은 Docker 버전 18.03 이상만 지원합니다.
독립형 Docker 사용자 인증 정보 도우미
이 옵션은 기본적으로 Cloud SDK가 없는 경우에 Docker에서 사용할 수 있도록 사용자 인증 정보를 구성합니다. 이 옵션은 Docker 버전 18.03 이상만 지원합니다.
액세스 토큰
애플리케이션 기본 사용자 인증 정보는 서비스 계정에서 Google Cloud 리소스에 액세스하는 데 사용하는 일시적인 액세스 토큰을 제공합니다. 사용자 인증 정보 도우미로 gcloud을 사용하는 것이 가장 안전합니다.
JSON 키 파일

서비스 계정의 사용자 인증 정보로 사용할 수 있는 사용자 관리형 키-쌍입니다. 사용자 인증 정보는 장기적이므로 사용 가능한 모든 인증 방법 중 보안 수준이 가장 낮은 옵션입니다.

가능한 경우 애플리케이션 기본 사용자 인증 정보 또는 다른 사용 가능한 인증 방법을 사용하여 아티팩트에 대한 승인되지 않은 액세스 위험을 줄입니다. 서비스 계정 키를 사용해야 하는 경우 사용자 인증 정보 관리 권장사항을 따라야 합니다.

일부 도구 또는 워크플로에서는 gcloud를 사용자 인증 정보 도우미로 사용할 수 없습니다. 대체 옵션 중 하나를 사용할 경우 보안상의 영향을 파악해야 합니다.

Docker 사용자 인증 정보 도우미로서의 gcloud

가능하다면 되도록 이 방법을 사용하세요. 프로젝트 리소스에 대한 안전하고 일시적인 액세스를 제공합니다.

Container Registry에 인증하려면 gcloud를 Docker 사용자 인증 정보 도우미로 사용합니다. 이렇게 하려면 다음 명령어를 실행하세요.

gcloud auth configure-docker
    

Container Registry를 인증하려면 이 명령어를 1회 실행해야 합니다.

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

Docker는 이미지를 내보내고 가져올 때 Container Registry에 액세스해야 합니다. gcloud가 필요 없는 Docker 사용자 인증 정보 도우미 docker-credential-gcr을 사용하여 Container Registry 사용자 인증 정보를 Docker에서 사용할 수 있도록 구성할 수 있습니다.

사용자 인증 정보 도우미는 Container Registry 사용자 인증 정보를 자동으로 또는 --token-source 플래그로 지정한 위치에서 가져온 후 Docker의 구성 파일에 기록합니다. 이렇게 하면 Docker의 명령줄 도구 docker를 사용하여 Container Registry와 직접 상호 작용할 수 있습니다.

Docker 사용자 인증 정보 도우미 사용 방법:

  1. GitHub 출시 버전에서 docker-credential-gcr을 다운로드합니다.

    원하는 경우 curl 명령줄 유틸리티를 사용할 수 있습니다. 예:

    VERSION=2.0.0
        OS=linux  # or "darwin" for OSX, "windows" for Windows.
        ARCH=amd64  # or "386" for 32-bit OSs, "arm64" for ARM 64.
    
        curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \
          | tar xz --to-stdout ./docker-credential-gcr \
          > /usr/bin/docker-credential-gcr && chmod +x /usr/bin/docker-credential-gcr
          ```
        
  2. Container Registry와 상호작용할 때 Container Registry 사용자 인증 정보를 사용하도록 Docker를 구성합니다. 이 작업을 한 번만 수행하면 됩니다.

    docker-credential-gcr configure-docker
        

    자세한 내용은 GitHub에 대한 docker-credential-gcr의 주요 문서를 참조하세요.

  3. 서비스 계정이 Compute Engine VM 인스턴스에서 이미지를 내보내거나 가져오는 경우 필요한 액세스 수준에 맞도록 액세스 범위를 구성합니다.

액세스 토큰

액세스 토큰은 Google Cloud 리소스에 대한 액세스를 제공하는 일시적인 사용자 자격 증명입니다. 액세스 토큰을 비밀번호로 사용하여 Container Registry에 연결할 수 있습니다.

액세스 토큰을 사용하려면 애플리케이션 기본 사용자 인증 정보 문서를 참조하세요. 그런 다음 아래 사용자 인증 정보를 사용하면 됩니다.

  1. Container Registry와 상호작용할 서비스 계정의 키를 가져옵니다.

    Console

    1. Google Cloud Console에서 서비스 계정 키 만들기 페이지를 엽니다.

      서비스 계정 키 만들기 페이지로 이동

    2. 서비스 계정 목록에서 사용할 서비스 계정을 선택합니다.

      새 서비스 계정을 만들려면 새 서비스 계정을 선택하고 서비스 계정에 부여할 권한에 따라 서비스 계정 이름, ID, 적절한 Container Registry 역할을 지정합니다.

    3. 키 유형으로 JSON을 선택합니다.

    4. 만들기를 클릭합니다. 키가 포함된 JSON 파일이 컴퓨터에 다운로드됩니다.

      이 페이지의 안내는 이 키 파일에 keyfile.json 파일 이름을 사용합니다.

    gcloud

    로컬 머신 또는 Cloud Shell에서 Cloud SDK를 사용하여 다음 명령어를 실행할 수 있습니다.

    1. 서비스 계정을 만듭니다. NAME을 서비스 계정의 이름으로 바꿉니다.

          gcloud iam service-accounts create NAME
          
    2. 서비스 계정에 권한을 부여합니다. PROJECT_ID를 프로젝트 ID로 바꾸고 ROLE을 서비스 계정에 적절한 Container Registry 역할로 바꿉니다. 이 역할은 프로젝트의 저장소에 적용됩니다. 나중에 역할을 변경할 수 있고 특정 저장소에서 서비스 계정에 다른 권한을 설정할 수도 있습니다.

          gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
          
    3. 키 파일을 생성합니다. 이 페이지의 안내는 이 키 파일에 keyfile.json 파일 이름을 사용합니다.

          gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
          
  2. 서비스 계정이 Compute Engine VM 인스턴스에서 이미지를 내보내거나 가져오는 경우 필요한 액세스 수준에 맞도록 액세스 범위를 구성합니다.

  3. 다음 명령어를 실행하여 Cloud SDK에 서비스 계정으로 로그인합니다. 이 명령어에서 keyfile.json은 서비스 계정에 생성된 키 파일입니다.

    gcloud auth activate-service-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com --key-file=keyfile.json
        
  4. 서비스 계정의 액세스 토큰을 가져옵니다. 토큰은 일시적으로 Container Registry와 연결하는 데 사용하기 한 시간 전에 요청합니다.

    Linux/macOS

    • 사용자 이름oauth2accesstoken입니다.
    • 비밀번호는 사용자의 액세스 토큰입니다. 예: gcloud auth print-access-token

    예를 들면 다음과 같습니다.

    gcloud auth print-access-token | docker login -u oauth2accesstoken --password-stdin https://[HOSTNAME]
        

    여기서 [HOSTNAME]gcr.io, us.gcr.io, eu.gcr.io 또는 asia.gcr.io입니다.

    또는 --password-stdin을 지원하지 않는 이전 Docker 클라이언트의 경우:

    docker login -u oauth2accesstoken -p "$(gcloud auth print-access-token)" https://[HOSTNAME]
        

    Windows

    • 사용자 이름oauth2accesstoken입니다.
    • 비밀번호gcloud auth print-access-token의 출력입니다.
    1. 액세스 토큰 가져오기
    gcloud auth print-access-token
        

    반환되는 문자열은 비밀번호로 사용하는 액세스 토큰입니다. 이 예시에서 ya29.8QEQIfY_...는 반환된 액세스 토큰을 나타냅니다.

    ya29.8QEQIfY_...
        
    1. 액세스 토큰으로 로그인
    docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." https://[HOSTNAME]
        

    여기서 [HOSTNAME]gcr.io, us.gcr.io, eu.gcr.io 또는 asia.gcr.io입니다.

JSON 키 파일

서비스 계정 키는 서비스 계정의 사용자 인증 정보로 사용할 수 있는 수명이 긴 키-쌍입니다. 비공개 키의 보안 및 키 순환과 같은 다른 키 관리 작업의 책임은 사용자에게 있습니다.

서비스 계정의 유효한 비공개 키에 액세스할 수 있는 사용자는 누구나 서비스 계정을 통해 리소스에 액세스할 수 있습니다. 예를 들어 Container Registry 서비스 계정과 같이 Google Cloud에서 자동으로 만든 일부 서비스 계정에는 상위 프로젝트에 대한 읽기-쓰기 Editor 역할이 부여됩니다. Compute Engine 기본 서비스 계정은 동일한 프로젝트 내 스토리지에 대한 읽기 전용 액세스 권한으로 구성됩니다.

또한 서비스 계정에 대한 키의 액세스 수명 주기(즉, 서비스 계정이 액세스한 데이터)는 키를 다운로드한 사용자의 수명 주기와는 관계가 없습니다.

컨테이너 이미지에 대한 액세스를 제한하려면 다음 가이드라인을 따릅니다.

  • Container Registry와 상호작용하는 데에만 사용되는 전용 서비스 계정을 만듭니다.
  • 서비스 계정에 필요한 액세스 권한이 가장 낮은 특정 역할을 부여합니다.
  • 사용자 인증 정보 관리 권장사항을 따릅니다.

Container Registry 저장소에서만 사용할 수 있도록 새 서비스 계정과 서비스 계정 키를 만들려면 다음 안내를 따르세요.

  1. 저장소와 상호작용할 수 있도록 서비스 계정을 만듭니다.

    Console

    1. Google Cloud Console에서 서비스 계정 키 만들기 페이지를 엽니다.

      서비스 계정 키 만들기 페이지로 이동

    2. 서비스 계정 목록에서 새 서비스 계정을 선택합니다.

    3. 서비스 계정 이름 필드에 이름을 입력합니다.

    4. 역할 목록에서 서비스 계정에 적절한 Container Registry 역할을 선택합니다.

    5. 만들기를 클릭합니다. 키가 포함된 JSON 파일이 컴퓨터에 다운로드됩니다.

      이 페이지의 안내는 이 키 파일에 keyfile.json 파일 이름을 사용합니다.

    gcloud

    로컬 머신 또는 Cloud Shell에서 Cloud SDK를 사용하여 다음 명령어를 실행할 수 있습니다.

    1. 서비스 계정을 만듭니다. NAME을 서비스 계정의 이름으로 바꿉니다.

          gcloud iam service-accounts create NAME
          
    2. 서비스 계정에 권한을 부여합니다. PROJECT_ID를 프로젝트 ID로, ROLE을 서비스 계정에 적절한 역할로 바꿉니다.

          gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
          
    3. 키 파일을 생성합니다. 이 예시에서 출력 키 파일 이름은 keyfile.json입니다.

          gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
          
  2. 서비스 계정 키를 비밀번호로 사용하여 Docker를 인증합니다.

    Linux/macOS

    • 사용자 이름_json_key입니다(서비스 계정의 이름이 아님).
    • keyfile.json은 사용자가 만든 서비스 계정 키입니다.

    예:

    cat keyfile.json | docker login -u _json_key --password-stdin https://[HOSTNAME]
        

    여기서 [HOSTNAME]gcr.io, us.gcr.io, eu.gcr.io 또는 asia.gcr.io입니다.

    또는 --password-stdin을 지원하지 않는 이전 Docker 클라이언트의 경우:

    docker login -u _json_key -p "$(cat keyfile.json)" https://[HOSTNAME]
        

    여기서 [HOSTNAME]gcr.io, us.gcr.io, eu.gcr.io 또는 asia.gcr.io입니다.

    기간

    • 사용자 이름_json_key입니다(서비스 계정의 이름이 아님).
    • keyfile.json에는 서비스 계정 JSON 키가 포함되어 있습니다.

    예:

    docker login -u _json_key --password-stdin https://[HOSTNAME] < keyfile.json
        

    여기서 [HOSTNAME]gcr.io, us.gcr.io, eu.gcr.io 또는 asia.gcr.io입니다.

    또는 --password-stdin을 지원하지 않는 이전 Docker 클라이언트의 경우:

    set /p PASS=<keyfile.json
        docker login -u _json_key -p "%PASS%" https://[HOSTNAME]
        

    여기서 [HOSTNAME]gcr.io, us.gcr.io, eu.gcr.io 또는 asia.gcr.io입니다.

  3. 서비스 계정이 Compute Engine VM 인스턴스에서 이미지를 내보내거나 가져오는 경우 필요한 액세스 수준에 맞도록 액세스 범위를 구성합니다.

Google Cloud에서 Container Registry 사용

Compute Engine 인스턴스와 Google Kubernetes Engine 클러스터는 인스턴스의 Cloud Storage 범위에 따라 Container Registry 이미지를 내보내고 가져올 수 있습니다. Google Cloud에서 Container Registry 사용을 참조하세요.

Container Registry에 저장된 이미지를 App Engine 가변형 환경에 배포할 수 있습니다.