flowchart TB
    SecretStore[Secret store]
    PostgreSQL[PostgreSQL]
    LB[Load balancer]
    OpenBao[OpenBao active node]
    Rails[Rails backend]
    Runner[GitLab Runner]
    Workhorse[Workhorse]
Rails-- Write secrets and permissions -->LB
Runner-- Get pipeline secrets -->LB
LB-->OpenBao
OpenBao-- Get unseal key -->SecretStore
OpenBao-- Store -->PostgreSQL
OpenBao-- Audit logs -->Workhorse
Workhorse--&gt;Rails</code></pre></details></div>

OpenBao는 모든 요청을 처리하는 단일 활성 노드로 실행되며,
선택적으로 활성 노드가 실패할 경우 대신하는 여러 대기 노드도 있습니다.
OpenBao 설치#
사전 요구 사항:


관리자 액세스 권한.


GitLab 19.0 이상.


Kubernetes 클러스터.


Cloud Native GitLab 배포의 경우 외부(비 Omnibus) PostgreSQL 인스턴스.
외부 PostgreSQL 인스턴스는 OpenBao가 아닌 Cloud Native 배포를 위한 GitLab Helm 차트에서 요구합니다. OpenBao는 해당 인스턴스의 별도 논리 데이터베이스를 사용합니다.


GitLab 배포에 따라 설치 방법을 선택합니다:


Cloud Native GitLab: GitLab을 Kubernetes에 배포하는 경우 사용합니다.
자세한 내용은 OpenBao Helm 차트 문서를 참조하세요.


Linux 패키지: 단일 노드 또는 여러 노드에 Linux 패키지로 GitLab을 배포하는 경우 사용합니다. 자세한 내용은
Linux 패키지 인스턴스용 OpenBao 설치를 참조하세요.


설치 후 GitLab Secrets Manager 사용자 문서를 따라
OpenBao가 작동하는지 확인합니다.
사이징 권장 사항#
OpenBao 리소스 요구 사항은 GitLab 인스턴스 크기와 시크릿 사용 패턴에 따라 다릅니다.
이 권장 사항은 검증된 시작점입니다. 실제 사용 패턴에 따라 배포를 모니터링하고 리소스를 조정합니다.
요구 사항은 시크릿을 가져오는 CI/CD job의 수와
Secrets Manager가 활성화된 그룹 및 프로젝트 수에 따라 달라집니다.
Pod 리소스#
OpenBao는 모든 요청을 처리하는 단일 활성 노드로 실행됩니다.
추가 레플리카는 고가용성 페일오버만 제공합니다.
OpenBao는 PostgreSQL 데이터베이스에 연결 시 수평 읽기 확장(HRS)을 지원하지 않으므로
대기 노드는 읽기 트래픽을 처리하지 않습니다.



시크릿 가져오기/초
CPU 요청
메모리 요청
레플리카




최대 3
500m
2 GB
2


최대 6
500m
3 GB
2


최대 12
500m
4 GB
2


최대 30
500m
9 GB
2


최대 60
1,000m
16 GB
2


최대 150
2,000m
31 GB
2



시크릿 가져오기 속도 추정#
적용할 행을 결정하려면 초당 시크릿 가져오기를 추정합니다:
fetches/s = Git Pull RPS × adoption rate × 3

각 항목의 의미:


Git Pull RPS는 GitLab 인스턴스의 최대 Git 풀 처리량입니다.
기존 환경 모니터링에서 측정할 수 있으며,
최대 트래픽 메트릭 추출을 참조하세요.


adoption rate는 Secrets Manager를 사용하는 CI/CD job의 비율입니다
(예: 5%이면 0.05, 20%이면 0.20, 50%이면 0.50).


3은 Secrets Manager를 사용하는 job당 평균 시크릿 가져오기 수입니다.


