Helm 차트로 worker 배포하기

Helm 차트로 worker 배포하기 (Deploy workers using a Helm chart)

worker 차트는 Helm 릴리스 하나당 셀프 매니지드 Boundary worker를 하나 설치합니다. HCP Boundary나 셀프 매니지드 Boundary 배포에서 쓰는 worker를 포함해, egress와 intermediate worker 사용 사례에 초점을 맞춰요.

worker 차트는 worker.config에 제공한 worker HCL을 마운트하고, 선택적인 proxy와 ops 서비스를 노출하며, auth 스토리지와 세션 녹화 스토리지용 선택적 PVC를 프로비저닝합니다.

Boundary worker Helm 차트를 배포하면 컨트롤러나 HCP(HashiCorp Cloud Platform) Boundary에 등록되는 실행 중인 데이터 플레인 worker를 얻게 돼요. 타깃으로의 세션 트래픽을 프록시할 준비가 된 상태입니다. 이 페이지는 worker 차트 설치만 다룹니다. 컨트롤 플레인을 먼저 구성하려면 Helm 차트로 컨트롤러 배포하기를 참고하세요.

출처: HashiCorp Boundary docs

본문

사전 요구 사항

worker Helm 차트를 설치하기 전에 다음이 준비되어 있는지 확인하세요:

• 기본 StorageClass 또는 사전 프로비저닝된 PersistentVolume이 있는 버전 1.34 이상의 Kubernetes 클러스터
• 대상 Kubernetes 클러스터에 접근하도록 구성된 Helm 3 이상
• worker 포드에서 HCP Boundary 클러스터 또는 셀프 매니지드 Boundary 업스트림 worker로의 네트워크 연결
• 유효한 Boundary worker HCL 구성
• 설치 전에 선택한 등록 모델:

등록 모델	요구 사항	가장 적합한 환경
Controller-led 등록	컨트롤러가 생성한 활성화 토큰	컨트롤러 운영자가 worker가 시작하기 전에 토큰을 발급하는 환경
Worker-led 등록	첫 시작 중 포드 로그에 출력되는 토큰	worker가 먼저 시작하고 운영자가 로그에서 토큰을 가져와 등록을 완료하는 환경
KMS 기반 worker 인증	KMS(키 관리 시스템) worker auth용으로 구성된 셀프 매니지드 Boundary 배포	worker 인증에 공유 KMS 키를 이미 사용하는 셀프 매니지드 배포

intermediate worker는 proxy 리스너의 도달 가능한 엔드포인트와 선택한 Service 유형(예: LoadBalancer)에 대한 클러스터 지원이 필요할 수도 있어요.

HashiCorp Helm 리포지토리 추가

Helm 리포지토리를 추가하고 차트가 보이는지 확인합니다:

$ helm repo add hashicorp https://helm.releases.hashicorp.com; \
  helm search repo hashicorp/boundary-worker

예시 출력:

NAME                      CHART VERSION   APP VERSION   DESCRIPTION
hashicorp/boundary-worker 0.1.0           1.0.0         Official HashiCorp Boundary Worker Helm Chart

worker 구성 준비

차트는 worker.config에서 원시 Boundary HCL을 읽습니다. values 파일의 worker.config 키 아래에 HCL을 인라인으로 넣고 --values로 그 파일을 전달하세요.

기본 worker 구성은 worker 구성 생성 참조의 안내를 참고하세요. 사용 가능한 worker 구성은 다음을 포함합니다:

• 세션 트래픽용 proxy 리스너
• 상태와 메트릭용 ops 리스너
• worker 등록 메커니즘
• HCP Boundary용 hcp_boundary_cluster_id 또는 업스트림 worker·컨트롤러용 initial_upstreams
• auth 스토리지 영속성을 활성화한 경우 auth_storage_path
• 세션 녹화 영속성을 활성화한 경우 recording_storage_path
• 다른 클라이언트나 worker가 이 worker에 연결해야 할 때 public_addr

HCP Boundary worker 구성 예시:

disable_mlock = true

listener "tcp" {
  address = "0.0.0.0:9202"
  purpose = "proxy"
}

listener "tcp" {
  address     = "0.0.0.0:9203"
  purpose     = "ops"
  tls_disable = true
}

worker {
  name = "boundary-worker"
  public_addr = ""
  initial_upstreams = ["boundary-controller-cluster:9201"]

  tags {
    type = ["worker", "kled", "tests"]
  }
}

kms "aead" {
  purpose = "worker-auth"
  aead_type = "aes-gcm"
  key = "ATTK2pMjMTEJGlAkUJAePnFMlNLQaXBnhSqJHVlJeKQ="
  key_id = "global_worker-auth"
}

events {
  audit_enabled       = true
  sysevents_enabled   = true
  observations_enable = true
  sink "stderr" {
    name        = "all-events"
    description = "All events sent to stderr"
    event_types = ["*"]
    format      = "cloudevents-json"
  }
}

