Worker Helm 차트 예시

Worker Helm 차트 예시 (Worker Helm chart examples)

이 worker 구성 변형들 — ingress, intermediate, egress 토폴로지, DNS 기반 주소 지정, 등록 방법 — 을 사용해서 worker를 네트워크 위치에 맞게 조정할 수 있어요. Boundary 컨트롤러나 HCP Boundary 클러스터가 이미 존재한다고 가정합니다.

토폴로지	연결을 받는 곳	일반적 Service 유형	public_addr 필요
Ingress	다운스트림 worker 및 클라이언트	LoadBalancer	예
Intermediate	업스트림 및 다운스트림 worker	LoadBalancer	예
Egress	업스트림 또는 intermediate worker; 타깃에 연결	ClusterIP (proxy는 보통 비활성화)	아니요

출처: HashiCorp Boundary docs

본문

Ingress 기능이 있는 worker

Ingress worker는 다운스트림 worker와 클라이언트로부터의 연결을 받아들여요. 흔히 컨트롤러 클러스터를 업스트림으로 사용하고, LoadBalancer Service를 통해 proxy 리스너를 공개적으로 노출합니다.

Ingress 기능이 있는 worker용 예시 HCL:

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 = "boundary-worker.example.com:9202"
  initial_upstreams = ["<boundary-controller-cluster:9201>"]

  tags {
    type = ["worker", "ingress"]
  }
}

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

events {
  audit_enabled       = true
  sysevents_enabled   = true
  observations_enabled = true
  sink "stderr" {
    name        = "all-events"
    event_types = ["*"]
    format      = "cloudevents-json"
  }
}

Ingress 기능과 공개 LoadBalancer가 있는 worker용 예시 values:

worker:
  service:
    proxy:
      enabled: true
      type: LoadBalancer
      port: 9202
      targetPort: 9202
    ops:
      enabled: true
      type: ClusterIP
      port: 9203
      targetPort: 9203
  persistence:
    authStorage:
      enabled: false
    recording:
      enabled: false

worker Helm 차트를 설치합니다:

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

로드 밸런서가 생길 때까지 public_addr을 알 수 없다면, 외부 주소를 기다리세요:

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

예시 출력:

NAME                     TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)          AGE
boundary-worker-proxy    LoadBalancer   10.0.0.30             9202:31600/TCP   10s
boundary-worker-proxy    LoadBalancer   10.0.0.30      203.0.113.20    9202:31600/TCP   45s

ingress-worker.hcl의 public_addr을 업데이트한 다음 업그레이드합니다:

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

Intermediate 기능이 있는 worker

Intermediate 기능이 있는 worker는 업스트림과 다운스트림 worker 사이의 트래픽을 중계해요. initial_upstreams와 public_addr이 모두 필요합니다.

Intermediate 기능이 있는 worker용 예시 HCL:

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 = ["<ingress-or-intermediate-worker-address>:9202"]

  tags {
    type = ["worker", "intermediate"]
  }
}

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"
    event_types = ["*"]
    format      = "cloudevents-json"
  }
}

Intermediate 기능과 LoadBalancer가 있는 worker용 예시 values:

worker:
  service:
    proxy:
      enabled: true
      type: LoadBalancer
      port: 9202
      targetPort: 9202
    ops:
      enabled: true
      type: ClusterIP
      port: 9203
      targetPort: 9203
  persistence:
    authStorage:
      enabled: false
    recording:
      enabled: false

worker Helm 차트를 설치합니다:

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

로드 밸런서가 생길 때까지 public_addr을 알 수 없다면 외부 주소를 기다리세요(ingress 기능이 있는 worker의 예시 출력 참고):

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

intermediate-worker.hcl의 public_addr을 업데이트한 다음 업그레이드합니다:

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

Egress 기능이 있는 worker

Egress 기능이 있는 worker는 타깃 시스템에 연결하며 보통 타깃 직전의 마지막 홉이에요. 종종 public_addr이 필요하지 않습니다.

Egress 기능이 있는 worker용 예시 HCL:

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 = ["<ingress-or-intermediate-worker-address>:9202"]

  tags {
    type = ["worker", "egress"]
  }
}

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"
    event_types = ["*"]
    format      = "cloudevents-json"
  }
}

Egress 기능이 있는 worker용 예시 values:

worker:
  service:
    proxy:
      enabled: false
    ops:
      enabled: true
      type: ClusterIP
  persistence:
    authStorage:
      enabled: false
    recording:
      enabled: false

worker 구성을 포함한 values 파일로 worker를 설치합니다:

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

사전 구성된 DNS 주소가 있는 worker

worker에 대한 DNS 이름을 이미 관리하고 있다면, 설치 중에 public_addr을 설정하세요:

worker {
  name = "boundary-worker"
  public_addr = "https://boundary-worker.example.com:9202"
  initial_upstreams = ["boundary-controller-cluster:9201"]

  tags {
    type = ["worker", "ingress"]
  }
}

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

