Google Cloud 워크로드 ID 연동 및 IAM 정책

Tier: Free, Premium, Ultimate Offering: GitLab.com Status: Beta

- 소개된 내용은 GitLab 16.10에 포함되어 있습니다. google_cloud_support_feature_flag 라는 플래그로 Beta 단계에 있습니다.

GitLab.com에서 이 기능은 일부 사용자를 대상으로 합니다. 그러나 GitLab Dedicated에서는 이 기능을 사용할 수 없습니다.

이 기능은 Beta 단계에 있습니다. 이 기능을 테스트하는 사용자 목록에 추가하려면 대기 목록에 가입하세요.

Google Cloud Artifact Registry와 같은 Google Cloud 통합을 사용하려면 워크로드 ID 풀 및 제공자를 생성하고 구성해야 합니다. Google Cloud 통합은 워크로드 ID 연동을 사용하여 JSON Web Token (JWT) 토큰을 통해 GitLab 워크로드가 Google Cloud 리소스에 OpenID Connect (OIDC)를 통해 액세스할 수 있도록 합니다.

워크로드 ID 연동 생성 및 구성

워크로드 ID 연동을 설정하는 방법은 다음 중 하나를 사용할 수 있습니다:

  • GitLab UI를 사용하여 안내 받기.
  • Google Cloud CLI를 사용하여 워크로드 ID 연동을 수동으로 설정하기.

GitLab UI 사용

GitLab UI를 사용하여 워크로드 ID 연동을 설정하려면 다음 단계를 수행하세요:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 통합을 선택합니다.
  3. Google Cloud IAM 통합을 찾아 구성을 선택합니다.
  4. 안내 설정을 선택하고 지시 사항을 따릅니다.

참고: 알려진 문제로 인해, Google Cloud IAM 통합 페이지의 필드가 안내 설정 스크립트를 실행한 후에 채워지지 않을 수 있습니다. 필드가 비어 있는 경우 페이지를 새로 고침하십시오. 자세한 내용은 issue 448831을 참조하십시오.

Google Cloud CLI 사용

필수 조건:

  • Google Cloud CLI를 설치하고 Google Cloud에 대해 인증되어 있어야 합니다.
  • Google Cloud의 워크로드 ID 연동을 관리하기 위한 권한을 가지고 있어야 합니다.

  1. 다음 명령을 사용하여 워크로드 ID 풀을 생성합니다. 다음 값을 대체하십시오:

    • <your_google_cloud_project_id>: Google Cloud 프로젝트 ID. 보안을 개선하기 위해 리소스 및 CI/CD 프로젝트와는 별도의 프로젝트를 사용할 것을 권장합니다.
    • <your_identity_pool_id>: 풀에 사용할 ID로, 4~32자의 영문 소문자, 숫자 또는 하이픈을 사용해야 합니다. 충돌을 피하기 위해 고유한 ID를 사용해야 합니다. IAM 정책 관리를 용이하게 하기 위해 GitLab 프로젝트 ID 또는 경로를 포함하는 것이 좋습니다. 예: gitlab-my-project-name. 
    gcloud iam workload-identity-pools create <your_identity_pool_id> \
         --project="<your_google_cloud_project_id>" \
         --location="global" \
         --display-name="GitLab 프로젝트 ID를 위한 워크로드 ID 풀"

  2. 다음 명령을 사용하여 워크로드 ID 풀에 OIDC 제공자를 추가합니다. 다음 값을 대체하십시오:

    • <your_identity_provider_id>: 제공자에 사용할 ID로, 4~32자의 영문 소문자, 숫자 또는 하이픈을 사용해야 합니다. 풀 내에서 고유한 ID를 사용해야 합니다. 예: gitlab.
    • <your_google_cloud_project_id>: Google Cloud 프로젝트 ID.
    • <your_identity_pool_id>: 이전 단계에서 생성한 워크로드 ID 풀의 ID.
    • <your_issuer_uri>: ID 제공자 발급자 URI로, IAM 통합 페이지를 선택하여 수동 설정을 선택할 때 복사할 수 있으며, 정확히 일치해야 합니다. 이 매개변수에는 루트 그룹의 경로를 포함해야 합니다. 예를 들어, 프로젝트가 my-root-group/my-sub-group/project-a에 속한 경우 issuer-uri는 https://auth.gcp.gitlab.com/oidc/my-root-group로 설정되어야 합니다. 
    gcloud iam workload-identity-pools providers create-oidc "<your_identity_provider_id>" \
      --location="global" \
      --project="<your_google_cloud_project_id>" \
      --workload-identity-pool="<your_identity_pool_id>" \
      --issuer-uri="<your_issuer_uri>" \
      --display-name="GitLab OIDC 제공자" \
      --attribute-mapping="attribute.guest_access=assertion.guest_access,\
attribute.reporter_access=assertion.reporter_access,\
attribute.developer_access=assertion.developer_access,\
attribute.maintainer_access=assertion.maintainer_access,\
attribute.owner_access=assertion.owner_access,\
attribute.namespace_id=assertion.namespace_id,\
attribute.namespace_path=assertion.namespace_path,\
attribute.project_id=assertion.project_id,\
attribute.project_path=assertion.project_path,\
attribute.user_id=assertion.user_id,\
attribute.user_login=assertion.user_login,\
attribute.user_email=assertion.user_email,\
attribute.user_access_level=assertion.user_access_level,\
google.subject=assertion.sub"
    • attribute-mapping 매개변수에는 JWT ID 토큰에 포함된 OIDC 사용자 지정 클레임에서 IAM 정책에 액세스를 부여하는 데 사용되는 해당 ID 속성으로의 매핑이 포함되어야 합니다. 소유권 및 액세스 수준을 구성하는 사용자 지정 클레임의 목록에 대해서는 지원되는 OIDC 사용자 지정 클레임 목록을 참조하십시오. 클레임을 IAM 정책에 매핑하는 자세한 내용은 Google Cloud 액세스 제어을 참조하십시오.

