- 전제 조건
- 방법 A: 기존 Vault 인증 방법에서 JWT 역할을 새로운 Vault 인증 방법으로 마이그레이션
-
방법 B: 마이그레이션 창을 위해
iss클레임을 역할로 이동 - CI/CD 작업 업데이트
튜토리얼: HashiCorp Vault 구성 업데이트하여 ID 토큰 사용
이 튜토리얼은 기존 CI/CD 시크릿 구성을 ID 토큰을 사용하도록 변환하는 방법을 보여줍니다.
CI_JOB_JWT 변수는 사용이 중단되었지만, ID 토큰으로 업데이트하려면 Vault와 함께 작동하도록 중요한 구성 변경이 필요합니다. 몇 가지 작업 이상이 있는 경우, 한꺼번에 모두 변환하는 것은 어려운 작업입니다.
ID 토큰으로 이관하는 표준 메소드는 없지만, 이 튜토리얼에는 기존 CI/CD 시크릿을 변환하는 두 가지 방법이 포함되어 있습니다. 사용 사례에 가장 적합한 방법을 선택하세요:
- Vault 구성 업데이트:
- 방법 A: 기존 Vault 인증 방법에서 JWT 역할을 새로운 Vault 인증 방법으로 마이그레이션
- 방법 B: 마이그레이션 창을 위해
iss클레임을 역할로 이동
- CI/CD Jobs 업데이트
전제 조건
이 튜토리얼은 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: 기존 Vault 인증 방법에서 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에서 여러 인증 경로를 만들 수 있으며, 이를 통해 단계별로 IT 토큰으로 전환할 수 있습니다.
-
이름이
jwt_v2인 새로운 인증 경로를 구성하려면 다음을 실행하세요:vault auth enable -path jwt_v2 jwt다른 이름을 선택할 수 있지만, 이 예제의 나머지 부분은
jwt_v2를 사용했다고 가정하므로 필요에 따라 예제를 업데이트하세요. -
인스턴스에 새로운 인증 경로를 구성하세요:
$ vault write auth/jwt_v2/config \ oidc_discovery_url="https://gitlab.example.com" \ bound_issuer="https://gitlab.example.com"
새로운 인증 경로를 사용하도록 역할 다시 생성
역할은 특정 인증 경로에 바인딩되므로 각 작업에 대해 새로운 역할을 추가해야 합니다.
-
스테이징용
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_claims": { "project_id": "22", "ref": "master", "ref_type": "branch" } } EOF -
프로덕션용
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_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 맵 구성 지시문을 사용하여 역할 레벨에서 구성할 수 있습니다.
이 방법을 사용하면 Vault에 iss 클레임 유효성 검사를 위한 여러 옵션을 제공할 수 있습니다. 이 방법으로는 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_claims": {
"iss": [
"https://gitlab.example.com",
"gitlab.example.com"
],
"project_id": "22",
"ref": "master",
"ref_type": "branch"
}
}
EOF
기존 역할 구성을 변경하지 않고도 bound_claims 섹션을 제외한 모든 역할 구성을 업데이트해야 합니다.
위의 예제와 같이 iss 구성을 추가하여 해당 역할에서 Vault가 접두사 및 접두사 없는 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 Secrets Engines가 있으며 사용 중인 버전에 따라 CI/CD에서 비밀을 정의하는 방법이 영향을 받습니다.
Vault 서버를 확인하려면 HashiCorp의 지원 포털에있는 어떤 버전의 Vault KV Mount를 사용 중 입니까? 글을 확인하세요.
또 필요한 경우 다음을 참고하여 CI/CD 문서를 검토할 수 있습니다.
다음 예제는 secret/myproject/staging/db의 password 필드에 작성된 스테이징 데이터베이스 암호를 얻는 방법을 보여줍니다.
VAULT_AUTH_PATH 변수의 값은 사용한 마이그레이션 방법에 따라 다릅니다.
- 방법 A (JWT 역할을 새로운 Vault 인증 방법으로 마이그레이션):
jwt_v2사용 - 방법 B (
iss클레임을 마이그레이션 창에 대상 역할로 이동):jwt사용
KV Secrets Engine v1
secrets:vault 키워드는 KV Mount의 기본값이 v2이므로 작업을 v1 엔진을 사용하도록 명시적으로 구성해야합니다.
job:
variables:
VAULT_SERVER_URL: https://vault.example.com
VAULT_AUTH_PATH: jwt_v2 # 또는 "jwt" (방법 B를 사용한 경우)
VAULT_AUTH_ROLE: myproject-staging
id_tokens:
VAULT_ID_TOKEN:
aud: https://gitlab.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 변수로 정의할 수 있습니다.
우리는 ID 토큰이 기본적으로 파일에 비밀을 놓지만 이것이 이전 동작과 일치하도록 일반 변수처럼 작동해야 하기 때문에 secrets:file:false를 사용합니다.
KV Secrets Engine v2
v2 엔진에는 두 가지 형식을 사용할 수 있습니다.
긴 형식:
job:
variables:
VAULT_SERVER_URL: https://vault.example.com
VAULT_AUTH_PATH: jwt_v2 # 또는 "jwt" (방법 B를 사용한 경우)
VAULT_AUTH_ROLE: myproject-staging
id_tokens:
VAULT_ID_TOKEN:
aud: https://gitlab.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 # 또는 "jwt" (방법 B를 사용한 경우)
VAULT_AUTH_ROLE: myproject-staging
id_tokens:
VAULT_ID_TOKEN:
aud: https://gitlab.example.com
secrets:
PASSWORD:
vault: myproject/staging/db/password@secret
file: false
업데이트된 CI/CD 구성을 커밋한 후에는 작업이 ID 토큰으로 비밀을 가져올 것입니다. 축하합니다!
모든 프로젝트를 ID 토큰으로 비밀을 가져오도록 마이그레이션했고 마이그레이션에 방법 B를 사용한 경우, 원하는 경우 이제 iss 클레임 유효성 검사를 다시 인증 방법의 구성으로 이동할 수 있습니다.
도움말