CI에서 외부 Secrets 사용하기

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

GitLab 13.4 및 GitLab Runner 13.4에 도입됨.
file 설정은 GitLab 14.1 및 GitLab Runner 14.1에 도입됨.
VAULT_NAMESPACE 설정은 GitLab 14.9 및 GitLab Runner 14.9에 도입됨.

Secrets는 CI 작업이 완료되기 위해 필요한 민감한 정보를 나타냅니다. 이러한 민감한 정보는 API 토큰, 데이터베이스 자격 증명 또는 개인 키와 같은 항목일 수 있습니다. Secrets는 Secrets 제공업체에서 소스를 제공합니다.

항상 작업에 제시되는 CI/CD 변수와 달리 Secrets는 작업에서 명시적으로 요구되어야 합니다. 구문에 대한 자세한 내용은 GitLab CI/CD 파이프라인 구성 참조를 참조하십시오.

GitLab은 다음의 Secrets 관리 제공업체를 지원합니다:

GitLab은 첫 번째로 지원되는 제공자로 HashiCorp Vault와 첫 번째로 지원되는 Secrets 엔진인 KV-V2을 선택했습니다.

Vault와 인증하려면 ID 토큰을 사용하십시오. HashiCorp Vault와의 인증 및 Secrets 읽기 튜토리얼에는 ID 토큰으로의 인증에 대한 자세한 내용이 있습니다.

HashiCorp Vault에서 생성된 JWT를 제공하여 CI 작업에 제공하기 전에, Vault 서버를 구성해야 합니다.

GitLab 및 Hashicorp Vault의 흐름은 다음 다이어그램에 요약되어 있습니다:

Vault 및 Secrets를 구성합니다.
JWT를 생성하고 CI 작업에 제공합니다.
Runner가 HashiCorp Vault에 연락하여 JWT를 사용하여 인증합니다.
HashiCorp Vault가 JWT를 확인합니다.
HashiCorp Vault가 바인딩된 클레임을 확인하고 정책을 첨부합니다.
HashiCorp Vault가 토큰을 반환합니다.
Runner가 HashiCorp Vault에서 Secrets를 읽습니다.

이 기능에 대한 버전으로 HashiCorp Vault와의 인증 및 Secrets 읽기 튜토리얼을 참조하십시오. 이 기능은 모든 구독 수준에서 사용할 수 있으며, Vault에 Secrets를 작성하고 삭제하는 기능을 지원하며, 여러 Secrets 엔진을 지원합니다.

Vault 서버 구성

Vault 서버를 구성하려면 다음을 수행하십시오:

Vault 서버가 1.2.0 이상인지 확인하십시오.
다음 명령을 실행하여 인증 방법을 활성화합니다. 이 명령은 Vault 서버에 귀하의 GitLab 인스턴스에 대한 OIDC Discovery URL을 제공하여 Vault가 인증 중에 JSON Web Token(JWT)을 확인하는 데 필요한 공개 서명 키를 가져올 수 있게 합니다:
```
$ vault auth enable jwt
   
$ vault write auth/jwt/config \
  oidc_discovery_url="https://gitlab.example.com" \
  bound_issuer="gitlab.example.com"
```
Vault 서버에서 특정 경로 및 작업에 대한 액세스 허용 또는 금지하는 정책을 구성하십시오. 이 예시에서는 프로덕션 환경에 필요한 Secrets 세트에 대한 읽기 액세스를 제공합니다:
```
vault policy write myproject-production - <<EOF
# 'ops/data/production/*' 경로에 대한 읽기 전용 권한
   
path "ops/data/production/*" {
  capabilities = [ "read" ]
}
EOF
```
Vault 서버에 프로젝트 또는 네임스페이스에 권한을 제한하는 역할을 구성하십시오. 이 페이지의 Vault 서버 역할 구성에 설명된 대로 구성합니다.
Vault 서버에 대한 다음의 CI/CD 변수를 만드십시오:
- VAULT_SERVER_URL - https://vault.example.com:8200와 같은 Vault 서버의 URL입니다. 필수 사항입니다.
- VAULT_AUTH_ROLE - 선택 사항입니다. 인증을 시도할 때 사용할 역할입니다. 역할이 지정되어 있지 않으면 Vault는 인증 방법이 구성될 때 기본 역할을 사용합니다.
- VAULT_AUTH_PATH - 선택 사항입니다. 인증 방법이 마운트된 경로입니다. 기본값은 jwt입니다.
- VAULT_NAMESPACE - 선택 사항입니다. Secrets 읽기 및 인증에 사용할 Vault Enterprise 네임스페이스입니다. 네임스페이스가 지정되어 있지 않으면 Vault는 root(“/”) 네임스페이스를 사용합니다. Vault Open Source에서 이 설정은 무시됩니다.
이러한 값을 UI로 제공하는 지원은 이 이슈에서 추적됩니다.

CI 작업에서 Vault Secrets 사용하기

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

GitLab 13.4 및 GitLab Runner 13.4에 도입됨.

Vault 서버를 구성한 후, vault 키워드를 사용하여 Vault에 저장된 Secrets를 정의하여 사용할 수 있습니다:

job_using_vault:
  id_tokens:
    VAULT_ID_TOKEN:
      aud: https://gitlab.com
  secrets:
    DATABASE_PASSWORD:
      vault: production/db/password@ops  # secret `ops/data/production/db`에 해당하며, 필드는 `password`입니다.
      token: $VAULT_ID_TOKEN

