이 튜토리얼은 기존 CI/CD 시크릿 구성을 ID 토큰을 사용하도록 변환하는 방법을 보여줍니다.

CI_JOB_JWT 변수는 deprecated되었지만 ID 토큰으로 업데이트하려면 Vault와 함께 작동하도록 일부 중요한 구성 변경이 필요합니다. 잡이 몇 개 이상 있는 경우 한 번에 모두 변환하는 것은 어려운 작업입니다.

ID 토큰으로 마이그레이션하는 표준 방법은 없으므로 이 튜토리얼에는 기존 CI/CD 시크릿을 변환하는 두 가지 방법이 포함됩니다. 사용 사례에 가장 적합한 방법을 선택하세요:

1. Vault 구성 업데이트:
   • 방법 A: JWT 역할을 새 Vault 인증 방법으로 마이그레이션
     1. Vault에서 두 번째 JWT 인증 경로 만들기
     2. 새 인증 경로를 사용하도록 역할 재생성
   • 방법 B: 마이그레이션 기간 동안 역할에 iss 클레임 이동
     1. 각 역할에 bound_issuers 클레임 맵 추가
     2. 인증 방법에서 bound_issuers 클레임 제거
2. CI/CD 잡 업데이트

사전 조건#

이 튜토리얼은 GitLab CI/CD와 Vault에 익숙하다고 가정합니다.

따르려면 다음이 있어야 합니다:

• GitLab 16.0 이상을 실행하는 인스턴스 또는 GitLab.com 사용.
• 이미 사용 중인 Vault 서버.
• CI_JOB_JWT로 Vault에서 시크릿을 검색하는 CI/CD 잡.

다음 예시에서 다음을 교체합니다:

• vault.example.com을 Vault 서버의 URL로.
• gitlab.example.com을 GitLab 인스턴스의 URL로.
• jwt 또는 jwt_v2를 인증 방법 이름으로.

방법 A: JWT 역할을 새 Vault 인증 방법으로 마이그레이션#

이 방법은 기존 것과 병렬로 두 번째 JWT 인증 방법을 만듭니다. 이후 GitLab 통합에 사용되는 모든 Vault 역할이 이 새 인증 방법에서 재생성됩니다.

Vault에서 두 번째 JWT 인증 경로 만들기#

CI_JOB_JWT에서 ID 토큰으로의 전환의 일부로 Vault의 bound_issuer를 업데이트하여 https://를 포함해야 합니다:

$ vault write auth/jwt/config \
    oidc_discovery_url="https://gitlab.example.com" \
    bound_issuer="https://gitlab.example.com"

이 변경을 하면 CI_JOB_JWT를 사용하는 잡이 실패하기 시작합니다.

Vault에서 여러 인증 경로를 만들 수 있으며 이를 통해 중단 없이 프로젝트별 잡 단위로 ID 토큰으로 전환할 수 있습니다.

1. jwt_v2라는 이름으로 새 인증 경로를 구성하려면 다음을 실행합니다:

   vault auth enable -path jwt_v2 jwt
   

   다른 이름을 선택할 수 있지만 나머지 예시에서는 jwt_v2를 사용한다고 가정하므로 필요에 따라 예시를 업데이트합니다.

2. 인스턴스에 대한 새 인증 경로를 구성합니다:

   $ vault write auth/jwt_v2/config \
       oidc_discovery_url="https://gitlab.example.com" \
       bound_issuer="https://gitlab.example.com"
   

새 인증 경로를 사용하도록 역할 재생성#

역할은 특정 인증 경로에 바인딩되므로 각 잡에 대한 새 역할을 추가해야 합니다. 역할의 bound_audiences 매개변수는 JWT에 대상이 포함된 경우 필수이며 JWT의 관련 aud 클레임 중 하나 이상과 일치해야 합니다.