Service가 외부 주소를 받은 뒤 DNS 레코드를 그 주소로 지정하세요. 이렇게 하면 설치 후 worker HCL을 바꿀 필요가 없지만, DNS가 도달 가능한 worker 엔드포인트로 해석되는지는 사용자가 책임져야 해요.

Worker-led 등록

Worker-led 등록에서는 컨트롤러가 생성한 활성화 토큰 없이 worker를 설치합니다. worker가 시작 시 아이덴티티 자료를 생성하고 등록 정보를 포드 로그에 기록해요. 자세한 내용은 Worker-led registration을 참고하세요.

Worker-led 등록용 예시 HCL:

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 {
  public_addr = ""
  initial_upstreams = ["boundary-controller-cluster:9201"]
  auth_storage_path = "/var/lib/boundary"

  tags {
    type = ["worker", "worker-led"]
  }
}

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

Auth 스토리지 영속성이 있는 worker-led 등록용 예시 values:

worker:
  persistence:
    authStorage:
      enabled: true
      size: 1Gi

일반적인 워크플로는 다음과 같아요:

• worker.config에 worker-led 등록 설정을 넣고 worker 차트 설치
• worker 포드 로그 읽기
• 발생한 worker 등록 정보를 Boundary에 등록하거나 승인
• worker가 활성 상태가 되는지 확인

로그 보기:

$ kubectl logs --namespace boundary deployment/boundary-worker-deployment

worker-led 등록에서는 생성된 worker 아이덴티티가 재시작 후에도 지속되도록 auth 스토리지를 활성화된 상태로 유지하세요.

Controller-led 등록

Controller-led 등록의 일반적인 워크플로는 다음과 같아요. 자세한 내용은 Controller-led registration을 참고하세요:

• Boundary나 HCP Boundary에서 worker 리소스 생성
• 컨트롤러가 생성한 활성화 토큰 확보
• 아래 방법 중 하나로 토큰 제공
• worker Helm 차트 설치
• worker가 등록하고 자격 증명을 auth 스토리지에 영속화하는지 확인

worker는 초기 부트스트랩 중에 활성화 토큰을 사용합니다. 등록에 성공한 후에는 auth 스토리지에 영속화된 자격 증명을 사용해요.

차트는 활성화 토큰을 제공하는 세 가지 방법을 지원합니다.

Note — 평문과 extraEnv 방법은 토큰을 Helm 릴리스 Secret에 저장하므로, helm get values boundary-worker --namespace boundary를 실행할 수 있는 누구에게나 보입니다. 토큰을 Helm 릴리스 저장소에서 완전히 밖에 두어야 한다면 secretRefs 방법을 사용하세요.

평문 토큰

토큰을 worker.config에 직접 넣습니다. 개발 전용으로만 적합해요 — ConfigMap을 읽을 수 있는 사람은 누구나 토큰을 볼 수 있습니다.

예시 HCL:

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"]
  auth_storage_path = "/var/lib/boundary"
  controller_generated_activation_token = "<activation-token>"

  tags {
    type = ["worker", "controller-led"]
  }
}

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

예시 values:

worker:
  persistence:
    authStorage:
      enabled: true
      size: 1Gi

worker Helm 차트를 설치합니다:

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

extraEnv로 토큰 전달

worker.config에서 controller_generated_activation_token을 env:// 참조로 설정하고, 토큰을 extraEnv의 키-값 쌍으로 제공합니다:

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"]
  auth_storage_path = "/var/lib/boundary"
  controller_generated_activation_token = "env://BOUNDARY_WORKER_CONTROLLER_GENERATED_ACTIVATION_TOKEN"

  tags {
    type = ["worker", "controller-led"]
  }
}

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

예시 values:

extraEnv:
  - name: BOUNDARY_WORKER_CONTROLLER_GENERATED_ACTIVATION_TOKEN
    value: "<activation-token>"

worker:
  persistence:
    authStorage:
      enabled: true
      size: 1Gi

worker Helm 차트를 설치합니다:

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

Kubernetes Secret에서 토큰 가져오기

활성화 토큰을 Kubernetes Secret에 저장하고 secretRefs로 참조합니다. 차트는 Secret 값을 BOUNDARY_WORKER_CONTROLLER_GENERATED_ACTIVATION_TOKEN 환경 변수로 주입하며, Boundary가 env:// 접두사를 통해 시작 시 읽어요.

차트를 설치하기 전에 Secret을 만듭니다:

$ kubectl create secret generic boundary-worker-secrets \
  --namespace boundary \
  --from-literal=worker-controller-generated-activation-token='<activation-token>'

키 이름(worker-controller-generated-activation-token)은 Helm values 파일의 secretRefs.keys.controllerGeneratedActivationToken에 설정한 값과 일치해야 해요. 이 명령은 예시로 제공됩니다 — 워크플로에 맞는 어떤 Secret 관리 방법이든 사용하세요.

