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 18.8 이상.
Linux 패키지 인스턴스와 함께 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 잡의 수와 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 잡의 비율입니다(예: 5%이면 0.05, 20%이면 0.20, 50%이면 0.50).
3은 Secrets Manager를 사용하는 잡당 평균 시크릿 가져오기 수입니다.

결과가 시크릿 가져오기/초 값을 충족하거나 약간 초과하는 행을 선택합니다.
예를 들어 측정된 Git 풀 RPS가 20이고 채택률이 20%인 배포: 20 × 0.20 × 3 = 12 가져오기/초. 최소한 최대 12 행을 사용합니다.
배포 후 실제 사용량과 추정치를 비교 검토합니다.
모니터링 쿼리를 사용하여 리소스 사용량을 측정하고 임계값이 초과되면 다음 행으로 확장합니다.
리소스 계산 방법#
CPU는 CI/CD 잡이 시크릿을 가져오는 빈도에 의해 결정됩니다.
시크릿 쓰기 작업(시크릿 생성 또는 업데이트)은 파이프라인 볼륨에 비해 드물고 CPU 부하에 미치는 영향이 미미합니다.
각 CI/CD 잡은 Git 클론으로 시작하므로 테이블은 CI 잡 속도의 대리값으로 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의 데이터베이스 스토리지를 할당하면 충분한 여유가 제공됩니다.
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는 모니터링을 위한 상태 확인 엔드포인트를 제공합니다:

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

이러한 엔드포인트를 모니터링 시스템과 통합할 수 있습니다.
백업 및 복원#
OpenBao는 PostgreSQL의 별도 논리 데이터베이스에 데이터를 저장합니다. 장애 후 시크릿을 복원할 수 있도록 정기적인 GitLab 백업과 함께 이 데이터베이스를 백업합니다.
OpenBao에 특정한 자세한 백업 및 복원 절차는 OpenBao 백업 문서를 참조하세요.
복구 키 관리#
복구 키 저장, 보기, 루트 토큰 생성에 사용하는 방법을 포함한 OpenBao 복구 키 관리에 대한 자세한 내용은 복구 키 관리를 참조하세요.
고가용성#
OpenBao는 단일 활성 노드 아키텍처를 사용합니다. 하나의 노드가 모든 요청을 처리하고, 대기 노드는 활성 노드가 실패할 경우 자동 페일오버를 제공합니다.
페일오버#
대기 노드는 시작 시 모든 네임스페이스 메타데이터를 로드하므로 활성으로의 승격에는 추가 초기화가 필요하지 않습니다. 네임스페이스 수는 페일오버 시간에 영향을 미치지 않습니다.
프로덕션 배포의 경우:

이중화를 위해 최소 두 개의 OpenBao 레플리카를 실행합니다.
고가용성 PostgreSQL 백엔드를 사용합니다.
모니터링 쿼리를 사용하여 모니터링 및 알림을 구현합니다.

업그레이드 다운타임#
OpenBao는 무중단 업그레이드를 지원하지 않습니다. 업그레이드 중 OpenBao는 시작 시 각 네임스페이스를 순차적으로 초기화합니다. Secrets Manager가 활성화된 모든 그룹 또는 프로젝트는 하나의 네임스페이스로 계산됩니다.
업그레이드하는 데 1,000 네임스페이스당 약 11초와 5초 기본 시간이 소요됩니다.
OpenBao가 온디맨드 네임스페이스 로딩을 구현하면 업그레이드 다운타임이 크게 줄어듭니다.
자세한 내용은 이슈 595721을 참조하세요.
Geo 배포#
OpenBao는 Geo 배포를 지원합니다. OpenBao는 기본 사이트와 보조 Geo 사이트 모두에 배포되지만, 기본 사이트에서만 활성 OpenBao 노드가 실행됩니다.
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 키를 사용해야 합니다. 기본 클러스터에서 보조 클러스터로 gitlab-openbao-unseal Kubernetes 시크릿을 복사합니다:
kubectl --namespace gitlab get secret gitlab-openbao-unseal -o yaml

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


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

