Controller values

Controller values

Boundary 컨트롤러 Helm 차트는 Helm values와 Boundary HCL 구성으로 설정해요. 지원되는 값의 출처(source of truth)는 차트 자체입니다.

출처: HashiCorp Boundary docs

본문

Boundary 런타임 구성

controller.config는 Boundary 컨트롤러 HCL을 담고 있어요. 차트는 HCL 값을 ConfigMap에 쓰고 /etc/boundary/controller.hcl에 마운트합니다.

차트는 몇 가지 차트 수준의 정렬 확인을 제외하고는 Boundary 컨트롤러 의미론을 검증하지 않아요. 유효한 리스너, 데이터베이스 설정, 클러스터 주소, KMS 스탠자, 속도 제한, 이벤트 싱크를 구성하는 것은 사용자 책임입니다.

차트는 다음을 검증합니다:

  • tls.disabled=false일 때 tls_cert_file과 tls_key_file 설정이 tls.mountPath와 정렬되어 있는지
  • kms 블록 안에서 AEAD(인증된 암호화, Authenticated Encryption with Associated Data) KMS 키가 env://BOUNDARY_KMS_*로 참조되지 않는지
  • secretRefs.validateExisting=true일 때 필수 Secret 키가 존재하는지

Kubernetes 인프라 구성

Kubernetes 관련 값은 Deployment, Services, ConfigMap, Job hooks, 보안 컨텍스트, ServiceAccount, 스케줄링 옵션을 제어해요. 이 값들은 Boundary 런타임 HCL을 대체하거나 생성하지 않습니다.

예를 들어 controller.service.api.targetPort를 9220으로 바꾸면, controller.config의 API 리스너 포트도 함께 업데이트해야 해요. 변경을 확정하기 전에 구성 정렬 체크리스트를 참고하세요.

다음 절은 기능별로 그룹화된 사용 가능한 Helm 값을 설명합니다. 각 표는 키, 기본값, 설명을 나열해요.

이름 및 네임스페이스 값

Key Default Description
nameOverride "" 차트가 생성하는 리소스 기본 이름을 재정의
fullnameOverride "" 차트가 생성하는 리소스 이름을 완전히 재정의
namespace "" 차트가 네임스페이스 리소스를 렌더링하는 네임스페이스를 재정의. 빈 값은 Helm 릴리스 네임스페이스를 사용.

이미지 값

Key Default Description
image.repository hashicorp/boundary-enterprise 컨트롤러 이미지 리포지토리
image.tag "" 컨트롤러 이미지 태그. 비어 있으면 Chart.appVersion(현재 1.0.0-ent) 사용.
image.pullPolicy IfNotPresent Kubernetes 이미지 풀 정책
imagePullSecrets [] 프라이빗 레지스트리용 선택적 이미지 풀 시크릿

TLS 값

Key Default Description
tls.disabled false true이면 API와 ops 리스너에서 TLS를 비활성화. 기본값은 false(즉 TLS 활성화).
tls.secretName boundary-controller-tls TLS가 활성화될 때 마운트되는 Kubernetes TLS Secret 이름
tls.mountPath /etc/boundary/tls TLS Secret이 마운트되는 컨테이너 경로

TLS를 활성화하면 controller.config의 리스너 tls_cert_file과 tls_key_file 경로를 tls.mountPath와 정렬된 상태로 유지하세요. 프로브 스킴(scheme)이 제공되지 않으면 차트는 controller.config의 ops 리스너 tls_disable 설정에서 파생합니다.

Secret 참조 값