worker.config에서 controller_generated_activation_token을 env:// 참조로 설정합니다:

worker {
  name = "boundary-worker"
  public_addr = ""
  initial_upstreams = ["boundary-controller-cluster:9201"]
  auth_storage_path = "/var/lib/boundary"
  controller_generated_activation_token = "env://BOUNDARY_WORKER_CONTROLLER_GENERATED_ACTIVATION_TOKEN"

  tags {
    type = ["worker", "controller-led"]
  }
}

예시 values:

secretRefs:
  secretName: boundary-worker-secrets
  keys:
    controllerGeneratedActivationToken: worker-controller-generated-activation-token

worker:
  persistence:
    authStorage:
      enabled: true
      size: 1Gi

secretRefs.validateExisting=true로 설정하면 설치 중 Secret이 없을 때 Helm이 일찍 실패하게 할 수 있어요.

Note — secretRefs.secretName이 설정되면 차트는 worker.config가 secret 지원 필드에 대해 올바른 env:// 변수 이름을 사용하는지 검증합니다. 다른 변수 이름을 쓰면 설치가 완료되기 전에 렌더링 중 차트가 실패해요. 필수 이름은 다음과 같습니다:

• controller_generated_activation_token용 env://BOUNDARY_WORKER_CONTROLLER_GENERATED_ACTIVATION_TOKEN

다른 변수 이름을 쓰면 차트는 해당 필드와 기대 변수 이름을 식별하는 오류 메시지와 함께 렌더링 중 실패합니다. secretRefs.secretName이 설정되었을 때 worker.config에 토큰을 직접 하드코딩하는 것도 거부됩니다.

worker Helm 차트를 설치합니다:

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

KMS(키 관리 시스템) 기반 worker 인증

Boundary는 셀프 매니지드 배포에서만 KMS 기반 worker 인증을 지원해요. 자세한 내용은 외부 KMS 등록을 참고하세요. HCP Boundary worker에는 사용할 수 없습니다.

셀프 매니지드 배포에서는 필수 KMS worker-auth 스탠자로 worker HCL을 구성하세요. KMS 인증은 영구적인 로컬 auth 자료를 요구하지 않으므로 auth 스토리지 PVC를 비활성화해야 해요.

KMS 기반 worker 인증용 예시 HCL:

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", "kms"]
  }
}

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"
    event_types = ["*"]
    format      = "cloudevents-json"
  }
}

worker:
  persistence:
    authStorage:
      enabled: false

worker.persistence.authStorage.enabled가 false일 때 차트는 PVC를 만드는 대신 auth 스토리지 경로에 emptyDir을 마운트해요.

세션 녹화 스토리지 활성화

worker가 세션 녹화를 저장한다면 녹화 영속성을 활성화하고 worker.config에 recording_storage_path를 설정하세요.

Note — RDP(원격 데스크톱 프로토콜) 세션 녹화 내보내기를 만들려면 worker에 버전 5.1.0 이상의 FFmpeg 바이너리가 설치되어 있어야 해요. libsvtav1 코덱도 있어야 합니다. 기본 Boundary worker 이미지는 FFmpeg를 포함하지 않으므로, 바이너리와 코덱을 추가한 커스텀 이미지를 빌드해서 values 파일에서 참조해야 해요.

values 파일에 커스텀 이미지를 전달합니다:

image:
  repository: <your-registry>/boundary-worker
  tag: "1.0.0-ffmpeg"

예시 values:

worker:
  persistence:
    recording:
      enabled: true
      size: 10Gi
      path: /boundary/recording

일치하는 HCL:

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

  tags {
    type = ["worker", "recording"]
  }
}

worker.config의 녹화 스토리지 경로가 worker.persistence.recording.path와 일치하는지 확인하세요.

서비스 포트 변경

리스너 포트를 바꾸면 HCL과 차트 values를 모두 업데이트하세요.

예시 values:

worker:
  service:
    proxy:
      port: 9222
      targetPort: 9222

일치하는 HCL:

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

차트는 이 설정들을 자동으로 동기화하지 않아요.

문제 해결

세션 녹화 내보내기 실패

세션 녹화 내보내기가 실패하면 세션 녹화 스토리지 활성화에서 설명한 대로 worker 이미지에 버전 5.1.0 이상의 FFmpeg 바이너리와 libsvtav1 코덱이 포함되어 있는지 확인하세요. 기본 Boundary worker 이미지는 FFmpeg를 포함하지 않으므로, 바이너리와 코덱을 추가한 커스텀 이미지를 빌드해서 참조하기 전까지 녹화 내보내기가 실패합니다.

더 알아보기 (Learn more)

worker를 구성하거나 업데이트하기 위한 지원되는 Helm values는 Worker values를 참고하세요.