GitLab과 워크로드 아이덴티티 페더레이션

GitLab과 워크로드 아이덴티티 페더레이션 (Federate workload identity with GitLab)

GitLab CI/CD Pipeline에서 GitLab ID 토큰을 사용해 인증하도록 워크로드 아이덴티티 페더레이션을 설정하는 방법을 설명해 드릴게요. 인증된 워크로드는 HCP 서비스 주체 키를 전혀 저장하지 않고 HCP 서비스와 상호작용할 수 있어요.

출처: 문서

본문

사전 요구 사항

GitLab용 워크로드 아이덴티티 제공자를 구성하기 전에 다음 단계를 완료해야 해요.

  • HCP 프로젝트에 대한 Admin 역할이 있어야 해요.
  • 원하는 프로젝트에 서비스 주체를 만들고 워크로드가 필요로 하는 HCP 리소스에 대한 접근 권한을 부여해요.
  • HCP로의 접근을 페더레이션할 GitLab CI/CD Pipeline에 대한 접근 권한이 있어야 해요.
  • 원하는 구성 워크플로에 따라 HCP CLI를 설치하거나 HCP Terraform Provider를 사용해요.

GitLab용 외부 워크로드 아이덴티티 제공자 구성

GitLab CI/CD용 HCP 워크로드 아이덴티티 제공자를 만들려면 조건부 접근 문이 필요해요.

조건부 접근 문 (Conditional access statement)

워크로드 아이덴티티를 페더레이션할 때 요구 사항 중 하나가 조건부 접근 문이에요. 이 문은 아이덴티티 클레임에 접근할 수 있고 어떤 외부 아이덴티티가 허용되는지 제한하는 불리언 표현식이에요.

아이덴티티 토큰을 HCP 접근 권한으로 교환할 때, 조건부 접근 문은 jwt_claims. 접두어로 토큰의 모든 클레임에 접근할 수 있어요. 자세한 내용은 GitLab 문서의 token 클레임 레퍼런스를 참고하세요.

다음 예시 조건부 접근 문은 acme-group/acme-project 리포지토리에서 시작된 jobs에 대해서만 HCP 서비스 접근을 제한해요.

`jwt_claims.project_path == "acme-group/acme-project"`

더 제한하여 Git main 브랜치의 요청만 인증되도록 하려면 추가 선택자와 값을 더할 수 있어요.

`jwt_claims.sub == "project_path:acme-group/acme-project:ref_type:branch:ref:main"`

선택자와 값을 사용해 복합 조건부 접근 문을 만드는 방법에 대한 자세한 내용은 conditional access statements 문서를 참고하세요.

워크로드 아이덴티티 제공자 만들기

필요한 정보를 정리한 뒤 GitLab용 워크로드 아이덴티티 제공자를 만들어요.

HCP CLI / Terraform

hcp iam workload-identity-providers create-oidc 명령을 사용해요.

$ hcp iam workload-identity-providers create-oidc <PROVIDER_NAME> \
  --service-principal=<SP_RESOURCE_NAME> \
  --issuer=https://gitlab.com \
  --conditional-access=<CONDITION> \
  --description=<DESCRIPTION>

이 명령에는 HCP와 GitLab 계정에 특정한 다음 정보가 필요해요.

  • <PROVIDER_NAME>: 만들 워크로드 아이덴티티 제공자의 이름.
  • <SP_RESOURCE_NAME>: iam/project/<PROJECT_ID>/service-principal/<NAME> 형식의 서비스 주체 리소스 이름.
  • <CONDITION>: 지정된 리포지토리와 브랜치에 대한 접근을 제한하는 조건부 접근 문.
  • <DESCRIPTION>: 프로바이더에 대한 선택적인 설명.

다음 예시는 gitlab-example이라는 워크로드 아이덴티티 제공자를 만들어요. 이 제공자는 JWT 토큰이 acme-group/acme-project의 main 브랜치에서 시작된 액션임을 식별하도록 요구해 GitLab 접근만 제한하도록 HCP를 구성해요. HCP 서비스에 대한 접근 권한을 부여받은 워크로드는 my-app-deployer 서비스 주체를 사용해요.