Key Default Description
secretRefs.secretName boundary-controller-secrets secretRefs.keys가 참조하는 값을 담고 있는 기존 Kubernetes Secret 이름
secretRefs.validateExisting false true이면 렌더링 중 참조된 Secret과 필수 키를 검증
secretRefs.keys.databaseUrl database-url controller.config에서 env://BOUNDARY_PG_URL에 사용하는 Secret의 키. Secret에서 사용한 키 이름으로 설정.
secretRefs.keys.migrationUrl migration-url controller.config에서 env://BOUNDARY_PG_MIGRATION_URL에 사용하는 Secret의 키. controller.config에서 참조할 때만 필요. Secret에서 사용한 키 이름으로 설정.
secretRefs.keys.license license controller.config에서 env://BOUNDARY_LICENSE에 사용하는 Secret의 키. Secret에서 사용한 키 이름으로 설정.
secretRefs.keys.adminUsername admin-username 부트스트랩 admin Job이 사용하는 값의 Secret 키. Secret에서 사용한 키 이름으로 설정.
secretRefs.keys.adminPassword admin-password 부트스트랩 admin Job이 사용하는 값의 Secret 키. Secret에서 사용한 키 이름으로 설정.

secretRefs.keys 값은 Kubernetes Secret 안의 키 이름으로, 차트가 고정하지 않아요. Secret을 만들 때 사용한 실제 키 이름과 일치하도록 각각 설정하세요. 예를 들어 --from-literal=pg-url=...로 Secret을 만들었다면 secretRefs.keys.databaseUrl: "pg-url"로 설정합니다.

컨트롤러 런타임 값

Key Default Description
controller.replicas 2 Deployment의 컨트롤러 레플리카 수
controller.rollingUpdate.maxUnavailable 1 롤링 업데이트 중 최대 사용 불가 포드 수
controller.rollingUpdate.maxSurge 1 롤링 업데이트 중 최대 추가 포드 수
controller.config Embedded sample HCL ConfigMap에 저장되고 컨트롤러 컨테이너와 hook Job에 마운트되는 Boundary 컨트롤러 HCL

기본 controller.config에는 disable_mlock = true가 들어 있어요. 차트의 기본 보안 모델은 모든 Linux capability를 제거하고 권한 상승을 금지합니다. 이 값을 바꾸지 않는 것을 권장합니다.

리스너 Service 값

차트는 API, cluster, ops 리스너에 대해 별도의 Service를 만듭니다.

API Service 값

Key Default Description
controller.service.api.type LoadBalancer Boundary API 트래픽용 Kubernetes Service 유형
controller.service.api.port 9200 API 트래픽용 Service 포트
controller.service.api.targetPort 9200 API Service가 대상으로 하는 컨테이너 포트. controller.config의 API 리스너와 일치해야 함.
controller.service.api.annotations {} API Service에 추가되는 어노테이션

Cluster Service 값

Key Default Description
controller.service.cluster.type ClusterIP worker 등록 및 컨트롤러 클러스터 트래픽용 Kubernetes Service 유형
controller.service.cluster.port 9201 클러스터 트래픽용 Service 포트
controller.service.cluster.targetPort 9201 cluster Service가 대상으로 하는 컨테이너 포트. controller.config의 cluster 리스너와 일치해야 함.
controller.service.cluster.annotations {} cluster Service에 추가되는 어노테이션

Ops Service 값

Key Default Description
controller.service.ops.type ClusterIP 상태 및 메트릭 트래픽용 Kubernetes Service 유형
controller.service.ops.port 9203 ops 엔드포인트용 Service 포트
controller.service.ops.targetPort 9203 ops Service가 대상으로 하는 컨테이너 포트. controller.config의 ops 리스너와 일치해야 함.
controller.service.ops.annotations {} ops Service에 추가되는 어노테이션

신뢰할 수 있는 모니터링 경로가 다른 노출 모델을 요구하지 않는 한, ops Service는 내부로 유지하세요.

프로브 값

controller.config에 ops TCP 리스너가 정의되어 있으면 차트가 자동으로 liveness와 readiness 프로브를 추가해요. 스킴이 제공되지 않으면 차트는 controller.config의 ops 리스너 tls_disable 설정에서 파생합니다: tls_disable=false면 HTTPS, tls_disable=true면 HTTP.