1. myproject-staging이라는 이름의 스테이징 역할을 재생성합니다:

   $ vault write auth/jwt_v2/role/myproject-staging - <<EOF
   {
     "role_type": "jwt",
     "policies": ["myproject-staging"],
     "token_explicit_max_ttl": 60,
     "user_claim": "user_email",
     "bound_audiences": ["https://vault.example.com"],
     "bound_claims": {
       "project_id": "22",
       "ref": "master",
       "ref_type": "branch"
     }
   }
   EOF
   

2. myproject-production이라는 이름의 프로덕션 역할을 재생성합니다:

   $ vault write auth/jwt_v2/role/myproject-production - <<EOF
   {
     "role_type": "jwt",
     "policies": ["myproject-production"],
     "token_explicit_max_ttl": 60,
     "user_claim": "user_email",
     "bound_audiences": ["https://vault.example.com"],
     "bound_claims_type": "glob",
     "bound_claims": {
       "project_id": "22",
       "ref_protected": "true",
       "ref_type": "branch",
       "ref": "auto-deploy-*"
     }
   }
   EOF
   

vault 명령에서 jwt를 jwt_v2로만 업데이트하면 됩니다. 역할 내부의 role_type은 변경하지 마세요.

방법 B: 마이그레이션 기간 동안 역할에 iss 클레임 이동#

이 방법은 Vault 관리자가 두 번째 JWT 인증 방법을 만들고 GitLab 관련 역할을 모두 재생성할 필요가 없습니다.

각 역할에 bound_issuers 클레임 맵 추가#

Vault는 JWT 인증 방법 수준에서 여러 iss 클레임을 허용하지 않습니다. 이 수준의 bound_issuer 지시문은 단일 값만 허용하기 때문입니다. 그러나 bound_claims 맵 구성 지시문을 사용하여 역할 수준에서 여러 클레임을 구성할 수 있습니다.

이 방법을 사용하면 iss 클레임 유효성 검사에 여러 옵션을 Vault에 제공할 수 있습니다. 이는 id_tokens와 함께 제공되는 https:// 접두사가 있는 GitLab 인스턴스 호스트 이름 클레임과 이전의 접두사 없는 클레임을 모두 지원합니다.

필요한 역할에 bound_claims 구성을 추가하려면 다음을 실행합니다:

$ vault write auth/jwt/role/myproject-staging - <<EOF
{
  "role_type": "jwt",
  "policies": ["myproject-staging"],
  "token_explicit_max_ttl": 60,
  "user_claim": "user_email",
  "bound_audiences": ["https://vault.example.com"],
  "bound_claims": {
    "iss": [
      "https://gitlab.example.com",
      "gitlab.example.com"
    ],
    "project_id": "22",
    "ref": "master",
    "ref_type": "branch"
  }
}
EOF

bound_claims 섹션을 제외한 기존 역할 구성을 변경할 필요가 없습니다. 이전에 표시된 대로 iss 구성을 추가하여 Vault가 이 역할에 대해 접두사가 있는 iss 클레임과 접두사가 없는 iss 클레임을 모두 수락하도록 합니다.

다음 단계로 진행하기 전에 GitLab 통합에 사용되는 모든 JWT 역할에 이 변경 사항을 적용해야 합니다.

모든 프로젝트가 마이그레이션되고 CI_JOB_JWT 및 ID 토큰에 대한 병렬 지원이 더 이상 필요하지 않은 경우 원하는 경우 인증 방법에서 역할로의 iss 클레임 유효성 검사 마이그레이션을 되돌릴 수 있습니다.

인증 방법에서 bound_issuers 클레임 제거#

모든 역할이 bound_claims.iss 클레임으로 업데이트된 후 이 유효성 검사에 대한 인증 방법 수준 구성을 제거할 수 있습니다:

$ vault write auth/jwt/config \
    oidc_discovery_url="https://gitlab.example.com" \
    bound_issuer=""

