OpenBao 유지 관리
GitLab v19.6Offering: GitLab Self-Managed
요약
Geo 장애 조치에 대해서는 Geo 재해 복구를 참고합니다. OpenBao는 PostgreSQL의 별도 논리 데이터베이스에 데이터를 저장합니다. OpenBao에 특화된 자세한 백업 및 복원 절차는 OpenBao 백업 문서를 참고합니다.
Geo 장애 조치에 대해서는 Geo 재해 복구를 참고합니다.
OpenBao 백업 및 복원#
OpenBao는 PostgreSQL의 별도 논리 데이터베이스에 데이터를 저장합니다. 장애 발생 후 시크릿을 복원할 수 있도록 이 데이터베이스를 정기적인 GitLab 백업과 함께 백업합니다.
OpenBao에 특화된 자세한 백업 및 복원 절차는 OpenBao 백업 문서를 참고합니다.
복구 키 관리#
복구 키 저장, 조회, 루트 토큰 생성 등 OpenBao 복구 키 관리에 대한 정보는 복구 키 관리를 참고합니다.
OpenBao 인증 복구#
GitLab은 JSON Web Token(JWT)으로 OpenBao에 인증합니다. OpenBao는 JWT의 iss(issuer)와 aud(audience) 클레임이
OpenBao가 저장한 값과 일치할 때만 JWT를 수락합니다. OpenBao는 이 값을 OpenBao를 초기화할 때와
각 프로젝트와 그룹에 GitLab Secrets Manager를 프로비저닝할 때 저장합니다. 이후 구성을 변경해도 OpenBao는
저장된 값을 업데이트하지 않습니다.
다음과 같은 경우 인증이 실패합니다.
- JWT audience 불일치: OpenBao URL이 변경된 경우처럼 GitLab이 OpenBao가 저장한 audience와 다른 audience를 전송합니다. 불일치를 해결하려면 JWT audience를 복원합니다.
- JWT issuer 불일치: OpenBao를 초기화한 후 GitLab URL이 변경되었습니다. 불일치를 해결하려면 JWT issuer를 복원합니다.
gitlab:secrets_management:openbao:root_token:generate는 GitLab JWT로 OpenBao에 인증하므로
루트 토큰으로는 인증 문제를 해결할 수 없습니다.
audience나 issuer를 복원할 수 없다면 OpenBao 데이터를 초기화합니다. 초기화하면 저장된 모든 시크릿이 삭제됩니다.
저장된 JWT audience 찾기#
저장된 audience는 OpenBao를 처음 초기화했을 때의 OpenBao URL입니다.
저장된 JWT audience를 찾으려면 다음과 같이 합니다.
-
후보를 찾습니다. 이전 복원에서
global.openbao.jwt_audience를 설정했다면 그 값이 저장된 audience입니다. 다음 단계에서 그 값을 확인합니다.그렇지 않다면 후보를 나열합니다. Helm은 최근 차트 리비전의 렌더링된 구성을 보관하므로, 각 리비전의
bound_audiences값을 나열합니다.for revision in $(helm history gitlab -n gitlab | awk 'NR > 1 { print $1 }'); do echo "$revision: $(helm get manifest gitlab -n gitlab --revision "$revision" | grep -o '"bound_audiences": "[^"]*"')" done서로 다른 값 하나하나가 후보입니다. 기본적으로 Helm은 최근 10개 리비전을 보관합니다. OpenBao를 더 오래된 리비전에서 처음 초기화했다면 목록에 저장된 audience가 없을 수 있습니다.
-
각 후보를 확인합니다. Rails 콘솔에서
<candidate_audience>를 후보 값으로 바꾸어 다음을 실행합니다.jwt = SecretsManagement::GlobalSecretsManagerJwt.new(aud: '<candidate_audience>').encoded SecretsManagement::SecretsManagerClient.new(jwt: jwt).generate_root_token_statusOpenBao가 이 audience를 저장했다면 두 번째 명령은 오류 없이 반환됩니다. 그렇지 않으면 OpenBao가
invalid audience (aud) claim으로 JWT를 거부합니다. 대신invalid issuer (iss) claim으로 JWT를 거부한다면 먼저 JWT issuer를 복원합니다.
JWT audience 복원#
GitLab이 OpenBao가 저장한 audience와 다른 audience를 전송할 때 JWT audience를 복원합니다.
사전 요구 사항:
- OpenBao가 저장한 audience. 자세한 내용은 저장된 JWT audience 찾기를 참고합니다.
JWT audience를 복원하려면 다음과 같이 합니다.
-
Helm values 파일에서
global.openbao.jwt_audience를 저장된 audience로 설정합니다. 예를 들면 다음과 같습니다.global: openbao: jwt_audience: https://openbao.example.com -
GitLab을 재배포합니다.
helm upgrade --install --version <chart-version> gitlab gitlab/gitlab \ -n gitlab -f gitlab.yaml
GitLab 파드가 다시 시작되면 GitLab이 OpenBao에 다시 인증합니다.
JWT issuer 복원#
OpenBao를 초기화한 후 GitLab URL이 변경된 경우 JWT issuer를 복원합니다. OpenBao는 그 시점의 GitLab URL을 issuer로 기대하므로 GitLab URL을 원래대로 되돌려야 합니다.
JWT issuer를 복원하려면 다음과 같이 합니다.
-
Helm values 파일에서 GitLab 호스트 설정을 OpenBao를 처음 초기화했을 때의 값으로 되돌립니다. 자세한 내용은 호스트 설정 구성을 참고합니다.
-
GitLab을 재배포합니다.
helm upgrade --install --version <chart-version> gitlab gitlab/gitlab \ -n gitlab -f gitlab.yaml
GitLab 파드가 다시 시작되면 GitLab이 OpenBao에 다시 인증합니다.
OpenBao 데이터 초기화#
이 절차는 OpenBao에 저장된 모든 시크릿과 시크릿 권한을 영구적으로 삭제하고, 모든 프로젝트와 그룹의 시크릿 관리자를 끕니다.
OpenBao 데이터를 초기화하면 OpenBao 데이터베이스가 지워져, OpenBao가 Helm values의 구성으로 자체 초기화됩니다.
사전 요구 사항:
- 구성에 올바른 OpenBao URL이 있어야 합니다. OpenBao는 자체 초기화 중에 이 URL에서
bound_audiences를 파생합니다. global.openbao.jwt_audience가 같은 URL로 설정되어 있거나 설정되어 있지 않아야 합니다.
OpenBao 데이터를 초기화하려면 다음과 같이 합니다.
-
OpenBao를 복제본 0개로 축소합니다.
kubectl -n gitlab scale deployment gitlab-openbao --replicas=0 kubectl -n gitlab wait --for=delete pod -l app.kubernetes.io/name=openbao --timeout=120s -
toolbox 파드 이름을 가져옵니다.
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;" -
GitLab 데이터베이스에서 시크릿 관리자 레코드와 저장된 복구 키를 삭제합니다. 이전 복구 키는 더 이상 작동하지 않으며, 이전 키가 저장되어 있는 동안에는 새 키를 만들 수 없습니다. Rails 콘솔에서 다음을 실행합니다.
ApplicationRecord.connection.execute(<<~SQL) TRUNCATE TABLE project_secrets_managers, project_secrets_manager_maintenance_tasks, group_secrets_managers, group_secrets_manager_maintenance_tasks, secret_rotation_infos, group_secret_rotation_infos, namespace_secret_counts SQL SecretsManagement::RecoveryKey.active.destroy_all시크릿 관리자를 하나씩 끄는 대신
TRUNCATE를 사용합니다. 시크릿 관리자를 끄면 OpenBao를 호출해 데이터를 삭제하는데, 그 데이터는 이전 단계에서 이미 삭제되었습니다. -
단일 OpenBao 복제본으로 오토스케일링을 설정하여 OpenBao를 재배포합니다.
openbao.autoscaling설정은 초기화가 완료되기 전에 Horizontal Pod Autoscaler가 두 번째 복제본을 추가하지 않도록 막습니다.helm upgrade --install --version <chart-version> gitlab gitlab/gitlab \ -n gitlab -f gitlab.yaml \ --set openbao.autoscaling.minReplicas=1 --set openbao.autoscaling.maxReplicas=1 -
OpenBao를 복제본 1개로 확장합니다. 차트를 재배포해도 수동으로 축소한 배포는 복원되지 않습니다.
kubectl -n gitlab scale deployment gitlab-openbao --replicas=1 kubectl -n gitlab rollout status deployment gitlab-openbao --timeout=120s -
OpenBao가 초기화되고 봉인 해제되었는지 확인합니다.
https://openbao.example.com을 사용 중인 OpenBao URL로 바꿉니다.curl "https://openbao.example.com/v1/sys/health"응답에
"initialized":true와"sealed":false가 포함됩니다. -
단일 복제본 설정 없이 재배포한 다음 OpenBao를 평소 복제본 수로 확장합니다.
<replica_count>를openbao.autoscaling.minReplicas값으로 바꿉니다. 기본값은2입니다.helm upgrade --install --version <chart-version> gitlab gitlab/gitlab \ -n gitlab -f gitlab.yaml kubectl -n gitlab scale deployment gitlab-openbao --replicas=<replica_count> kubectl -n gitlab rollout status deployment gitlab-openbao --timeout=120s -
새 복구 키를 만듭니다.
초기화한 후에는 각 프로젝트와 그룹에서 다음에 누군가 시크릿을 만들 때 GitLab Secrets Manager가 다시 프로비저닝됩니다.
외부 요청에서 시크릿 액세스 활성화#
히스토리
- GitLab 19.3에서 Rake 태스크 도입.
GitLab 19.2 이상에서 프로비저닝된 시크릿 관리자는 외부 서비스 및 도구에서의 시크릿 액세스를 지원합니다. GitLab 19.1 이하에서 프로젝트나 그룹에 대해 시크릿 관리자가 프로비저닝된 경우 이 액세스는 지원되지 않습니다.
GitLab 19.2 이전에 프로비저닝된 시크릿 관리자에 대해 이 액세스를 활성화하려면
관리자가 backfill_api_auth Rake 태스크를 실행해야 합니다.
Rake 태스크가 실행되는 동안 시크릿 관리자는 활성 상태로 유지되며 기존 시크릿은 보존됩니다.
사전 요구 사항:
- 관리자 액세스 권한.
인스턴스의 모든 그룹 및 프로젝트 시크릿 관리자를 백필하려면 다음과 같이 합니다.
# Linux package (Omnibus) and Helm chart (Kubernetes)
sudo gitlab-rake gitlab:secrets_management:backfill_api_auth
# Self-compiled (source)
bundle exec rake gitlab:secrets_management:backfill_api_auth RAILS_ENV=production
대신 단일 최상위 그룹이나 사용자 네임스페이스로 백필 범위를 지정하려면 해당 ID를 전달합니다.
sudo gitlab-rake "gitlab:secrets_management:backfill_api_auth[<root_namespace_id>]"
이 태스크는 멱등성을 가지므로 여러 번 실행해도 안전합니다. 실패가 보고되면 근본 원인(예: OpenBao 서버에 연결할 수 없음)을 해결한 후 태스크를 다시 실행합니다.
GitLab용 OpenBao 정책 업데이트#
히스토리
- Rake 태스크가 GitLab 19.6에서 도입되었습니다.
시크릿 매니저를 프로비저닝하기 위해 GitLab은 gitlab_rails_jwt 인증 마운트의 app 역할로 OpenBao에 인증합니다.
secrets_manager OpenBao 정책은 이 역할이 수행할 수 있는 작업을 제어합니다.
이전 버전의 정책은 모든 OpenBao 경로에 대한 액세스를 부여합니다.
GitLab 19.6 이상에는 GitLab이 사용하는 경로에만 액세스를 부여하는 제한된 정책이 포함되어 있습니다.
OpenBao는 처음 초기화될 때 정책을 한 번 생성합니다.
GitLab을 업그레이드해도 기존 정책은 바뀌지 않습니다.
기존 설치에서 정책을 업데이트하려면 관리자가
gitlab:secrets_management:openbao:secrets_manager_policy:update Rake 태스크를 실행합니다.
이 태스크는 OpenBao의 정책과 사용 중인 GitLab 버전에 포함된 정책을 비교합니다.
두 정책이 일치하면 태스크는 아무것도 변경하지 않습니다.
사전 요구 사항:
- 관리자 액세스 권한이 있어야 합니다.
- OpenBao 2.6.0 이상이 필요합니다.
- 복구 키가 있어야 합니다.
- OpenBao에 제한된 정책이 있는 경우 복구 키로 생성한 루트 토큰이 필요합니다. 제한된 정책은 GitLab이 정책을 변경하는 것을 허용하지 않습니다.
정책을 업데이트하려면 다음과 같이 합니다.
-
Rake 태스크를 실행합니다. 기본적으로 이 태스크는 아무것도 변경하지 않고 기존 정책과 사용 중인 GitLab 버전에 포함된 정책을 보여 줍니다.
# Linux package (Omnibus) sudo gitlab-rake "gitlab:secrets_management:openbao:secrets_manager_policy:update" # Helm chart (Kubernetes) kubectl exec -n gitlab -it -c toolbox <toolbox-pod-name> -- \ gitlab-rake "gitlab:secrets_management:openbao:secrets_manager_policy:update"toolbox 파드 이름을 찾으려면
kubectl get pods -n gitlab -lapp=toolbox를 실행합니다.출력에
secrets_manager정책이 이미 최신이라고 나오면 다른 작업은 필요하지 않습니다. 출력에 OpenBao에 복구 키가 없다고 나오면 복구 키를 저장한 뒤 태스크를 다시 실행합니다. -
정책을 업데이트하려면
DRY_RUN=false로 Rake 태스크를 실행합니다.# Linux package (Omnibus) sudo gitlab-rake "gitlab:secrets_management:openbao:secrets_manager_policy:update" DRY_RUN=false # Helm chart (Kubernetes) kubectl exec -n gitlab -it -c toolbox <toolbox-pod-name> -- \ gitlab-rake "gitlab:secrets_management:openbao:secrets_manager_policy:update" DRY_RUN=falseGitLab 데이터베이스에 복구 키가 저장되어 있지 않으면 태스크가 복구 키를 가지고 있는지 묻습니다. 계속하려면
y를 입력합니다.OpenBao가 업데이트를 거부하면 태스크가 루트 토큰을 요청합니다. 루트 토큰을 입력합니다. 태스크는 입력하는 동안 토큰을 표시하지 않습니다. 루트 토큰은 만료되지 않으므로 유지 관리를 마치면 루트 토큰을 폐기합니다.
-
루트 토큰을 입력했고 추가 유지 관리에 필요하지 않다면 루트 토큰을 폐기합니다. 루트 토큰을 생성할 때 사용한 절차의 마지막 단계에서 폐기 방법을 확인할 수 있습니다.