Key Default Description
controller.livenessProbe.scheme "" /health용 프로브 스킴. 제공되지 않으면 controller.config의 ops 리스너 tls_disable에서 파생: tls_disable=false면 HTTPS, tls_disable=true면 HTTP. 필요하면 재정의.
controller.livenessProbe.initialDelaySeconds 60 초기 liveness 프로브 지연
controller.livenessProbe.periodSeconds 10 liveness 프로브 주기
controller.livenessProbe.failureThreshold 3 liveness 프로브 실패 임계값
controller.livenessProbe.timeoutSeconds 5 liveness 프로브 타임아웃
controller.readinessProbe.scheme "" /health용 readiness 프로브 스킴. 제공되지 않으면 controller.config의 ops 리스너 tls_disable에서 파생: tls_disable=false면 HTTPS, tls_disable=true면 HTTP. 필요하면 재정의.
controller.readinessProbe.initialDelaySeconds 15 초기 readiness 프로브 지연
controller.readinessProbe.periodSeconds 10 readiness 프로브 주기
controller.readinessProbe.failureThreshold 3 readiness 프로브 실패 임계값
controller.readinessProbe.timeoutSeconds 5 readiness 프로브 타임아웃

리소스 값

Key Default Description
controller.resources.requests.cpu 250m 컨트롤러 컨테이너 CPU 요청
controller.resources.requests.memory 512Mi 컨트롤러 컨테이너 메모리 요청
controller.resources.limits.cpu 500m 컨트롤러 컨테이너 CPU 제한
controller.resources.limits.memory 1Gi 컨트롤러 컨테이너 메모리 제한

예상 API 부하, worker 규모, 세션 조정, 감사 이벤트 규모에 맞게 리소스 값을 튜닝하세요.

데이터베이스 Job 값

차트는 데이터베이스 초기화, 마이그레이션, 선택적 복구에 hook Job을 사용해요.

Key Default Description
database.init.enabled false 사전 설치 데이터베이스 초기화 Job 실행
database.migrate.enabled false 사전 업그레이드 데이터베이스 마이그레이션 Job 실행
database.repair.version "" database.migrate.enabled=true와 함께 설정하면 지정된 버전에 대한 사전 업그레이드 복구 마이그레이션 Job도 실행
database.resources.requests.cpu 100m 데이터베이스 Job CPU 요청
database.resources.requests.memory 128Mi 데이터베이스 Job 메모리 요청
database.resources.limits.cpu 500m 데이터베이스 Job CPU 제한
database.resources.limits.memory 512Mi 데이터베이스 Job 메모리 제한

초기화 Job은 idempotent(멱등)해요. 데이터베이스가 이미 초기화되어 있으면 Job은 성공적으로 종료됩니다.

Bootstrap admin 값

부트스트랩 admin Job은 Boundary 복구 권한을 사용해 global password 인증 방법, 사용자, 계정, 역할을 생성하거나 업데이트해요.

Key Default Description
bootstrapAdmin.enabled false 설치 후 부트스트랩 admin Job 실행
bootstrapAdmin.runOnUpgrade false true이면 업그레이드 후에도 부트스트랩 admin Job 실행
bootstrapAdmin.waitTimeoutSeconds 120 부트스트랩 Job이 컨트롤러 API에 도달하기까지 기다리는 최대 시간
bootstrapAdmin.authMethodName bootstrap-auth-method Job이 생성하거나 재사용하는 password 인증 방법 이름
bootstrapAdmin.userResourceName bootstrap-admin Job이 생성하거나 재사용하는 Boundary 사용자 리소스 이름
bootstrapAdmin.accountResourceName bootstrap-admin Job이 생성하거나 재사용하는 Boundary 계정 리소스 이름
bootstrapAdmin.roleName bootstrap-global-admin Job이 생성하거나 재사용하는 Boundary 역할 이름
bootstrapAdmin.resources.requests.cpu 100m 부트스트랩 Job CPU 요청
bootstrapAdmin.resources.requests.memory 128Mi 부트스트랩 Job 메모리 요청
bootstrapAdmin.resources.limits.cpu 500m 부트스트랩 Job CPU 제한
bootstrapAdmin.resources.limits.memory 512Mi 부트스트랩 Job 메모리 제한

차트 바깥에서 Boundary 인증 방법과 admin 주체를 이미 관리한다면 이 Job을 비활성화하세요.

추가 환경 변수

