Status: Beta

Geo 장애 조치에 대해서는 Geo 재해 복구를 참조하세요.

OpenBao 백업 및 복원#

OpenBao는 PostgreSQL의 별도 논리 데이터베이스에 데이터를 저장합니다. 장애 발생 후 시크릿을 복원할 수 있도록 이 데이터베이스를 정기적인 GitLab 백업과 함께 백업하세요.

OpenBao에 특화된 자세한 백업 및 복원 절차는 OpenBao 백업 문서를 참조하세요.

복구 키 관리#

복구 키 저장, 조회, 루트 토큰 생성 등 OpenBao 복구 키 관리에 대한 정보는 복구 키 관리를 참조하세요.

OpenBao 인증 복구#

JWT aud(audience) 클레임과 저장된 bound_audiences 값이 서로 달라진 경우 OpenBao 인증을 복구해야 할 수 있습니다.

저장된 시크릿이 보존되는 복구 키를 사용하여 인증을 재구성하는 방법을 먼저 시도하세요. 모든 저장된 시크릿이 삭제되므로 OpenBao 데이터 초기화는 최후의 수단으로만 사용하세요.

복구 키로 인증 재구성#

이 방법은 저장된 모든 시크릿을 보존하지만 복구 키가 필요합니다.

• 복구 키에서 임시 루트 토큰을 생성합니다. 절차는 복구 키에서 루트 토큰 생성을 참조하세요.

• 현재 인증 권한을 읽어 전체 구성을 확인합니다:

OPENBAO_POD=$(kubectl get pods -n gitlab -l app.kubernetes.io/name=openbao -o name | head -1)
kubectl exec -n gitlab "$OPENBAO_POD" -c openbao-server -- \
  sh -c "BAO_ADDR=http://127.0.0.1:8200 BAO_TOKEN=<root_token> bao read auth/gitlab_rails_jwt/role/app"

• 수정된 bound_audiences와 이전 단계에서 얻은 다른 모든 필드를 사용하여 권한을 다시 적용합니다. 업데이트 시 OpenBao는 생략된 필드를 기본값으로 초기화하므로 요청에 전체 구성이 포함되어야 합니다. 중요한 사항:

  role_type 필드는 기본값이 oidc이므로 role_type=jwt를 반드시 포함해야 합니다. 그렇지 않으면 권한이 손상됩니다.

  • claim_mappings 필드는 생략하면 빈 값으로 초기화되어 인가가 손상됩니다. 이전 단계에서 반환된 동일한 매핑을 포함하세요.

  bound_claims와 claim_mappings는 맵이므로 bao write <path> -로 표준 입력을 통해 JSON 형식으로 구성을 제공하세요. <your-domain>을 OpenBao 도메인으로 교체하고, claim_mappings 및 다른 값은 이전 단계에서 반환된 값으로 교체하세요:

kubectl exec -i -n gitlab "$OPENBAO_POD" -c openbao-server -- \
  sh -c "BAO_ADDR=http://127.0.0.1:8200 BAO_TOKEN=<root_token> bao write auth/gitlab_rails_jwt/role/app -" <<'JSON'
{
  "role_type": "jwt",
  "user_claim": "user_id",
  "bound_subject": "gitlab_secrets_manager",
  "bound_audiences": ["https://openbao.<your-domain>"],
  "token_policies": ["secrets_manager"],
  "bound_claims": {"secrets_manager_scope": "privileged"},
  "claim_mappings": {
    "user_id": "user_id",
    "project_id": "project_id",
    "group_id": "group_id",
    "namespace_id": "namespace_id",
    "correlation_id": "correlation_id"
  }
}
JSON

• 루트 토큰을 폐기합니다. 첫 번째 단계의 절차에 폐기 명령어가 포함되어 있습니다.

이 절차는 루트 수준 audience만 수정합니다. 도메인이 다른 보조 사이트로의 Geo 장애 조치는 지원되지 않습니다. 모든 프로젝트와 그룹에 대해 JWT 인증을 다시 프로비저닝해야 하기 때문입니다. 대신 기본 도메인이 승격된 보조 사이트를 가리키도록 DNS를 업데이트하세요. 자세한 내용은 Geo 배포를 참조하세요.

OpenBao 데이터 초기화#

WARNING: 이 절차는 OpenBao에 저장된 모든 시크릿을 영구적으로 삭제합니다. 완료 후 모든 Secrets Manager 시크릿을 다시 생성해야 합니다.

복구 키가 없고 bound_audiences가 JWT aud 클레임과 동기화되지 않아 인증이 실패하는 경우 OpenBao 데이터를 초기화하세요. 잘못된 URL로 OpenBao가 초기화된 경우 불일치가 발생할 수 있습니다. 초기화는 OpenBao 데이터베이스를 지워 OpenBao가 올바른 구성으로 자체 초기화되도록 합니다.

복구 키가 있는 경우 저장된 시크릿이 보존되는 복구 키로 인증 재구성을 대신 사용하세요.

시작하기 전에 구성에서 올바른 audience를 설정하세요:

• GitLab 18.10 이상의 경우 원하는 audience로 global.openbao.jwt_audience를 설정합니다.

• 이전 버전의 경우 OpenBao 외부 URL을 설정합니다. OpenBao는 자체 초기화 중에 이 URL에서 bound_audiences를 파생합니다.

OpenBao 데이터를 초기화하려면:

• OpenBao를 0개의 복제본으로 축소합니다:

kubectl -n gitlab scale deployment gitlab-openbao --replicas=0
kubectl -n gitlab rollout status deployment gitlab-openbao --timeout=60s

• toolbox Pod 이름을 가져옵니다:

kubectl -n gitlab get pods -l app=toolbox -o jsonpath='{.items[0].metadata.name}'

• OpenBao 스토리지 테이블을 초기화합니다. 플레이스홀더를 OpenBao 데이터베이스 비밀번호와 호스트로 교체하세요:

kubectl -n gitlab exec -ti <toolbox-pod-name> -- \
  env PGPASSWORD='<openbao_database_password>' \
  psql -h <postgres_host> -U openbao -d openbao \
  -c "TRUNCATE TABLE openbao_kv_store; TRUNCATE TABLE openbao_ha_locks;"

• 수정된 구성으로 OpenBao를 재배포합니다:

helm upgrade --install --version <chart-version> gitlab gitlab/gitlab \
  -n gitlab -f gitlab.yaml

• OpenBao를 다시 확장합니다. 차트를 재배포해도 수동으로 축소한 배포는 복원되지 않습니다:

kubectl -n gitlab scale deployment gitlab-openbao --replicas=2
kubectl -n gitlab rollout status deployment gitlab-openbao --timeout=120s

• OpenBao가 초기화되고 봉인 해제되었으며 올바른 audience를 사용하는지 확인합니다:

OPENBAO_POD=$(kubectl -n gitlab get pods -l app.kubernetes.io/name=openbao \
  -l openbao-active=true -o jsonpath='{.items[0].metadata.name}')
kubectl -n gitlab exec -ti "$OPENBAO_POD" -c openbao-server -- \
  sh -c "BAO_ADDR=http://127.0.0.1:8200 bao status"
kubectl -n gitlab get configmap gitlab-openbao-config -o yaml | grep bound_audiences

상태에는 Initialized true와 Sealed false가 표시되고, bound_audiences 값은 GitLab이 전송하는 audience와 일치합니다.