이 예에서:

production/db - Secrets입니다.
password - 필드입니다.
ops - Secrets 엔진이 마운트된 경로입니다.

GitLab이 Vault로부터 Secrets를 가져오면 해당 값을 임시 파일에 저장합니다. 이 파일의 경로는 DATABASE_PASSWORD라는 CI/CD 변수에 저장되며, 이는 file 유형의 변수와 유사합니다.

기본 동작을 덮어쓰려면 file 옵션을 명시적으로 설정하십시오:

secrets:
  id_tokens:
    VAULT_ID_TOKEN:
      aud: https://gitlab.com
  DATABASE_PASSWORD:
    vault: production/db/password@ops
    file: false
    token: $VAULT_ID_TOKEN

이 예에서 Secrets 값은 해당 값을 보유하는 파일을 가리키는 대신 DATABASE_PASSWORD 변수에 직접적으로 넣습니다.

지원되는 구문에 대한 자세한 내용은 .gitlab-ci.yml 구문 참조를 참조하십시오.

Vault 서버 역할 구성

CI 작업이 인증을 시도할 때 역할을 지정합니다. 역할을 사용하여 서로 다른 정책을 그룹화할 수 있습니다. 인증이 성공하면 이러한 정책은 생성된 Vault 토큰에 첨부됩니다.

Bound claims는 미리 정의된 값으로, JWT 클레임과 일치시킵니다. 바운드 클레임을 사용하면 특정 GitLab 사용자, 특정 프로젝트 또는 특정 Git 레퍼런스에서 실행 중인 작업에 대한 액세스를 제한할 수 있습니다. 필요한 만큼의 바운드 클레임을 가질 수 있지만, 모두 일치해야만 인증이 성공합니다.

GitLab 사용자 역할과 protected branches와 같은 GitLab 기능과 결합하여 이러한 규칙을 특정 사용 사례에 맞게 조정할 수 있습니다. 이 예에서는 인증이 production 릴리스에 사용된 패턴과 일치하는 보호된 태그에서 실행 중인 작업에 대해서만 허용됩니다.

$ vault write auth/jwt/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": "42",
    "ref_protected": "true",
    "ref_type": "tag",
    "ref": "auto-deploy-*"
  }
}
EOF

제공된 클레임 중 하나를 사용하여 항상 역할을 프로젝트 또는 네임스페이스로 제한하세요. 이러한 제한이 없으면 이 GitLab 인스턴스에서 생성된 모든 JWT가이 역할을 사용하여 인증하는 데 허용될 수 있습니다.

ID 토큰 JWT 클레임의 전체 디렉터리은 How It Works 섹션의 HashiCorp Vault로의 인증 및 비밀 읽기 튜토리얼의 문서에서 확인할 수 있습니다.

또한 결과 Vault 토큰에 대해 시간 제한, IP 주소 범위 및 사용 횟수와 같은 일부 속성을 지정할 수 있습니다. 옵션의 전체 디렉터리은 Vault의 역할 생성에 관한 문서에서 확인할 수 있습니다.

자체 서명 Vault 서버 사용

Vault 서버가 자체 서명된 인증서를 사용하는 경우, 작업 로그에 다음 오류가 표시됩니다:

ERROR: Job failed (system failure): resolving secrets: initializing Vault service: preparing authenticated client: checking Vault server health: Get https://vault.example.com:8000/v1/sys/health?drsecondarycode=299&performancestandbycode=299&sealedcode=299&standbycode=299&uninitcode=299: x509: certificate signed by unknown authority

이 오류를 해결하기 위해 두 가지 옵션이 있습니다:

자체 서명된 인증서를 GitLab Runner 서버의 CA 리포지터리에 추가합니다. Helm 차트를 사용하여 GitLab Runner를 배포한 경우, 자체 GitLab Runner 이미지를 만들어야 합니다.
VAULT_CACERT 환경 변수를 사용하여 GitLab Runner가 인증서를 신뢰하도록 구성합니다:
- GitLab Runner를 관리하기 위해 systemd를 사용하는 경우, GitLab Runner를 위한 환경 변수 추가 방법을 참조하십시오.
- Helm 차트를 사용하여 GitLab Runner를 배포한 경우:
  1. GitLab에 액세스하기 위한 사용자 정의 인증서 제공 및 GitLab 대신 Vault 서버에 대한 인증서를 추가해야 합니다. GitLab 인스턴스도 자체 서명된 인증서를 사용하는 경우, 동일한 Secret에 두 개를 추가할 수 있어야 합니다.
  2. 다음 줄을 values.yaml 파일에 추가하십시오:
    ## <SECRET_NAME> 및 <VAULT_CERTIFICATE>를 실제 사용한 값으로 바꿉니다. certsSecretName: <SECRET_NAME> envVars: - name: VAULT_CACERT value: "/home/gitlab-runner/.gitlab-runner/certs/<VAULT_CERTIFICATE>"

CI에서 외부 Secrets 사용하기

Vault 서버 구성

CI 작업에서 Vault Secrets 사용하기

Vault 서버 역할 구성

자체 서명 Vault 서버 사용

도움말

기능 사용 가능성과 제품 평가판

도움받기