클라우드 서비스 연결하기

클라우드 서비스 연결하기 (Connect to cloud services)

빌드와 배포 job이 클라우드 자격 증명과 서비스에 접근할 수 있게 하려면, GitLab CI/CD는 OpenID Connect (OIDC)를 지원해요. 이전에는 비밀(secret)을 프로젝트에 저장하거나 GitLab Runner 인스턴스에 권한을 부여해서 빌드·배포를 했지만, 이제는 더 안전한 방식으로 접근을 관리할 수 있습니다.

출처: 문서

본문

• 티어(Tier): Free, Premium, Ultimate
• 제공 방식(Offering): GitLab.com, GitLab Self-Managed, GitLab Dedicated

CI_JOB_JWT와 CI_JOB_JWT_V2는 GitLab 17.0에서 제거되었어요. 대신 ID 토큰을 사용하세요.

GitLab CI/CD는 OpenID Connect (OIDC)를 지원해서 빌드와 배포 job이 클라우드 자격 증명과 서비스에 접근할 수 있게 해줍니다. 과거에는 팀이 비밀을 프로젝트에 저장하거나 GitLab Runner 인스턴스에 권한을 적용해서 빌드·배포를 했어요. OIDC를 지원하는 ID 토큰은 CI/CD job에서 구성할 수 있어서, 확장 가능하고 최소 권한(least-privilege) 원칙을 따르는 보안 접근 방식을 쓸 수 있습니다.

전제 조건

• GitLab 계정.
• 권한 부여를 구성하고 역할을 만들 OIDC를 지원하는 클라우드 제공자에 대한 접근 권한.

ID 토큰은 OIDC를 지원하는 클라우드 제공자를 지원해요:

• AWS
• Azure
• GCP
• HashiCorp Vault

OIDC를 구성하면 모든 파이프라인에 대해 대상 환경에 대한 JWT 토큰 접근이 활성화돼요. 파이프라인에 OIDC를 구성할 때는 추가된 접근 권한에 초점을 맞춰 소프트웨어 공급망 보안 검토를 완료해야 합니다. 공급망 공격에 대한 자세한 내용은 DevOps 플랫폼이 공급망 공격 방어에 어떻게 도움이 되는지를 참고하세요.

클라우드 서비스에 대한 OIDC 연결은 다음과 같은 이점을 줘요:

• GitLab 그룹이나 프로젝트에 비밀을 저장할 필요가 없어져요. 임시 자격 증명을 OIDC를 통해 클라우드 제공자에서 가져올 수 있어요.
• 그룹, 프로젝트, 브랜치, 태그를 포함하는 세밀한 GitLab 조건부(conditional)로 클라우드 리소스에 임시 access를 제공해요.
• 환경에 대한 조건부 접근으로 CI/CD job에서 직무 분리(separation of duties)를 정의할 수 있어요. 과거에는 스테이징이나 프로덕션 환경에만 접근하는 전용 GitLab Runner로 앱을 배포했을 수 있어요. 이는 각 머신이 전용 권한을 가지면서 Runner가 난립(Runner sprawl)하는 원인이 됐습니다.
• 인스턴스 러너가 여러 클라우드 계정에 안전하게 접근할 수 있게 해줘요. 접근은 파이프라인을 실행하는 사용자에 특화된 JWT 토큰에 의해 결정됩니다.
• 기본적으로 임시 자격 증명을 가져오므로 비밀을 회전(rotate)하는 로직을 만들 필요가 없어져요.

클라우드 서비스를 위한 ID 토큰 인증

각 job은 ID 토큰으로 구성할 수 있고, ID 토큰은 토큰 페이로드를 담은 CI/CD 변수로 제공돼요. 이 JWT는 AWS, Azure, GCP, Vault 같은 OIDC 지원 클라우드 제공자와 인증하는 데 사용할 수 있습니다.

권한 부여 워크플로

