히스토리

• GitLab 16.10에서 google_cloud_support_feature_flag라는 플래그와 함께 도입됨.
• GitLab 17.1에서 GitLab.com에서 활성화됨. 기능 플래그 google_cloud_support_feature_flag 제거됨.

Google Artifact Management 통합과 같은 Google Cloud 통합을 사용하려면 워크로드 아이덴티티 풀 및 공급자를 생성하고 구성해야 합니다. Google Cloud 통합은 Workload Identity Federation을 사용하여 JSON Web Token(JWT) 토큰을 통해 OpenID Connect(OIDC)를 사용하여 GitLab 워크로드에 Google Cloud 리소스에 대한 액세스 권한을 부여합니다.

Workload Identity Federation#

Workload Identity Federation을 사용하면 Identity and Access Management(IAM)를 사용하여 외부 아이덴티티에 IAM 역할을 부여할 수 있습니다.

전통적으로 Google Cloud 외부에서 실행되는 애플리케이션은 Google Cloud 리소스에 액세스하기 위해 서비스 계정 키를 사용했습니다. 그러나 서비스 계정 키는 강력한 자격 증명이며, 올바르게 관리되지 않으면 보안 위험을 초래할 수 있습니다.

아이덴티티 페더레이션을 사용하면 Identity and Access Management(IAM)를 사용하여 서비스 계정 없이 외부 아이덴티티에 IAM 역할을 직접 부여할 수 있습니다. 이 방식은 서비스 계정과 해당 키와 관련된 유지 관리 및 보안 부담을 제거합니다.

워크로드 아이덴티티 풀#

_워크로드 아이덴티티 풀_은 Google Cloud에서 비-Google 아이덴티티를 관리할 수 있는 엔티티입니다.

Google Cloud의 GitLab 통합은 Google Cloud에 인증하기 위한 워크로드 아이덴티티 풀 설정을 안내합니다. 이 설정에는 GitLab 역할 속성을 Google Cloud IAM 정책의 IAM 클레임에 매핑하는 것이 포함됩니다. Google Cloud의 GitLab 통합에 사용 가능한 GitLab 속성의 전체 목록은 OIDC 커스텀 클레임을 참조하세요.

워크로드 아이덴티티 풀 공급자#

_워크로드 아이덴티티 풀 공급자_는 Google Cloud와 아이덴티티 공급자(IdP) 간의 관계를 설명하는 엔티티입니다. GitLab은 Google Cloud의 GitLab 통합을 위한 워크로드 아이덴티티 풀의 IdP입니다.

외부 워크로드의 아이덴티티 페더레이션에 대한 자세한 내용은 Workload Identity Federation을 참조하세요.

기본 Google Cloud의 GitLab 통합은 GitLab 조직 수준에서 GitLab에서 Google Cloud로의 인증을 설정하려는 것을 가정합니다. 프로젝트별로 Google Cloud에 대한 액세스를 제어하려면 워크로드 아이덴티티 풀 공급자의 IAM 정책을 구성해야 합니다. GitLab 조직에서 Google Cloud에 액세스할 수 있는 사람을 제어하는 방법에 대한 자세한 내용은 IAM을 사용한 액세스 제어를 참조하세요.

Workload Identity Federation을 사용한 GitLab 인증#

워크로드 아이덴티티 풀과 공급자가 GitLab 역할 및 권한을 IAM 역할에 매핑하도록 설정된 후, Google Cloud에서 권한 부여를 위해 identity 키워드를 google_cloud로 설정하여 GitLab에서 Google Cloud로 워크로드를 배포하는 러너를 프로비저닝할 수 있습니다.

Google Cloud의 GitLab 통합을 사용하여 러너를 프로비저닝하는 방법에 대한 자세한 내용은 튜토리얼 Google Cloud에서 러너 프로비저닝을 참조하세요.

Workload Identity Federation 생성 및 구성#

Workload Identity Federation을 설정하려면 다음 중 하나를 사용할 수 있습니다:

• 안내된 설정을 위해 GitLab UI 사용.
• Workload Identity Federation을 수동으로 설정하기 위해 Google Cloud CLI 사용.

GitLab UI를 사용하여#

Workload Identity Federation 설정에 GitLab UI를 사용하려면:

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

Google Cloud CLI를 사용하여#

사전 조건:

• Google Cloud CLI가 Google Cloud와 함께 설치되고 인증되어 있어야 합니다.
• Google Cloud에서 Workload Identity Federation을 관리할 권한이 있어야 합니다.

1. 다음 명령으로 워크로드 아이덴티티 풀을 생성합니다. 다음 값을 교체합니다:

   • <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="Workload identity pool for GitLab project ID"
   