결과가 시크릿 가져오기/초 값을 충족하거나 약간 초과하는 행을 선택합니다.
예를 들어 측정된 Git 풀 RPS가 20이고 채택률이 20%인 배포:
20 × 0.20 × 3 = 12 가져오기/초. 최소한 최대 12 행을 사용합니다.
배포 후 실제 사용량과 추정치를 비교 검토합니다.
모니터링 쿼리를 사용하여 리소스 사용량을 측정하고
임계값이 초과되면 다음 행으로 확장합니다.
리소스 계산 방법#
CPU는 CI/CD job이 시크릿을 가져오는 빈도에 의해 결정됩니다.
시크릿 쓰기 작업(시크릿 생성 또는 업데이트)은 파이프라인 볼륨에 비해 드물고
CPU 부하에 미치는 영향이 미미합니다.
각 CI/CD job은 Git 클론으로 시작하므로 테이블은 CI job 속도의 대리값으로
Git 클론 속도(Git Pull RPS)를 사용합니다.
수식은 시크릿 가져오기 속도 추정을 참조하세요.
CPU 제한을 CPU 요청의 두 배로 설정합니다. 이는 안정 상태에서 노드의 과도한 예약 없이
시작 및 프로비저닝 스파이크에 대한 버스트 헤드룸을 제공합니다.
메모리는 OpenBao 네임스페이스 수에 의해 결정되며,
이는 Secrets Manager가 활성화된 GitLab 그룹 및 프로젝트 수에 해당합니다.
네임스페이스당 약 5 MB를 할당하고 1 GB 안전 마진을 추가하되 최소 2 GB를 할당합니다.
메모리 제한을 메모리 요청과 동일하게 설정합니다(Guaranteed QoS 클래스).
OpenBao는 메모리 제한을 초과하면 정상적인 저하 없이 즉시 충돌합니다.
레플리카는 고가용성 페일오버만 제공합니다. 모든 배포에 2개의 레플리카를 사용합니다.
OpenBao는 PostgreSQL 스토리지 백엔드와 함께 수평 읽기 확장(HRS)을 지원하지 않으므로
추가 레플리카는 처리량 이점을 제공하지 않습니다.
데이터베이스 리소스#
OpenBao는 별도의 PostgreSQL 데이터베이스에 데이터를 저장합니다.
GitLab 데이터베이스와 동일한 PostgreSQL 서버에 함께 배치할 수 있습니다.
참조 아키텍처 PostgreSQL 권장 사항 이외의
추가 데이터베이스 컴퓨팅 용량은 필요하지 않습니다.
데이터베이스 연결 풀#
OpenBao Helm 차트는 다음 PostgreSQL 연결 풀 기본값을 구성합니다:



설정
기본값




config.storage.postgresql.maxParallel
5


config.storage.postgresql.maxIdleConnections
2



모니터링에서 데이터베이스 연결 대기 시간이 관찰되지 않는 한 이 값을 늘리지 마세요.
데이터베이스 스토리지#
데이터베이스 스토리지 요구 사항은 주로 총 시크릿 수에 따라 다릅니다.
메타데이터 및 저장된 버전을 포함한 각 시크릿은 약 13 KB의 스토리지를 필요로 합니다.



총 시크릿 수
예상 스토리지




10,000
~130 MB


50,000
~650 MB


100,000
~1.3 GB


200,000
~2.6 GB



모든 참조 아키텍처 계층에서 스토리지 증가는 미미합니다.
5~10 GB의 데이터베이스 스토리지를 할당하면 충분한 여유가 제공됩니다.
GitLab Secrets Manager 활성화#
히스토리
GitLab 19.0에서 도입됨
Secrets Manager가 인스턴스에 대해 활성화되면
특정 그룹 및 프로젝트에 대해 활성화할 수 있습니다.
사전 요구 사항:


관리자 액세스 권한.


OpenBao가 설치 및 구성되어 있어야 합니다.


인스턴스에 대한 Secrets Manager를 활성화하려면:


오른쪽 상단 모서리에서 Admin을 선택합니다.


왼쪽 사이드바에서 Settings > General을 선택합니다.


GitLab Secrets Manager를 확장합니다.


Secrets Manager 토글을 켭니다.