워크로드 ID 풀과 제공자를 생성한 후, GitLab에서 설정을 완료하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 통합을 선택합니다.
  3. Google Cloud IAM 통합을 찾아 구성을 선택합니다.
  4. 수동 설정을 선택합니다.
  5. 필드를 완성합니다.
    • 워크로드 ID 풀 및 제공자를 생성한 Google Cloud 프로젝트의 프로젝트 ID. 예: my-sample-project-191923.
    • 동일한 Google Cloud 프로젝트의 프로젝트 번호. 예: 314053285323.
    • 이 통합을 위해 생성한 워크로드 ID 풀의 풀 ID.
    • 이 통합을 위해 생성한 워크로드 ID 제공자의 제공자 ID.

OIDC 사용자 정의 클레임

ID 토큰에는 다음과 같은 사용자 정의 클레임이 포함됩니다.

클레임 이름 시점 설명
namespace_id 프로젝트 이벤트 시 그룹 또는 사용자 레벨 네임스페이스의 ID입니다.
namespace_path 프로젝트 이벤트 시 그룹 또는 사용자 레벨 네임스페이스의 경로입니다.
project_id 프로젝트 이벤트 시 프로젝트의 ID입니다.
project_path 프로젝트 이벤트 시 프로젝트의 경로입니다.
root_namespace_id 그룹 이벤트 시 루트 그룹 또는 사용자 레벨 네임스페이스의 ID입니다.
root_namespace_path 그룹 이벤트 시 루트 그룹 또는 사용자 레벨 네임스페이스의 경로입니다.
user_id 사용자 이벤트 시 사용자의 ID입니다.
user_login 사용자 이벤트 시 사용자의 사용자 이름입니다.
user_email 사용자 이벤트 시 사용자의 이메일입니다.
ci_config_ref_uri CI/CD 파이프라인 실행 중 최상위 CI 파이프라인 정의로의 참조 경로입니다.
ci_config_sha CI/CD 파이프라인 실행 중 ci_config_ref_uri에 대한 Git 커밋 SHA입니다.
job_id CI/CD 파이프라인 실행 중 CI 작업의 ID입니다.
pipeline_id CI/CD 파이프라인 실행 중 CI 파이프라인의 ID입니다.
pipeline_source CI/CD 파이프라인 실행 중 CI 파이프라인 소스입니다.
project_visibility CI/CD 파이프라인 실행 중 파이프라인이 실행되는 프로젝트의 가시성입니다.
ref CI/CD 파이프라인 실행 중 CI 작업에 대한 Git ref입니다.
ref_path CI/CD 파이프라인 실행 중 CI 작업에 대한 완전한 참조입니다.
ref_protected CI/CD 파이프라인 실행 중 Git ref가 보호되었는지 여부입니다.
ref_type CI/CD 파이프라인 실행 중 Git ref 유형입니다.
runner_environment CI/CD 파이프라인 실행 중 CI 작업에서 사용되는 러너 유형입니다.
runner_id CI/CD 파이프라인 실행 중 CI 작업을 실행하는 러너의 ID입니다.
sha CI/CD 파이프라인 실행 중 CI 작업의 커밋 SHA입니다.
environment CI/CD 파이프라인 실행 중 CI 작업이 배포된 환경입니다.
environment_protected CI/CD 파이프라인 실행 중 배포된 환경이 보호되었는지 여부입니다.
environment_action CI/CD 파이프라인 실행 중 CI 작업에서 지정된 환경 작업입니다.
deployment_tier CI/CD 파이프라인 실행 중 CI 작업이 지정하는 환경의 배포 계층입니다.
user_access_level 사용자 이벤트 시 사용자의 역할로 guest, reporter, developer, maintainer, owner의 값이 있습니다.
guest_access 사용자 이벤트 시 사용자가 적어도 guest 역할을 가지고 있는지 여부를 나타냅니다. 값은 문자열 “true” 또는 “false”입니다.
reporter_access 사용자 이벤트 시 사용자가 적어도 reporter 역할을 가지고 있는지 여부를 나타냅니다. 값은 문자열 “true” 또는 “false”입니다.
developer_access 사용자 이벤트 시 사용자가 적어도 developer 역할을 가지고 있는지 여부를 나타냅니다. 값은 문자열 “true” 또는 “false”입니다.
maintainer_access 사용자 이벤트 시 사용자가 적어도 maintainer 역할을 가지고 있는지 여부를 나타냅니다. 값은 문자열 “true” 또는 “false”입니다.
owner_access 사용자 이벤트 시 사용자가 적어도 owner 역할을 가지고 있는지 여부를 나타냅니다. 값은 문자열 “true” 또는 “false”입니다.

이러한 클레임들은 ID 토큰 클레임의 슈퍼셋입니다. 모든 값은 문자열 유형입니다. 자세한 내용 및 예시 값에 대해서는 ID 토큰 클레임 문서를 참조하세요.