인증 방식

이 페이지에서는 Container Registry로 인증하도록 타사 클라이언트를 구성하는 방법을 설명합니다.

Container Registry와 통합되는 Google Cloud 서비스는 동일한 프로젝트의 저장소에 액세스할 수 있는 권한으로 사전 구성됩니다. 이러한 서비스에 대한 인증을 구성할 필요는 없지만 권한이 적절하게 구성되었는지 확인해야 합니다.

시작하기 전에

  1. 인증에 사용할 계정에는 레지스트리에 액세스할 수 있는 권한이 있어야 합니다. 사용자 계정이 아닌 서비스 계정을 사용하는 것이 좋습니다. 서비스 계정은 특정 사용자와 연결되지 않으며 Google Cloud 애플리케이션에서 애플리케이션 기본 사용자 인증 정보 전략을 사용하여 사용자 인증 정보를 자동으로 가져올 수 있습니다.

  2. Cloud SDK의 최신 버전을 설치합니다. 기존 설치를 업데이트하려면 gcloud components update 명령어를 실행합니다.

  3. Docker를 사용하려면 사용자 인증 정보 도우미가 PATH 시스템에 있어야 합니다. gcloud 명령어가 PATH 시스템에 있는지 확인합니다.

  4. Docker가 아직 설치되어 있지 않으면 설치합니다.

  5. Docker에는 레지스트리와 상호작용하기 위한 액세스 권한이 필요합니다. Docker가 Linux 또는 Windows에 설치된 경우 Docker 보안 그룹에 Docker 명령어를 실행하는 데 사용할 사용자를 추가합니다.

    MacOS에서는 Docker가 루트 사용자가 있는 가상 머신에서 실행되므로 이 단계가 필요하지 않습니다. MacOS의 Docker에 대한 자세한 내용은 Docker 문서를 참조하세요.

    Linux

    Docker 보안 그룹을 docker라고 합니다. 사용자 이름을 추가하려면 다음 명령어를 실행합니다.

    sudo usermod -a -G docker ${USER}
    

    Windows

    Docker 보안 그룹을 docker-users라고 합니다. 관리자 명령어 프롬프트에서 사용자를 추가하려면 다음 명령어를 실행합니다.

    net localgroup docker-users DOMAIN\USERNAME /add
    

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

    • DOMAIN은 Windows 도메인입니다.
    • USERNAME은 사용자 이름입니다.

    그룹 멤버십 변경사항을 적용하려면 로그아웃했다가 다시 로그인합니다. 가상 머신을 사용하는 경우 멤버십 변경사항을 적용하려면 가상 머신을 다시 시작해야 할 수 있습니다.

인증 방식

Container Registry에 액세스해야 하는 모든 타사 클라이언트를 구성해야 합니다.

다음과 같은 인증 방식을 사용할 수 있습니다.

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

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

가능하면 액세스 토큰 또는 사용 가능한 다른 인증 방법을 사용하여 아티팩트에 대한 무단 액세스의 위험을 줄이세요. 서비스 계정 키를 사용해야 하는 경우 사용자 인증 정보 관리 권장사항을 따라야 합니다.

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

사용자 인증 정보 도우미

Docker 사용자 인증 정보 도우미는 특정 레지스트리로 인증하도록 Docker를 구성합니다. Container Registry는 다음을 제공합니다.

  • gcloud 사용자 인증 정보 도우미
  • Cloud SDK를 사용할 수 없는 시스템의 독립형 사용자 인증 정보 도우미

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

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

gcloud를 사용하여 Cloud Shell 또는 Cloud SDK가 설치된 환경에서 인증을 구성합니다. Cloud Shell에는 Docker의 현재 버전이 포함되어 있습니다.

인증을 구성하려면 다음 안내를 따르세요.

  1. Docker 명령어를 실행할 사용자로 gcloud에 로그인합니다.

    • 사용자 인증 정보로 인증을 구성하려면 다음 명령어를 실행합니다.

      gcloud auth login
      
    • 서비스 계정 사용자 인증 정보로 인증을 구성하려면 다음 명령어를 실행합니다.

      gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
      

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

      • ACCOUNT[USERNAME]@[PROJECT-ID].iam.gserviceaccount.com 형식의 서비스 계정 이름입니다. Cloud Console의 서비스 계정 페이지 또는 gcloud iam service-accounts list 명령어를 사용하여 기존 서비스 계정을 볼 수 있습니다.
      • KEY-FILE은 서비스 계정 키 파일입니다. 키 만들기에 대한 자세한 내용은 ID 및 액세스 관리(IAM) 문서를 참조하세요.
  2. 다음 명령어로 Docker를 구성합니다.

    gcloud auth configure-docker
    

    사용자 인증 정보는 사용자 홈 디렉터리에 저장됩니다.

    • Linux: $HOME/.docker/config.json
    • Windows: %USERPROFILE%/.docker/config.json

이제 Docker가 Container Registry로 인증하도록 구성되었습니다. 이미지를 내보내고 가져오려면 권한이 올바르게 구성되어 있는지 확인합니다.

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

독립형 Docker 사용자 인증 정보 도우미는 Cloud SDK를 사용할 수 없는 시스템에서 Container Registry에 인증하도록 Docker를 구성합니다.

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

인증을 구성하려면 다음 안내를 따르세요.

  1. Docker 명령어를 실행할 사용자로 머신에 로그인합니다.

  2. 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/local/bin/docker-credential-gcr && chmod +x /usr/local/bin/docker-credential-gcr
    
  3. 다음 명령어로 Docker를 구성합니다.

    docker-credential-gcr configure-docker
    

    사용자 인증 정보는 사용자 홈 디렉터리에 저장됩니다.

    • Linux: $HOME/.docker/config.json
    • Windows: %USERPROFILE%/.docker/config.json

자세한 내용은 GitHub의 독립형 Docker 사용자 인증 정보 도우미 문서를 참조하세요.

이제 Docker가 Container Registry로 인증하도록 구성되었습니다. 이미지를 내보내고 가져오려면 권한이 올바르게 구성되어 있는지 확인합니다.

액세스 토큰

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

Google Cloud는 애플리케이션 기본 사용자 인증 정보를 사용하여 액세스 토큰을 얻습니다.

  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. 다음 명령어를 실행하여 Cloud SDK에 서비스 계정으로 로그인합니다.

    gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
    

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

    • ACCOUNT[USERNAME]@[PROJECT-ID].iam.gserviceaccount.com 형식의 서비스 계정 이름입니다.
    • KEY-FILE은 서비스 계정 키 파일입니다. 키를 만드는 방법은 IAM 문서를 참조하세요.
  3. 서비스 계정에 대해 권한이 올바르게 구성되었는지 확인합니다. Compute Engine 서비스 계정을 사용하는 경우 권한과 액세스 범위를 모두 올바르게 구성해야 합니다.

  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입니다.

이제 Docker가 Container Registry로 인증됩니다.

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. 서비스 계정에 대해 권한이 올바르게 구성되었는지 확인합니다. Compute Engine 서비스 계정을 사용하는 경우 권한과 액세스 범위를 모두 올바르게 구성해야 합니다.

  3. 서비스 계정 키를 비밀번호로 사용하여 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입니다.

    Windows

    • 사용자 이름_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입니다.

이제 Docker가 Container Registry로 인증됩니다.