%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
accTitle: Authorization workflow
accDescr: The flow of authorization requests between GitLab and a cloud provider.

    participant GitLab
    Note right of Cloud: Create OIDC identity provider
    Note right of Cloud: Create role with conditionals
    Note left of GitLab: CI/CD job with ID token
    GitLab->>+Cloud: Call cloud API with ID token
    Note right of Cloud: Decode & verify JWT with public key (https://gitlab.com/oauth/discovery/keys)
    Note right of Cloud: Validate audience defined in OIDC
    Note right of Cloud: Validate conditional (sub, aud) role
    Note right of Cloud: Generate credential or fetch secret
    Cloud->>GitLab: Return temporary credential
    Note left of GitLab: Perform operation

1. 클라우드(예: AWS, Azure, GCP, Vault)에 OIDC identity provider를 만들어요.
2. 그룹, 프로젝트, 브랜치, 태그로 필터링하는 조건부 역할을 클라우드 서비스에 만들어요.
3. CI/CD job은 JWT 토큰인 ID 토큰을 포함해요. 이 토큰으로 클라우드 API에 권한 부여를 할 수 있어요.
4. 클라우드가 토큰을 검증하고, 페이로드에서 조건부 역할을 확인한 뒤 임시 자격 증명을 반환해요.

OIDC 클레임으로 조건부 역할 구성하기

조건부 역할을 구성할 때는 클라우드 제공자가 지원하는 경우, sub 같은 경로 기반 클레임과 함께 namespace_id나 project_id 같은 안정적이고 고유한 식별자를 포함하세요. 이 식별자들은 경로와 무관하므로, 이들을 참조하는 신뢰 정책(trust policy)은 그룹이나 프로젝트 이름 변경 같은 경로 변화의 영향을 받지 않아요.

이러한 조건 키에 대한 지원은 클라우드 제공자와 GitLab 제공 방식에 따라 달라져요. 예를 들어 AWS는 gitlab.com OIDC identity provider에서만 namespace_id와 project_id를 지원해요. 제공자 예시는 AWS에서 OpenID Connect 구성하기를 참고하세요.

GitLab과 OIDC 사이의 신뢰를 구성하려면 JWT를 검사하는 조건부 역할을 클라우드 제공자에 만들어야 해요. 이 조건은 JWT에 대해 검증되며, audience와 subject 두 클레임에 대해 신뢰가 만들어집니다.

• Audience 또는 aud: ID 토큰의 일부로 구성돼요: job_needing_oidc_auth: id_tokens: OIDC_TOKEN: aud: https://oidc.provider.com script: - echo $OIDC_TOKEN
• Subject 또는 sub: 그룹, 프로젝트, 브랜치, 태그를 포함하는 GitLab CI/CD 워크플로를 설명하는 메타데이터의 연결(concatenation). sub 필드는 기본적으로 다음 형식이에요: - project_path:{group}/{project}:ref_type:{type}:ref:{branch_name}

subject로 프로젝트 ID 사용하기

클라우드 신뢰 정책을 변경 불가능한(immutable) 식별자에 바인딩하려면 sub 클레임의 첫 번째 구성 요소로 project_id를 사용하세요. 이 옵션을 쓰면 프로젝트가 이름 변경되거나 이동되어도 클라우드 접근이 안정적으로 유지돼요.

이를 활성화하려면 프로젝트 API 엔드포인트 API로 ci_id_token_sub_claim_components를 ["project_id", "ref_type", "ref"] 같은 값으로 설정하세요. 그러면 sub 필드는 다음 형식이 됩니다:

• project_id:{id}:ref_type:{type}:ref:{branch_name}

클라우드 제공자와 OIDC 권한 부여

클라우드 제공자와 연결하려면 다음 튜토리얼을 참고하세요:

• AWS에서 OpenID Connect 구성하기
• Azure에서 OpenID Connect 구성하기
• Google Cloud에서 OpenID Connect 구성하기

더 알아보기 (Learn more)

• ID 토큰 인증
• AWS 설정