OpenBao 배포 모니터링#
다음 쿼리를 사용하여 배포가 올바르게 사이징되었는지 확인하고 확장이 필요할 때 감지합니다.
CPU 사용률#
OpenBao CPU 사용량을 측정하려면:
sum(rate(container_cpu_usage_seconds_total{container="openbao-server"}[5m]))

결과는 CPU 코어 단위입니다. 사이징 테이블의 CPU 요청 값과 비교하기 위해 1,000을 곱하면
밀리코어로 변환됩니다.
CPU 사용률이 지속적으로 CPU 요청의 50%를 초과하면 사이징 테이블의 다음 행으로 확장을 고려하세요.
메모리 사용률#
OpenBao 메모리 사용량을 측정하려면:
sum(container_memory_working_set_bytes{container="openbao-server"})

결과는 바이트 단위입니다. 메모리는 그룹과 프로젝트가 Secrets Manager를 활성화함에 따라
네임스페이스당 약 5 MB씩 증가합니다. 재시작 후 OpenBao가 데이터베이스에서
네임스페이스 메타데이터를 로드하면서 메모리가 안정됩니다.
올바른 메모리 요청을 계산하려면 Secrets Manager가 활성화된 그룹 및 프로젝트 수를 세고
5 MB를 곱한 다음 1 GB를 추가합니다. 결과가 현재 메모리 요청을 초과하면 Pod 리소스를 업데이트합니다.
메모리가 활성 프로비저닝 없이 지속적인 상승 추세를 보이면 잠재적인 문제를 조사합니다.
CPU 스로틀링#
지연 시간에 영향을 줄 수 있는 CPU 스로틀링을 감지하려면:
sum(rate(container_cpu_cfs_throttled_periods_total{container="openbao-server"}[5m]))
/
sum(rate(container_cpu_cfs_periods_total{container="openbao-server"}[5m]))

스로틀 비율이 0.25(25%)를 초과하면 CPU 제한이 현재 워크로드에 너무 낮음을 나타냅니다.
OpenBao가 스로틀링되면 CPU 시간을 기다리는 고루틴이 시크릿 가져오기 지연 시간을 증가시킵니다.
OpenBao 메트릭#
OpenBao Prometheus 메트릭을 사용하여 요청 지연 시간, 스토리지 백엔드 성능, 캐시
효율성, 노드 상태를 모니터링합니다.
기본적으로 OpenBao는 포트 8209의 인증되지 않은 리스너에서 /v1/sys/metrics 경로로 메트릭을 제공합니다.
메트릭 이름은 openbao_ 접두사를 사용하며, OpenBao는 24시간 동안 메트릭 데이터를 보관합니다.
포트, 메트릭 접두사 또는 보관 시간을 변경하려면
모니터링 구성 옵션을 참조하세요.
메트릭 포트는 서비스를 통해 노출되지 않으므로, 모니터링이 OpenBao Pod를 직접 스크랩하도록 구성합니다.
Prometheus Operator를 사용하는 경우 GitLab 차트에는 기본적으로 비활성화된 PodMonitor가 포함됩니다.
활성화하려면 openbao.podMonitor.enabled를 true로 설정합니다.
다음 메트릭은 배포 운영에 가장 유용합니다:



메트릭
타입
설명




openbao_core_active
Gauge
노드가 활성 노드(1)인지 대기 노드(0)인지 여부.


openbao_core_unsealed
Gauge
노드가 unsealed(1)인지 sealed(0)인지 여부.


openbao_core_in_flight_requests
Gauge
동시에 처리 중인 요청 수.


openbao_core_handle_request
Summary
요청 처리의 지연 시간.


openbao_postgres_get
Summary
PostgreSQL 스토리지 백엔드에서 항목을 읽는 시간.


openbao_postgres_put
Summary
PostgreSQL 스토리지 백엔드에 항목을 쓰는 시간.


openbao_postgres_list
Summary
PostgreSQL 스토리지 백엔드에서 항목을 나열하는 시간.


openbao_postgres_delete
Summary
PostgreSQL 스토리지 백엔드에서 항목을 삭제하는 시간.


openbao_barrier_get
Summary
암호화 배리어를 통해 항목을 읽는 시간.


