• 관리자 액세스 권한이 있고 Linux 패키지로 설치한 GitLab 19.2 이상.
• 같은 호스트에 설치된 로컬 Kubernetes 배포판.
• 호스트에서 사용할 수 있는 helm 과 kubectl.
• OpenBao 도메인을 호스트의 공개 IP 주소로 지정하는 DNS 레코드.

OpenBao 를 설치하기 전에 Kubernetes 배포판이 다음 요구 사항을 충족하는지 확인합니다.

• Linux 패키지 인스턴스의 요구 사항과 Kubernetes 클러스터의 요구 사항에 더해 OpenBao 사이징 권장 사항도 충족해야 합니다.
• 코로케이티드 Kubernetes 안의 어떤 것도 GitLab 이 이미 사용하는 포트에 연결을 시도해서는 안 됩니다. 작은 Kubernetes 배포판 중에는 기본적으로 80번과 443번 포트에 바인딩되는 로드 밸런서를 설치하는 것이 많습니다. Linux 패키지가 관리하는 NGINX 가 이미 그 포트에서 수신 대기하므로 이러한 컴포넌트는 비활성화합니다.
• 코로케이티드 Kubernetes 는 Linux 패키지 인스턴스와 네트워크를 공유해야 합니다. 그래야 Linux 패키지가 관리하는 NGINX 가 외부 OpenBao 트래픽을 OpenBao 서비스로 라우팅하고 그 서비스에서 오는 요청을 수신할 수 있습니다. 공유 네트워크 안에서 양쪽에 도달할 수만 있다면 Linux 패키지 인스턴스는 서비스가 Kubernetes LoadBalancer 로 노출되는지 NodePort 로 노출되는지 상관하지 않습니다.

시작하기 전에 다음을 수행합니다.

1. Kubernetes CNI(Pod 네트워크)의 CIDR 를 수집합니다. 이후 PostgreSQL 인증을 구성할 때 필요합니다.
2. Linux 패키지 인스턴스와 Kubernetes 가 공유하는 네트워크 인터페이스의 IP 주소 ()를 수집합니다. 이후 여러 구성 값에 필요합니다.
3. OpenBao 설치를 시도하기 전에 Kubernetes 배포판이 완전히 실행 중인지 확인합니다.
4. kubectl 컨텍스트가 이 클러스터로 설정되어 있는지(KUBECONFIG 가 올바르게 구성되어 있는지) 확인합니다.

GitLab 호스트의 /etc/gitlab/gitlab.rb 에 다음을 추가하고, 자리표시자 값을 실제 IP 주소와 도메인으로 바꿉니다.

# PostgreSQL: accept TCP connections from Kubernetes pods.
# Use the shared network IP to restrict exposure to the shared network.
# Using '0.0.0.0' makes PostgreSQL listen on all interfaces, including public ones.
postgresql['listen_address'] = ''

# Local GitLab services (Rails, container registry) connect to the shared
# network IP address over TCP instead of the Unix socket, so include it in
# the trusted CIDR blocks.
postgresql['trust_auth_cidr_addresses'] = %w[127.0.0.1/32 ::1/128 /32]

# Kubernetes pods authenticate with a password.
# Replace 10.42.0.0/16 with the CIDR of your Kubernetes CNI (pod network).
postgresql['md5_auth_cidr_addresses'] = %w[10.42.0.0/16]

# Without this setting, NGINX routes all traffic on the shared IP to the
# OpenBao virtual host. Both virtual hosts must listen on the same addresses
# so NGINX can route by server name instead.
nginx['listen_addresses'] = ['*', '']

# OAK: OpenBao reverse proxy via GitLab NGINX.
oak['enable'] = true
oak['network_address'] = ''

oak['components']['openbao']['enable'] = true

# Replace 'https://openbao.example.com' with the URL of the DNS record
# you configured for OpenBao, which resolves to your host's public IP address.
oak['components']['openbao']['external_url'] = 'https://openbao.example.com'

# The internal URL that GitLab NGINX uses to reach the OpenBao service.
# If you use the service clusterIP, set a temporary value now and replace it after
# you install OpenBao. See the Helm installation step.
oak['components']['openbao']['internal_url'] = 'http://127.0.0.1:8200'

# The URL that the GitLab application uses to connect to OpenBao.
gitlab_rails['openbao'] = {
  'url' => 'https://openbao.example.com'
}

이 구성에서 각 항목의 의미는 다음과 같습니다.