Note — 이 인라인 AEAD KMS 예시는 개발이나 테스트에 적합합니다. 키가 구성 파일을 읽을 수 있는 누구에게나 보여요. 프로덕션에는 KMS 구성에서 설명한 대로 외부 KMS를 사용하세요.

차트 기본값인 disable_mlock = true를 바꾸지 않는 것을 권장합니다. 컨테이너는 메모리 잠금에 필요한 상승된 권한 없이 실행되니까요.

사용 가능한 차트 버전 나열

worker 차트의 게시된 버전을 보려면 다음 명령을 사용하세요:

$ helm search repo hashicorp/boundary-worker --versions

Boundary worker 설치

worker.config와 Kubernetes 오버라이드가 들어 있는 values 파일을 만드세요:

worker:
  config: |
    disable_mlock = true

    listener "tcp" {
      address = "0.0.0.0:9202"
      purpose = "proxy"
    }

    listener "tcp" {
      address     = "0.0.0.0:9203"
      purpose     = "ops"
      tls_disable = true
    }

    worker {
      name = "boundary-worker"
      public_addr = ""
      initial_upstreams = ["boundary-controller-cluster:9201"]

      tags {
        type = ["worker", "kled", "tests"]
      }
    }

    kms "aead" {
      purpose = "worker-auth"
      aead_type = "aes-gcm"
      key = "ATTK2pMjMTEJGlAkUJAePnFMlNLQaXBnhSqJHVlJeKQ="
      key_id = "global_worker-auth"
    }

  persistence:
    authStorage:
      storageClass: ""
    recording:
      enabled: true
      storageClass: ""

릴리스를 설치하려면 다음 명령을 실행해요:

$ helm install boundary-worker hashicorp/boundary-worker \
  --version 0.1.0 \
  --namespace boundary \
  --create-namespace \
  --values my-values.yaml \
  --wait

예시 출력:

NAME: boundary-worker
LAST DEPLOYED: Tue Jul 22 00:00:00 2026
NAMESPACE: boundary
STATUS: deployed
REVISION: 1

배포 검증

설치 후 렌더링된 리소스를 확인합니다:

$ kubectl get deployment,pods,svc,pvc --namespace boundary; \
  kubectl logs --namespace boundary deployment/boundary-worker-deployment

예시 출력:

NAME                                          READY   STATUS    RESTARTS   AGE
pod/boundary-worker-deployment-abcde          1/1     Running   0          2m

NAME                            TYPE           CLUSTER-IP   EXTERNAL-IP   PORT(S)          AGE
service/boundary-worker-proxy   LoadBalancer   10.0.0.20    203.0.113.9   9202:31500/TCP   2m
service/boundary-worker-ops     ClusterIP      10.0.0.21            9203/TCP         2m

NAME                                      STATUS   VOLUME     CAPACITY   ACCESS MODES   AGE
persistentvolumeclaim/boundary-worker-pvc Bound     pvc-1234   1Gi        RWO            2m

다음을 확인하세요:

• 포드가 Ready가 됨
• 활성화된 PVC가 Bound됨
• proxy와 ops 서비스가 의도한 노출 모델과 일치
• worker 로그에 성공적인 등록 또는 인증이 표시됨
• worker가 Boundary에서 활성 상태로 나타나고 세션 할당 자격을 갖춤

worker의 public_addr 업데이트

worker.service.proxy.type이 LoadBalancer일 때 Kubernetes는 설치 후 외부 호스트 이름이나 IP를 할당할 수 있어요. worker.service.proxy.type이 ClusterIP라면, worker를 내부에서 접근할 때 클러스터에서 도달 가능한 주소를 사용하세요.

다음 명령으로 proxy Service를 지켜봅니다:

$ kubectl get svc boundary-worker-proxy --namespace boundary --watch

worker HCL에 최종 주소가 필요하다면, worker.config나 HCL 파일의 public_addr 필드를 LoadBalancer 주소나 내부 ClusterIP 주소로 업데이트한 다음 릴리스를 업그레이드하세요:

$ helm upgrade boundary-worker hashicorp/boundary-worker \
  --version 0.1.0 \
  --namespace boundary \
  --values my-values.yaml \
  --rollback-on-failure \
  --wait

worker 제거

worker Helm 릴리스와 관련 Kubernetes 리소스를 제거하려면 다음을 실행하세요:

$ helm uninstall boundary-worker --namespace boundary

문제 해결

worker가 활성 상태가 되지 않음

설치 후 worker가 Boundary에서 활성으로 나타나지 않으면, worker.config의 initial_upstreams가 올바른 컨트롤러 클러스터 주소(HCP Boundary라면 hcp_boundary_cluster_id)를 가리키는지 확인하세요. 잘못된 업스트림 주소로 구성된 worker는 등록을 완료하지 못하고 비활성 상태에 머무릅니다.

더 알아보기 (Learn more)

• worker를 구성하거나 업데이트하기 위한 지원되는 Helm 값은 Worker values를 참고하세요.
• 예시 구성을 보려면 Worker Helm chart 예시를 참고하세요.