openbao_barrier_put
Summary
암호화 배리어를 통해 항목을 쓰는 시간.


openbao_barrier_list
Summary
암호화 배리어를 통해 항목을 나열하는 시간.


openbao_barrier_delete
Summary
암호화 배리어를 통해 항목을 삭제하는 시간.


openbao_cache_hit
Counter
캐시 히트 수.


openbao_cache_miss
Counter
캐시 미스 수.


openbao_cache_write
Counter
캐시 쓰기 수.


openbao_audit_log_request_failure
Counter
감사 로그 요청 실패 수.


openbao_audit_log_response_failure
Counter
감사 로그 응답 실패 수.


openbao_runtime_alloc_bytes
Gauge
OpenBao 프로세스가 할당한 메모리 바이트.



Summary 메트릭은 _count, _sum, 분위수 시리즈(0.5, 0.9, 0.99)를 노출합니다.
평균을 계산하려면 _sum 시리즈의 속도를 _count 시리즈의 속도로 나눕니다.
지연 시간 상승 확인에 표시된 방법을 참조하세요.
이 메트릭을 사용하는 임계값 및 진단 쿼리는
느린 시크릿 작업 진단을 참조하세요.
완전한 OpenBao 메트릭 목록은 OpenBao 텔레메트리 메트릭을 참조하세요.
상태 확인 엔드포인트#
OpenBao는 모니터링을 위한 상태 확인 엔드포인트를 제공합니다:


<your-openbao-url>/v1/sys/health: OpenBao의 상태를 반환합니다.


<your-openbao-url>/v1/sys/seal-status: seal 상태를 반환합니다.


이러한 엔드포인트를 모니터링 시스템과 통합할 수 있습니다.
고가용성#
OpenBao는 단일 활성 노드 아키텍처를 사용합니다. 하나의 노드가 모든 요청을 처리하고,
대기 노드는 활성 노드가 실패할 경우 자동 페일오버를 제공합니다.
페일오버#
대기 노드는 시작 시 모든 네임스페이스 메타데이터를 로드하므로 활성으로의 승격에는
추가 초기화가 필요하지 않습니다. 네임스페이스 수는 페일오버 시간에 영향을 미치지 않습니다.
프로덕션 배포의 경우:


이중화를 위해 최소 두 개의 OpenBao 레플리카를 실행합니다.


고가용성 PostgreSQL 백엔드를 사용합니다.


모니터링 쿼리를 사용하여 모니터링 및 알림을 구현합니다.


업그레이드 다운타임#
OpenBao는 무중단 업그레이드를 지원하지 않습니다. 업그레이드 중 OpenBao는 시작 시
각 네임스페이스를 순차적으로 초기화합니다. Secrets Manager가 활성화된 모든 그룹 또는
프로젝트는 하나의 네임스페이스로 계산됩니다.
업그레이드하는 데 1,000 네임스페이스당 약 11초와 5초 기본 시간이 소요됩니다.
OpenBao가 온디맨드 네임스페이스 로딩을 구현하면 업그레이드 다운타임이 크게 줄어듭니다.
자세한 내용은
이슈 595721을 참조하세요.
Geo 배포#
OpenBao는 Geo 배포를 지원합니다. OpenBao는 기본 사이트와 보조 Geo 사이트 모두에
배포되지만, 기본 사이트에서만 활성 OpenBao 노드가 실행됩니다.

OpenBao는 다른 도메인을 사용하는 보조 사이트로의 Geo 페일오버를 지원하지 않습니다. 보조 사이트가
기본 도메인을 가리키도록 DNS를 업데이트하는 대신 자체 도메인을 유지하는 경우,
GitLab Secrets Manager가 활성화된 모든 프로젝트 및 그룹에 대해 JWT 인증을 수동으로 재프로비저닝해야 합니다.
재프로비저닝은 루트 레벨 및 각 네임스페이스에 적용되며, 대규모 배포에서는 시간이 많이 소요됩니다.
마이그레이션 도구가 이슈 595722에서 제안 중입니다.
도구가 존재할 때까지 기본 도메인이 승격된 보조 사이트를 가리키도록 DNS 레코드를 업데이트하세요.