$ hcp iam workload-identity-providers create-oidc gitlab-example \
  --service-principal=iam/project/dcffbc8c-0873-4acc-bf96-4c79a4c3fd1a/service-principal/my-app-deployer \
  --issuer=https://gitlab.com \
  --conditional-access='jwt_claims.sub == "project_path:acme-group/acme-project:ref_type:branch:ref:main"' \
  --description="Allow acme-repo deploy job to access my-app-deployer service principal"

hcp_iam_workload_identity_provider 리소스를 사용해요.

# Replace with an existing service principal if created ahead of time.
resource "hcp_service_principal" "deployment_sp" {
  name = "my-app-deployer"
}

resource "hcp_iam_workload_identity_provider" "example" {
  name              = "gitlab-example"
  service_principal = hcp_service_principal.deployment_sp.resource_name
  description       = "Allow acme-project deploy job to access my-app-runtime service principal"

  oidc {
    issuer_uri = "https://gitlab.com"
  }

  conditional_access = "<CONDITION>"
}

이 구성에는 GitLab 계정에 특정한 다음 정보가 필요해요.

  • <CONDITION>: 지정된 리포지토리와 브랜치에 대한 접근을 제한하는 조건부 접근 문.

다음 예시는 gitlab-example이라는 워크로드 아이덴티티 제공자를 만들어요. 이 제공자는 JWT 토큰이 acme-group/acme-project의 main 브랜치에서 시작된 워크로드임을 식별하도록 요구해 GitLab 접근만 제한하도록 HCP를 구성해요. HCP 서비스에 대한 접근 권한을 부여받은 워크로드는 my-app-deployer 서비스 주체를 사용해요.

# Replace with an existing service principal if created ahead of time.
resource "hcp_service_principal" "deployment_sp" {
  name = "my-app-deployer"
}

resource "hcp_iam_workload_identity_provider" "example" {
  name              = "gitlab-example"
  service_principal = hcp_service_principal.deployment_sp.resource_name
  description       = "Allow acme-repo deploy workflow to access my-app-deployer service principal"

  oidc {
    issuer_uri = "https://gitlab.com"
  }

  conditional_access = "jwt_claims.sub == `project_path:acme-group/acme-project:ref_type:branch:ref:main`"
}

CI/CD job 구성

HCP CLI를 사용해 외부 자격 증명을 자동으로 가져와 HCP 액세스 토큰으로 교환할 수 있어요. 이 안내는 hashicorp/hcp Docker 컨테이너를 사용하지만, HCP CLI가 설치된 런타임이라면 어디든 이 단계를 따를 수 있어요.

CI/CD job YAML 구성에 다음을 추가해요.

hcp:
  image: hashicorp/hcp
  id_tokens:
    WORKLOAD_IDENTITY_TOKEN:
      aud: <PROVIDER_NAME>
  script:
    - hcp iam workload-identity-providers create-cred-file <PROVIDER_NAME>
      --output-file=creds.json
      --source-env=WORKLOAD_IDENTITY_TOKEN
    - hcp auth login --cred-file=creds.json
    - MY_SECRET=$(hcp vault-secrets secrets open --app=my-app --format=json my-secret |
          jq -r '.static_version.value')

이 명령에는 HCP 계정에 특정한 다음 정보가 필요해요.

  • <PROVIDER_NAME>: iam/project/<PROJECT_ID>/service-principal/<SP_NAME>/workload-identity-provider/<PROVIDER_NAME> 형식으로 자격 증명을 교환할 워크로드 아이덴티티 제공자의 이름.

CI/CD 파이프라인에서 사용할 수 있는 명령에 대한 자세한 내용은 HCP CLI 명령 레퍼런스를 참고하세요.

더 알아보기 (Learn more)