• postgresql['listen_address'] 는 공유 네트워크 IP 입니다. trust_auth_cidr_addresses 나 md5_auth_cidr_addresses 에 나열되지 않은 CIDR 에서 오는 연결은 PostgreSQL 이 거부합니다.
• postgresql['trust_auth_cidr_addresses'] 는 localhost 와 공유 네트워크 IP 를 포함하는 CIDR 블록 목록입니다. 이 블록에서 오는 연결에는 비밀번호가 필요하지 않습니다. 로컬 GitLab 서비스가 Unix 소켓 대신 TCP 로 이 IP 에 연결하므로 공유 네트워크 IP 가 필요합니다.
• postgresql['md5_auth_cidr_addresses'] 는 Pod CIDR 에서 가져온 CIDR 블록 목록입니다. 이 블록에서 오는 연결에는 비밀번호가 필요합니다. 이 주소는 OpenBao Pod 가 사용합니다.
• nginx['listen_addresses'] 는 GitLab 과 OpenBao NGINX 가상 호스트가 수신 대기하는 주소를 지정합니다. NGINX 가 가장 구체적인 수신 주소를 우선하지 않고 서버 이름으로 요청을 라우팅하려면 두 가상 호스트가 같은 주소에서 수신 대기해야 합니다.
• oak['network_address'] 는 공유 네트워크 IP 입니다. NGINX listen 지시문에서 사용합니다.
• oak['components']['openbao']['internal_url'] 은 GitLab 애플리케이션이 OpenBao 와 통신하는 데 사용하는 URL 입니다.
• gitlab_rails['openbao']['url'] 은 GitLab 애플리케이션이 사용하는 OpenBao URL 입니다.

클러스터에서 OpenBao 가 노출되는 방식에 따라 내부 URL 을 선택합니다.

• 로드 밸런서 또는 nodePort. OpenBao 를 설치하기 전에 URL 을 알 수 있으므로 지금 설정해 한 번의 reconfigure 로 마칠 수 있습니다. 로드 밸런서를 사용하는 경우 내부 URL 이 로드 밸런서 IP 주소로 해석되도록 DNS 를 구성합니다.
• 서비스 clusterIP. clusterIP 는 Helm 이 서비스를 만든 뒤에만 할당됩니다. 지금은 임시 internal_url 을 설정하고 OpenBao 를 설치한 뒤에 업데이트합니다.

호스트 머신은 Kubernetes 클러스터 외부에서 내부 URL 의 IP 에 도달할 수 있어야 합니다. 선택한 에서 IP 를 할당하도록 클러스터를 구성합니다.

GitLab external_url 설정이 https:// 를 사용한다면 Let's Encrypt 가 이미 활성화되어 있습니다. OpenBao external_url 스킴을 https:// 로 설정하는 것으로 충분합니다. GitLab 이 기존 Let's Encrypt 인증서에 OpenBao 도메인을 주체 대체 이름(Subject Alternative Name, SAN)으로 자동으로 추가합니다.

대신 사용자 지정 인증서를 사용하려면 다음을 추가합니다.

oak['components']['openbao']['ssl_certificate']     = '/etc/gitlab/ssl/openbao.example.com.crt'
oak['components']['openbao']['ssl_certificate_key'] = '/etc/gitlab/ssl/openbao.example.com.key'

구성 변경 사항을 적용합니다.

sudo gitlab-ctl reconfigure

이 명령은 모든 구성을 한 번에 적용합니다.

• PostgreSQL 이 Kubernetes Pod 에서 오는 TCP 연결을 수락하기 시작합니다.
• NGINX 에 OpenBao 가상 호스트가 구성되며, TLS 종료와 HTTP 에서 HTTPS 로의 리다이렉트가 포함됩니다.
• 해당하는 경우 Let's Encrypt 인증서가 발급되거나 갱신됩니다.
• Helm 값 파일이 /etc/gitlab/openbao-helm-values.yaml 에 생성됩니다.

oak['components']['openbao']['external_url'] 이나 oak['components']['openbao']['internal_url'] 이 설정되어 있지 않으면 reconfigure 가 실패합니다.

Helm 을 사용하여 OpenBao 를 설치하려면 다음을 수행합니다.

1. GitLab Helm 리포지터리를 추가합니다.

   helm repo add gitlab https://charts.gitlab.io
   helm repo update
   

2. 생성된 값 파일로 OpenBao 를 설치합니다.

   helm upgrade --install openbao gitlab/openbao \
     --namespace openbao \
     --values /etc/gitlab/openbao-helm-values.yaml
   

   생성된 파일은 PostgreSQL 스토리지, 고가용성, JWT 초기화를 구성합니다. 코로케이티드 클러스터는 Linux 패키지가 관리하는 NGINX 를 통해 OpenBao 에 도달하므로 ingress, ui, gatewayRoute 는 구성하지 않습니다.

   사용할 수 있는 모든 차트 옵션은 OpenBao Helm 차트 문서를 참고합니다.

3. 선택 사항. 서비스 clusterIP 를 내부 URL 로 사용하는 경우 지금 확정합니다. 할당된 clusterIP 를 읽습니다.

   kubectl -n openbao get svc openbao-active \
     -o jsonpath='{.spec.clusterIP}'
   

   /etc/gitlab/gitlab.rb 에 내부 URL 을 설정합니다.

   oak['components']['openbao']['internal_url'] = 'http://:8200'
   

   그다음 다시 reconfigure 를 실행합니다.

   sudo gitlab-ctl reconfigure
   

   로드 밸런서나 nodePort 내부 URL 을 사용하는 경우 GitLab 을 구성할 때 이미 URL 을 알 수 있으므로 이 단계는 필요하지 않습니다.