Geo에서의 OpenBao 동작#
기본 사이트에서 OpenBao는 쓰기 가능한 PostgreSQL 데이터베이스에 연결된 활성
노드로 실행됩니다. 보조 사이트에서 OpenBao는 PostgreSQL 읽기 복제본에 연결된 대기 모드로 실행됩니다.
PostgreSQL 스트리밍 복제는 모든 OpenBao 데이터(시크릿, 정책, 인증
구성)를 기본 사이트에서 보조 사이트로 자동으로 전송합니다.
두 GitLab 인스턴스(기본 및 보조) 모두 기본 OpenBao URL에 연결합니다. 보조
OpenBao 배포는 대기 상태로 유지되며, Geo 장애 조치 중에
보조 PostgreSQL 데이터베이스가 쓰기 가능해지면 활성으로 승격됩니다.
보조 사이트에서 OpenBao는 failed to acquire lock 및
cannot execute INSERT in a read-only transaction 오류를 로그에 기록합니다. 이러한 오류는 예상되는 동작입니다.
OpenBao는 읽기 전용 데이터베이스에서 HA 리더 잠금을 획득할 수 없습니다.
보조 사이트에 OpenBao 설치#
사전 요구 사항:


Geo가 구성되어 있어야 합니다. 자세한 내용은 Geo 설정을 참조하세요.


보조 사이트에 배포하기 전에 기본 사이트에 OpenBao가 설치되고 작동 중이어야 합니다.
자세한 내용은 OpenBao 설치를 참조하세요.


보조 OpenBao는 복제된 데이터를 복호화하기 위해 기본과 동일한 unseal 구성을 사용해야 합니다.
단계는 구성된 unseal 방법에 따라 다릅니다:
Kubernetes 시크릿(기본값): 기본 클러스터에서 보조 클러스터로 gitlab-openbao-unseal Kubernetes 시크릿을 복사합니다:
kubectl --namespace gitlab get secret gitlab-openbao-unseal -o yaml

내보낸 시크릿을 보조 클러스터에 적용합니다. 자세한 내용은
시크릿 백업을 참조하세요.


KMS 기반 자동 unseal: 동일한 KMS 키로 보조 클러스터를 구성합니다.
자세한 내용은
Unsealing 및 초기화 옵션을 참조하세요.


페일오버 중에 기본 도메인의 DNS 레코드를 보조 사이트로 업데이트할 계획이라면,
미리 OpenBao를 구성할 수 있습니다.
Helm 차트를 구성하고 url 및 jwt_audience를 기본 OpenBao URL로 설정합니다:
global:
  openbao:
    enabled: true
    url: https://openbao.<primary-domain>
    jwt_audience: https://openbao.<primary-domain>

차트 구성 옵션에 대한 자세한 내용은
OpenBao 차트 문서를 참조하세요.


보조 사이트에 GitLab Helm 차트를 배포합니다. OpenBao Pod가 시작되고 대기
모드로 유지됩니다. 이는 예상되는 동작입니다.


보조 클러스터에서 OpenBao Pod가 실행 중인지 확인합니다:
kubectl --namespace gitlab get pods -l app=openbao

모든 Pod가 Running 상태여야 합니다. 보조 Pod에는 openbao-active: "true"
레이블이 없습니다. 이는 예상되는 동작입니다.


보조 클러스터에서 활성 서비스에 엔드포인트가 없는지 확인합니다:
kubectl --namespace gitlab get endpoints gitlab-openbao-active

보조에서 엔드포인트가 없는 것은 예상되는 동작입니다.


보조 사이트에서 Secrets Manager 변수를 사용하는
CI 파이프라인을 실행하여 Secrets Manager를 테스트합니다.


문제 해결#
배포, 연결, 프로비저닝, 봉인, 데이터베이스, 감사, Geo
문제를 진단하려면 OpenBao 문제 해결을 참조하세요.
유지 관리#
OpenBao 백업 및 복원, 복구 키 관리, OpenBao 인증 복구에 대한 자세한 내용은
OpenBao 유지 관리를 참조하세요.