Worker values
Worker values
Boundary worker Helm 차트는 Helm values와 Boundary HCL 구성으로 설정해요. 지원되는 값의 출처(source of truth)는 차트 자체입니다.
본문
Boundary 런타임 구성
worker.config는 Boundary worker HCL을 담고 있어요. 차트는 이 값을 ConfigMap에 쓰고 /etc/boundary/boundary-worker.hcl에 마운트합니다.
차트는 Helm의 tpl 함수로 worker.config를 렌더링합니다. HCL 안의 Helm 템플릿 표현식은 렌더링 중에 평가돼요.
컨테이너 시작 시 차트는 ${POD_NAME_LOWER}를 소문자로 변환한 포드 이름으로 바꾸고, 처리된 구성 파일로 Boundary를 시작합니다.
차트는 Boundary HCL 의미론을 검증하지 않아요. 유효한 리스너, 등록 설정, 업스트림, 스토리지 경로, worker 태그를 구성하는 것은 사용자 책임입니다.
Kubernetes 인프라 구성
Kubernetes 관련 값은 Deployment, Services, PVCs, 보안 컨텍스트, 스케줄링 옵션을 제어해요. 이 값들은 Boundary 런타임 HCL을 대체하거나 생성하지 않습니다.
예를 들어 worker.service.proxy.targetPort를 9222로 바꾸면, worker.config의 proxy 리스너 포트도 함께 업데이트해야 해요. 변경을 확정하기 전에 구성 정렬 체크리스트를 참고하세요.
다음 절은 기능별로 그룹화된 모든 사용 가능한 Helm 값을 설명합니다. 각 표는 키, 기본값, 설명을 나열해요.
이미지 값
| Key | Default | Description |
|---|---|---|
| image.repository | hashicorp/boundary-enterprise | worker 컨테이너 이미지 리포지토리 |
| image.tag | "" | worker 이미지 태그. 비어 있으면 Chart.appVersion(현재 1.0.0-ent) 사용. |
| image.pullPolicy | IfNotPresent | Kubernetes 이미지 풀 정책 |
| imagePullSecrets | [] | 프라이빗 레지스트리용 선택적 이미지 풀 시크릿 |
worker 런타임 값
| Key | Default | Description |
|---|---|---|
| worker.config | Embedded sample HCL | ConfigMap에 저장되고 worker 컨테이너에 마운트되는 Boundary worker HCL. 설치 전에 플레이스홀더를 교체하세요. |
| worker.terminationGracePeriodSeconds | 7200 | 포드 종료 유예 기간(초). 강제 종료 전에 오래 실행되는 세션이 드레인될 시간을 줌. |
기본 worker.config에는 disable_mlock = true가 들어 있어요. 차트의 기본 보안 모델은 모든 Linux capability를 제거하고 권한 상승을 금지합니다. 이 값을 바꾸지 않는 것을 권장합니다. 메모리 잠금에는 차트가 부여하지 않는 상승된 권한이 필요해요. 노드에서 스왑을 활성화한다면, 그로 인한 data-at-rest 노출을 플랫폼 제어를 통해 처리하세요.
프로브 값
차트는 ops 리스너의 /health 엔드포인트에 liveness와 readiness 프로브를 추가합니다.
| Key | Default | Description |
|---|---|---|
| worker.livenessProbe.scheme | HTTP | ops 리스너의 /health용 프로브 스킴 |
| worker.livenessProbe.initialDelaySeconds | 10 | 초기 liveness 프로브 지연 |
| worker.livenessProbe.periodSeconds | 10 | liveness 프로브 주기 |
| worker.livenessProbe.failureThreshold | 3 | liveness 프로브 실패 임계값 |
| worker.livenessProbe.timeoutSeconds | 5 | liveness 프로브 타임아웃 |
| worker.readinessProbe.scheme | HTTP | ops 리스너의 /health용 readiness 프로브 스킴 |
| worker.readinessProbe.initialDelaySeconds | 10 | 초기 readiness 프로브 지연 |
| worker.readinessProbe.periodSeconds | 10 | readiness 프로브 주기 |
| worker.readinessProbe.failureThreshold | 3 | readiness 프로브 실패 임계값 |
| worker.readinessProbe.timeoutSeconds | 5 | readiness 프로브 타임아웃 |
Proxy Service 값
Proxy Service는 worker의 세션 트래픽 리스너를 노출합니다.
| Key | Default | Description |
|---|---|---|
| worker.service.proxy.enabled | true | 활성화되면 proxy Service 생성 |
| worker.service.proxy.type | LoadBalancer | proxy 트래픽용 Kubernetes Service 유형 |
| worker.service.proxy.port | 9202 | proxy 트래픽용 Service 포트 |
| worker.service.proxy.targetPort | 9202 | proxy Service가 대상으로 하는 컨테이너 포트. worker.config의 proxy 리스너와 일치해야 함. |
| worker.service.proxy.annotations | {} | proxy Service에 추가되는 어노테이션. proxy Service 유형이 LoadBalancer가 아니면 AWS 로드 밸런서 어노테이션은 자동으로 생략됨. |
Operations Service 값
Operations Service는 상태와 메트릭용 worker operations 리스너를 노출합니다.
| Key | Default | Description |
|---|---|---|
| worker.service.ops.enabled | true | 활성화되면 operations Service 생성 |
| worker.service.ops.type | ClusterIP | operations 트래픽용 Kubernetes Service 유형 |
| worker.service.ops.port | 9203 | operations 엔드포인트용 Service 포트 |
| worker.service.ops.targetPort | 9203 | operations Service가 대상으로 하는 컨테이너 포트. worker.config의 ops 리스너와 일치해야 함. |
| worker.service.ops.annotations | {} | operations Service에 추가되는 어노테이션 |
신뢰할 수 있는 모니터링 경로가 다른 노출 모델을 요구하지 않는 한, operations Service는 내부로 유지하세요.
리소스 값
| Key | Default | Description |
|---|---|---|
| worker.resources.requests.cpu | 100m | worker 컨테이너 CPU 요청 |
| worker.resources.requests.memory | 512Mi | worker 컨테이너 메모리 요청 |
| worker.resources.limits.cpu | 200m | worker 컨테이너 CPU 제한 |
| worker.resources.limits.memory | 1Gi | worker 컨테이너 메모리 제한 |
예상 연결 규모, 녹화 사용량, 클러스터 규모에 맞게 리소스 값을 튜닝하세요.
Auth 스토리지 값
Auth 스토리지는 로컬 영속성이 필요한 등록 모델을 위해 worker 아이덴티티와 인증 자료를 저장합니다.
| Key | Default | Description |
|---|---|---|
| worker.persistence.authStorage.enabled | false | 활성화되면 auth 스토리지 PVC를 생성하고 마운트. 비활성화되면 auth 스토리지 경로에 emptyDir을 마운트. |
| worker.persistence.authStorage.size | 1Gi | auth 스토리지 PVC 크기 |
| worker.persistence.authStorage.accessMode | ReadWriteOnce | auth 스토리지 PVC 접근 모드 |
| worker.persistence.authStorage.storageClass | "" | auth 스토리지 PVC용 StorageClass. 비어 있으면 클러스터 기본값 사용. |
| worker.persistence.authStorage.path | /var/lib/boundary | auth 스토리지 마운트 경로. worker.config의 auth_storage_path와 일치해야 함. |
| worker.persistence.authStorage.retainOnUninstall | true | helm uninstall 후 auth 스토리지 PVC 보존. 삭제하려면 false로 설정. |
worker 인증 모델이 영구적인 로컬 auth 자료를 요구하지 않을 때(KMS 기반 worker 인증 같은 경우)에만 auth 스토리지를 비활성화하세요.
녹화 스토리지 값
녹화 스토리지는 Boundary에서 녹화가 구성되어 있을 때 세션 녹화를 저장합니다.
| Key | Default | Description |
|---|---|---|
| worker.persistence.recording.enabled | false | 활성화되면 녹화 PVC를 생성하고 마운트 |
| worker.persistence.recording.size | 10Gi | 녹화 PVC 크기 |
| worker.persistence.recording.accessMode | ReadWriteOnce | 녹화 PVC 접근 모드 |
| worker.persistence.recording.storageClass | "" | 녹화 PVC용 StorageClass. 비어 있으면 클러스터 기본값 사용. |
| worker.persistence.recording.path | /boundary/recording | 녹화 스토리지 마운트 경로. 녹화가 활성화되면 worker.config의 recording_storage_path와 일치해야 함. |
| worker.persistence.recording.retainOnUninstall | true | helm uninstall 후 녹화 PVC 보존. 삭제하려면 false로 설정. |
녹화 스토리지를 비활성화하면 HCL에서 recording_storage_path를 제거하거나 녹화 데이터가 영속될 필요가 없는지 확인하세요.
Secret 참조 값
차트는 기존 Kubernetes Secret의 값을 worker 컨테이너에 환경 변수로 주입합니다. 컨트롤러가 생성한 활성화 토큰 같은 민감한 값을 worker.config에 넣지 않고 제공할 때 사용해요.
| Key | Default | Description |
|---|---|---|
| secretRefs.secretName | "" | worker 컨테이너에 주입할 기존 Kubernetes Secret 이름. 비어 있으면 Secret을 마운트하지 않음. |
| secretRefs.validateExisting | false | true이면 참조된 Secret이 없거나 필수 키가 없을 때 Helm이 일찍 실패. |
| secretRefs.keys.controllerGeneratedActivationToken | worker-controller-generated-activation-token | BOUNDARY_WORKER_CONTROLLER_GENERATED_ACTIVATION_TOKEN에 사용하는 Secret의 키. Kubernetes Secret의 키 이름과 일치해야 함. |
Controller-led 등록에 Secret을 사용하려면 worker.config에서 controller_generated_activation_token = "env://BOUNDARY_WORKER_CONTROLLER_GENERATED_ACTIVATION_TOKEN"을 설정하고, secretRefs.secretName을 토큰 키가 들어 있는 Secret으로 지정하세요.
추가 환경 변수
extraEnv를 사용해서 worker 컨테이너에 추가 환경 변수를 주입할 수 있어요. 일반 name/value 쌍과 valueFrom 참조를 포함한 유효한 Kubernetes env 항목을 모두 지원합니다.
| Key | Default | Description |
|---|---|---|
| extraEnv | [] | worker 컨테이너에 주입되는 추가 환경 변수 목록 |
일반 값 사용 예시:
extraEnv:
- name: BOUNDARY_WORKER_CONTROLLER_GENERATED_ACTIVATION_TOKEN
value: "act_1234abcd..."
Secret 참조 사용 예시:
extraEnv:
- name: BOUNDARY_WORKER_CONTROLLER_GENERATED_ACTIVATION_TOKEN
valueFrom:
secretKeyRef:
name: boundary-worker-secrets
key: worker-controller-generated-activation-token
Secret 키를 환경 변수 이름에 매핑하는 방식을 더 세밀하게 제어해야 하거나, 활성화 토큰과 무관한 변수를 주입할 때는 secretRefs의 대안으로 extraEnv를 사용하세요.
보안 컨텍스트 값
기본 보안 설정은 상승된 권한 없이 worker를 실행합니다.
| 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는 또한 SKIP_SETCAP=1을 설정해서, 컨테이너 시작 경로가 Linux capability 수정을 시도하지 못하게 합니다.
ServiceAccount 값
| Key | Default | Description |
|---|---|---|
| serviceAccount.create | false | true이면 worker Deployment와 PVC Jobs용 ServiceAccount 생성. false이면 serviceAccount.name이 가리키는 ServiceAccount 사용. |
| serviceAccount.name | "" | 사용하거나 만들 ServiceAccount 이름. 비어 있고 serviceAccount.create=true면 차트는 릴리스 fullname을 사용. |
| serviceAccount.annotations | {} | ServiceAccount에 추가되는 어노테이션. 클라우드 프로바이더 KMS(키 관리 시스템) 접근을 위한 IRSA(IAM Roles for Service Accounts, eks.amazonaws.com/role-arn) 또는 Workload Identity(iam.gke.io/gcp-service-account) 어노테이션을 붙이는 데 사용. |
| serviceAccount.automountServiceAccountToken | false | 포드 service account 토큰을 마운트할지 제어. IRSA나 Workload Identity를 쓸 때 true로 설정. |
스케줄링 값
| Key | Default | Description |
|---|---|---|
| podAnnotations | {} | 추가 포드 어노테이션 |
| nodeSelector | {} | 노드 선택기 제약 |
| tolerations | [] | 포드 톨러레이션 |
| affinity | {} | 포드 어피니티 규칙 |
구성 정렬 체크리스트
설치하거나 업그레이드하기 전에 다음을 확인하세요:
worker.config의 proxy 리스너 포트가worker.service.proxy.targetPort와 일치worker.config의 ops 리스너 포트가worker.service.ops.targetPort와 일치- auth 스토리지가 활성화될 때
auth_storage_path가worker.persistence.authStorage.path와 일치 - 녹화 스토리지가 활성화될 때
recording_storage_path가worker.persistence.recording.path와 일치 public_addr이 다른 Boundary 클라이언트나 worker가 실제로 도달할 수 있는 엔드포인트와 일치- 플레이스홀더 활성화 토큰, 클러스터 ID, 업스트림 주소가 교체되었는지
문제 해결
auth 스토리지 활성화 후 worker가 크래시-루프
auth 스토리지를 활성화한 뒤 worker 포드가 크래시-루프하면, worker.config의 auth_storage_path가 worker.persistence.authStorage.path로 설정한 마운트된 PVC 경로와 일치하는지 확인하세요. 둘이 불일치하면 worker는 기대 위치에서 아이덴티티 자료를 읽거나 쓸 수 없습니다.
더 알아보기 (Learn more)
- 예시 worker 구성을 보려면 Worker Helm chart 예시를 참고하세요.
- 이 값을 사용해 worker를 설치하려면 Helm 차트로 worker 배포하기를 참고하세요.