차트 구성 옵션에 대한 자세한 내용은 Geo 구성을 참조하세요.


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


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

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


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

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


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


문제 해결#
Secrets Manager 작업 중 다음 문제가 발생할 수 있습니다.
Geo 배포 문제 해결#



증상
원인
해결 방법




보조 OpenBao 로그에 cipher: message authentication failed 또는 알 수 없는 키 ID 오류
기본과 보조 간의 unseal 키 불일치
기본 클러스터에서 보조 클러스터로 gitlab-openbao-unseal을 복사하고 OpenBao 파드를 재시작합니다.


보조 OpenBao 로그에 failed to acquire lock 오류
읽기 전용 데이터베이스에서 OpenBao 대기
예상되는 동작입니다. 조치가 필요하지 않습니다.


보조 OpenBao 로그에 cannot execute INSERT in a read-only transaction 오류
읽기 복제본에서 OpenBao가 리더 선출 시도
예상되는 동작입니다. 조치가 필요하지 않습니다.


Geo 장애 조치 후 JWT 인증 실패
jwt_audience가 OpenBao의 boundAudiences와 일치하지 않음
두 사이트 모두에서 jwt_audience를 기본 OpenBao URL로 설정합니다.



느린 시크릿 작업 진단#
CI/CD 잡의 시크릿 가져오기가 느리거나 시크릿 작업이 시간 초과될 때 이 섹션을 사용합니다.
지연 시간 상승 확인#
다음 쿼리를 사용하여 밀리초 단위의 평균 요청 지연 시간을 측정합니다.
이 쿼리는 트래픽이 적은 배포를 포함한 모든 트래픽 수준에서 작동합니다:
rate(openbao_core_handle_request_sum[5m])
/
rate(openbao_core_handle_request_count[5m])

정상 부하에서 모든 요청 유형의 평균 지연 시간은 일반적으로 3~7 ms입니다.
평균 지연 시간이 지속적으로 20 ms를 초과하면 조사합니다.
OpenBao가 요청을 활발하게 처리할 때 다음 쿼리로 P99 지연 시간을 확인합니다:
openbao_core_handle_request{quantile="0.99"}

정상 P99는 10 ms 미만입니다. 이 쿼리는 OpenBao가 유휴 상태일 때 요약 창에 최근 관측값이 없으므로 NaN을 반환합니다. 그 경우에는 속도 기반 쿼리를 사용합니다.
잠재적 문제 식별#



잠재적 문제
확인 사항
쿼리
임계값
조치




CPU 제한이 너무 낮음
CFS 스로틀 비율
CPU 스로틀링 쿼리
25% 초과
CPU 제한 증가


수요가 CPU 용량 초과
CPU 사용률
CPU 사용률 쿼리
요청의 50% 초과
사이징 테이블의 다음 행으로 확장


요청 급증
진행 중인 요청
openbao_core_in_flight_requests
5 이상 지속
일시적. 재발을 모니터링합니다.


PostgreSQL 병목 현상
평균 PostgreSQL 읽기 지연 시간
rate(openbao_postgres_get_sum[5m]) / rate(openbao_postgres_get_count[5m])
5 ms 초과
PostgreSQL 리소스 및 연결 풀 확인


메모리 부족
메모리 사용률
메모리 사용률 쿼리
메모리 요청에 근접
네임스페이스 수식을 사용하여 메모리 증가



PostgreSQL 지연 시간이 상승하면 연결 풀이 포화 상태인지 확인합니다.
모든 연결이 사용 중이면 추가 요청이 대기하여 지연 시간이 발생합니다.
연결 풀 구성은 데이터베이스 리소스를 참조하세요.
PostgreSQL 모니터링 또는 OpenBao 로그에서 연결 수를 확인합니다.