2. 다음 명령으로 워크로드 아이덴티티 풀에 OIDC 공급자를 추가합니다. 다음 값을 교체합니다:

   • <your_identity_provider_id> - 공급자에 사용할 ID. 4~32자의 소문자, 숫자 또는 하이픈이어야 합니다. 아이덴티티 풀에서 충돌을 피하려면 고유한 ID를 사용하세요. 예: gitlab.
   • <your_google_cloud_project_id> - Google Cloud 프로젝트 ID.
   • <your_identity_pool_id> - 이전 단계에서 생성한 워크로드 아이덴티티 풀의 ID.
   • <your_issuer_uri> - 아이덴티티 공급자 발급자 URI. 수동 설정을 선택할 때 IAM 통합 페이지에서 복사할 수 있으며 값과 정확히 일치해야 합니다. 매개변수에는 최상위 그룹의 경로가 포함되어야 합니다. 예를 들어 프로젝트가 my-root-group/my-subgroup/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 provider" \
         --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 커스텀 클레임과 액세스 권한 부여를 위해 Identity and Access Management(IAM) 정책에서 사용되는 해당 아이덴티티 속성 간의 매핑이 포함되어야 합니다. 자세한 내용은 Google Cloud에 대한 액세스 제어에 사용할 수 있는 지원되는 OIDC 커스텀 클레임을 참조하세요.

특정 GitLab 프로젝트 또는 그룹으로 아이덴티티 토큰 액세스를 제한하려면 속성 조건을 사용합니다. 프로젝트에는 assertion.project_id 속성을, 그룹에는 assertion.namespace_id 속성을 사용합니다. 자세한 내용은 속성 조건 정의 방법에 대한 Google Cloud 설명서를 참조하세요. 속성 조건을 정의한 후 워크로드 아이덴티티 공급자를 업데이트할 수 있습니다.

워크로드 아이덴티티 풀과 공급자를 생성한 후 GitLab에서 설정을 완료하려면:

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

OIDC 커스텀 클레임#

ID 토큰에는 다음 커스텀 클레임이 포함됩니다:

이 클레임은 ID 토큰 클레임의 상위 집합입니다. 모든 값은 문자열 유형입니다. 자세한 내용과 예시 값은 ID 토큰 클레임 설명서를 참조하세요.

Google Cloud에 대한 액세스 제어#

Workload Identity Federation을 설정하면 많은 표준 GitLab 클레임(예: user_access_level)이 자동으로 Google Cloud 속성에 매핑됩니다.

GitLab 조직에서 Google Cloud에 액세스할 수 있는 사람을 추가로 커스터마이즈할 수 있습니다. 이를 위해 Google Cloud의 GitLab 통합을 위한 OIDC 커스텀 속성을 기반으로 주체를 설정하는 Common Expression Language(CEL)을 사용합니다.

예를 들어, GitLab 프로젝트 gitlab-org/my-project에서 maintainer 역할을 가진 사용자가 GitLab에서 Google Artifact Registry로 아티팩트를 푸시할 수 있도록 허용하려면:

1. Google Cloud Console에 로그인하고 Workload Identity Federation 페이지로 이동합니다.

2. 표시 이름 열에서 워크로드 아이덴티티 풀을 선택합니다.

3. 공급자 섹션에서 편집할 워크로드 아이덴티티 공급자 옆의 편집 (✏️)을 선택하여 공급자 세부 정보를 엽니다.

4. 속성 매핑 섹션에서 매핑 추가를 선택합니다.

5. Google N 텍스트 상자에 다음을 입력합니다:

   attribute.my_project_maintainer
   

6. OIDC N 텍스트 상자에 다음 CEL 표현식을 입력합니다:

   assertion.maintainer_access=="true" && assertion.project_path=="gitlab-org/my-project"
   

7. 저장을 선택합니다.

   Google 속성 my_project_maintainer는 GitLab 클레임 maintainer_access==true 및 project_path=="gitlab-org/my-project"에 매핑됩니다.

8. Google Cloud Console에서 IAM 페이지로 이동합니다.

9. 액세스 권한 부여를 선택합니다.

10. 새 주체 텍스트 상자에 다음 형식으로 attribute.my_project_maintainer/true를 포함하는 주체 집합을 입력합니다:

    principalSet://iam.googleapis.com/projects//locations/global/workloadIdentityPools//attribute.my_project_maintainer/true
    

    다음을 교체합니다:

    • - Google Cloud 프로젝트 번호. 프로젝트 번호를 찾으려면 프로젝트 식별을 참조하세요.
    • - 워크로드 아이덴티티 풀 ID.

11. 역할 선택 드롭다운 목록에서 Google Artifact Registry 작성자 역할(roles/artifactregistry.writer)을 선택합니다.

12. 저장을 선택합니다.

역할은 프로젝트 gitlab-org/my-project에서 GitLab maintainer 역할을 가진 사용자를 포함하는 주체 집합에 부여됩니다.

다른 GitLab 프로젝트가 Google Artifact Registry로 아티팩트를 푸시하지 못하도록 하려면 Google Cloud Console에서 IAM 정책을 보고 필요에 따라 역할을 제거하거나 편집할 수 있습니다.

IAM 정책 보기#

Google Cloud Console에 로그인하고 IAM 페이지로 이동합니다.

주체별 보기 또는 역할별 보기를 선택할 수 있습니다.