bound_issuer 지시문을 빈 문자열로 설정하면 인증 방법 수준에서 발급자 유효성 검사가 제거됩니다. 그러나 이 유효성 검사가 이제 역할 수준에 있으므로 구성은 여전히 안전합니다.

CI/CD 잡 업데이트#

Vault에는 두 가지 다른 KV 시크릿 엔진이 있으며 사용 중인 버전이 CI/CD에서 시크릿을 정의하는 방법에 영향을 미칩니다.

HashiCorp 지원 포털의 Which Version is my Vault KV Mount? 문서를 확인하여 Vault 서버를 확인하세요.

또한 필요한 경우 다음에 대한 CI/CD 문서를 검토할 수 있습니다:

• secrets:
• id_tokens:

다음 예시는 secret/myproject/staging/db의 password 필드에 작성된 스테이징 데이터베이스 비밀번호를 얻는 방법을 보여줍니다.

VAULT_AUTH_PATH 변수의 값은 사용한 마이그레이션 방법에 따라 다릅니다:

• 방법 A (JWT 역할을 새 Vault 인증 방법으로 마이그레이션): jwt_v2 사용.
• 방법 B (마이그레이션 기간 동안 역할에 iss 클레임 이동): jwt 사용.

KV 시크릿 엔진 v1#

secrets:vault 키워드는 기본적으로 KV 마운트의 v2를 사용하므로 v1 엔진을 사용하도록 잡을 명시적으로 구성해야 합니다:

job:
  variables:
    VAULT_SERVER_URL: https://vault.example.com
    VAULT_AUTH_PATH: jwt_v2  # 방법 B를 사용한 경우 "jwt"
    VAULT_AUTH_ROLE: myproject-staging
  id_tokens:
    VAULT_ID_TOKEN:
      aud: https://vault.example.com
  secrets:
    PASSWORD:
      vault:
        engine:
          name: kv-v1
          path: secret
        field: password
        path: myproject/staging/db
      file: false

VAULT_SERVER_URL 및 VAULT_AUTH_PATH는 원하는 경우 프로젝트 또는 그룹 CI/CD 변수로 정의할 수 있습니다.

secrets:file은 ID 토큰이 기본적으로 파일에 시크릿을 배치하고 이전 동작을 일치시키기 위해 일반 변수로 작동해야 하기 때문에 false로 설정됩니다.

KV 시크릿 엔진 v2#

v2 엔진에 사용할 수 있는 두 가지 형식이 있습니다.

긴 형식:

job:
  variables:
    VAULT_SERVER_URL: https://vault.example.com
    VAULT_AUTH_PATH: jwt_v2  # 방법 B를 사용한 경우 "jwt"
    VAULT_AUTH_ROLE: myproject-staging
  id_tokens:
    VAULT_ID_TOKEN:
      aud: https://vault.example.com
  secrets:
    PASSWORD:
      vault:
        engine:
          name: kv-v2
          path: secret
        field: password
        path: myproject/staging/db
      file: false

이것은 v1 엔진 예시와 동일하지만 엔진과 일치하도록 secrets:vault:engine:name:이 kv-v2로 설정됩니다.

짧은 형식도 사용할 수 있습니다:

job:
  variables:
    VAULT_SERVER_URL: https://vault.example.com
    VAULT_AUTH_PATH: jwt_v2  # 방법 B를 사용한 경우 "jwt"
    VAULT_AUTH_ROLE: myproject-staging
  id_tokens:
    VAULT_ID_TOKEN:
      aud: https://vault.example.com
  secrets:
      PASSWORD:
        vault: myproject/staging/db/password@secret
        file: false

업데이트된 CI/CD 구성을 커밋하면 잡이 ID 토큰으로 시크릿을 가져옵니다. 축하합니다!

방법 B를 사용하여 모든 프로젝트가 ID 토큰으로 시크릿을 가져오도록 마이그레이션한 경우 이제 원하는 경우 iss 클레임 유효성 검사를 인증 방법 구성으로 다시 이동할 수 있습니다.