GitLab CI/CD에서 Azure Key Vault 시크릿 사용하기

Azure Key Vault에 저장된 시크릿을 GitLab CI/CD 파이프라인에서 사용하는 방법을 설명하는 문서예요. Azure AD 애플리케이션과 OIDC 인증을 이용해 Key Vault 시크릿을 읽는 방식을 코드 예시와 함께 옆에서 설명해 주는 방식으로 정리했어요.

여러 시크릿을 사용하는 방법과 함께, JWT 토큰 오류나 권한 오류 같은 자주 겪는 문제와 그 해결책도 함께 살펴볼 수 있어요.

출처: 문서

본문

Azure Key Vault에 저장된 시크릿을 GitLab CI/CD 파이프라인에서 사용할 수 있어요.

전제 조건:

Azure에 Key Vault가 있어야 해요.
- 여러분의 IAM 사용자에게 Key Vault에 할당된 리소스 그룹에 대한 Key Vault Administrator 역할 할당이 부여되어야 해요. 그렇지 않으면 Key Vault 안에 시크릿을 만들 수 없어요.
임시 자격 증명을 가져오려면 Azure에서 OpenID Connect 구성하세요. 이 단계에는 Key Vault 접근을 위한 Azure AD 애플리케이션을 만드는 방법도 포함돼요.
Vault 서버 정보를 제공하기 위해 프로젝트에 CI/CD 변수를 추가하세요.
- AZURE_KEY_VAULT_SERVER_URL: Azure Key Vault 서버의 URL, 예: https://vault.example.com.
- AZURE_CLIENT_ID: Azure 애플리케이션의 클라이언트 ID.
- AZURE_TENANT_ID: Azure 애플리케이션의 테넌트 ID.

CI/CD 작업에서 Azure Key Vault 시크릿 사용하기

azure_key_vault 키워드로 정의해 Azure Key Vault에 저장된 시크릿을 작업에서 사용할 수 있어요.

job:
  id_tokens:
    AZURE_JWT:
      aud: 'https://gitlab.com'
  secrets:
    DATABASE_PASSWORD:
      token: $AZURE_JWT
      azure_key_vault:
        name: 'DATABASE-PASSWORD'
        version: '00000000000000000000000000000000'

같은 작업에서 Azure Key Vault의 여러 시크릿을 사용하려면 secrets 키워드 아래에 각 시크릿을 정의하세요.

job:
  id_tokens:
    AZURE_JWT:
      aud: 'https://gitlab.com'
  secrets:
    REDIS_PASSWORD:
      token: $AZURE_JWT
      azure_key_vault:
        name: 'REDIS-PASSWORD'
        version: '00000000000000000000000000000000'
    DATABASE_PASSWORD:
      token: $AZURE_JWT
      azure_key_vault:
        name: 'DATABASE-PASSWORD'
        version: '00000000000000000000000000000000'

이 예시들에서:

aud는 연합 자격 증명을 만들 때 사용된 오디언스와 일치해야 하는 오디언스예요.
name은 Azure Key Vault의 시크릿 이름이에요.
version은 Azure Key Vault의 시크릿 버전이에요. 버전은 대시 없는 GUID로 생성되며 Azure Key Vault 시크릿 페이지에서 찾을 수 있어요.

GitLab은 Azure Key Vault에서 시크릿을 가져와 값을 임시 파일에 저장해요. 이 파일의 경로는 secrets 아래에 정의한 이름(예: DATABASE_PASSWORD 또는 REDIS_PASSWORD)의 CI/CD 변수에 저장되며, 파일 형식 CI/CD 변수와 유사해요.

문제 해결

Azure로 OIDC를 설정할 때 일반적인 문제는 Azure용 OIDC 문제 해결을 참고하세요.

`JWT token is invalid or malformed` 메시지

Azure Key Vault에서 시크릿을 가져올 때 이 오류를 받을 수 있어요.

RESPONSE 400 Bad Request
AADSTS50027: JWT token is invalid or malformed.

이 오류는 GitLab Runner에서 JWT 토큰이 올바르게 구문 분석되지 않는 알려진 이슈로 인해 발생해요. 해결하려면 러너를 지원되는 버전으로 업그레이드하세요.

`Caller is not authorized to perform action on resource` 메시지

Azure Key Vault에서 시크릿을 가져올 때 이 오류를 받을 수 있어요.

RESPONSE 403: 403 Forbidden
ERROR CODE: Forbidden
Caller is not authorized to perform action on resource.\r\nIf role assignments, deny assignments or role definitions were changed recently, please observe propagation time.
ForbiddenByRbac

Azure Key Vault가 RBAC를 사용한다면 Azure AD 애플리케이션에 Key Vault Secrets User 역할 할당을 추가해야 해요.

예를 들어:

appId=$(az ad app list --display-name gitlab-oidc --query '[0].appId' -otsv)
az role assignment create --assignee $appId --role "Key Vault Secrets User" --scope /subscriptions/

구독 ID는 다음에서 찾을 수 있어요.

Azure 포털.
Azure CLI.

`The secrets provider can not be found. Check your CI/CD variables and try again.` 메시지

Azure Key Vault에 접근하도록 구성된 작업을 시작하려 할 때 이 오류를 받을 수 있어요.

The secrets provider can not be found. Check your CI/CD variables and try again.

필요한 변수 중 하나 이상이 정의되지 않아 작업을 만들 수 없어요.

AZURE_KEY_VAULT_SERVER_URL
AZURE_CLIENT_ID
AZURE_TENANT_ID

더 알아보기

Azure와의 OIDC 설정 방법은 Azure용 OIDC 문서에서 자세히 다루고 있어요. GitLab CI/CD에서 다른 시크릿 관리자를 사용하는 방법도 참고하려면 외부 시크릿 사용 문서를 함께 보시면 좋아요.

GitLab CI/CD에서 Azure Key Vault 시크릿 사용하기