Key Default Description
extraEnv [] 컨트롤러와 hook Job 컨테이너에 주입되는 추가 환경 변수. 유효한 Kubernetes env 항목을 모두 지원.

보안 컨텍스트 값

기본 보안 설정은 상승된 권한 없이 컨트롤러를 실행합니다.

Key Default
podSecurityContext.runAsNonRoot true
podSecurityContext.runAsUser 100
podSecurityContext.runAsGroup 1000
podSecurityContext.fsGroup 1000
podSecurityContext.fsGroupChangePolicy OnRootMismatch
podSecurityContext.seccompProfile.type RuntimeDefault
containerSecurityContext.runAsNonRoot true
containerSecurityContext.runAsUser 100
containerSecurityContext.runAsGroup 1000
containerSecurityContext.allowPrivilegeEscalation false
containerSecurityContext.readOnlyRootFilesystem true
containerSecurityContext.capabilities.drop ALL
containerSecurityContext.seccompProfile.type RuntimeDefault

Deployment와 Job은 또한 SKIP_SETCAP=1을 설정해서, 컨테이너 시작 경로가 Linux capability 수정을 시도하지 못하게 합니다.

ServiceAccount 값

Key Default Description
serviceAccount.name default Deployment와 hook Job이 사용하는 기존 ServiceAccount. 차트는 ServiceAccount를 생성하지 않음.
serviceAccount.automountServiceAccountToken false 포드 service account 토큰을 마운트할지 제어

가용성 및 종료 값

Key Default Description
podDisruptionBudget.enabled true 컨트롤러 포드용 PodDisruptionBudget 생성
podDisruptionBudget.minAvailable 1 자발적 중단 중 최소 사용 가능 컨트롤러 포드 수
podDisruptionBudget.maxUnavailable not set minAvailable의 선택적 대안. 둘 중 하나만 사용.
terminationGracePeriodSeconds 15 SIGKILL 전 Kubernetes 종료 유예 기간. controller.config의 graceful_shutdown_wait_duration보다 커야 함.

스케줄링 값

Key Default Description
podAnnotations {} 추가 포드 어노테이션
nodeSelector {} 노드 선택기 제약
tolerations [] 포드 톨러레이션
affinity {} 포드 어피니티 규칙

구성 정렬 체크리스트

컨트롤러를 설치하거나 업그레이드하기 전에 다음을 확인하세요:

  • controller.config의 API 리스너 포트가 controller.service.api.targetPort와 일치
  • controller.config의 cluster 리스너 포트가 controller.service.cluster.targetPort와 일치
  • controller.config의 ops 리스너 포트가 controller.service.ops.targetPort와 일치
  • public_cluster_addr 설정이 worker가 실제로 도달할 수 있는 엔드포인트와 일치
  • TLS가 활성화될 때 tls_cert_file과 tls_key_file 설정이 tls.mountPath와 일치
  • 프로브 스킴이 제공되지 않으면 controller.config의 ops 리스너 tls_disable에서 파생. 파생된 스킴이 리스너 구성과 맞지 않을 때만 재정의.
  • 참조된 Secret이 현재 controller.config와 부트스트랩 설정이 요구하는 모든 키를 담고 있는지
  • terminationGracePeriodSeconds 설정이 컨트롤러 HCL의 graceful_shutdown_wait_duration을 초과하는지

문제 해결

컨트롤러 포드가 readiness 또는 liveness 프로브에 실패

TLS 설정을 바꾼 뒤 컨트롤러 포드가 readiness나 liveness 프로브에 실패하면, controller.livenessProbe.scheme이나 controller.readinessProbe.scheme이 controller.config의 ops 리스너 tls_disable 설정과 일치하는지 확인하세요. 프로브 스킴을 명시적으로 설정하지 않으면 차트는 tls_disable에서 파생합니다(tls_disable=false면 HTTPS, tls_disable=true면 HTTP). 프로브 스킴을 수동으로 재정의했다면, tls_disable을 바꿀 때마다 ops 리스너와 정렬된 상태를 유지하세요.

더 알아보기 (Learn more)