Helm 차트로 컨트롤러 배포하기

Helm 차트로 컨트롤러 배포하기 (Deploy controllers using a Helm chart)

컨트롤러 차트는 Kubernetes에서 운영자 관리형(operator-managed) Boundary 컨트롤 플레인을 위한 것이에요. 여러 컨트롤러 레플리카를 실행할 수 있고, 데이터베이스 초기화에 Helm hook Job을 사용합니다. 데이터베이스 마이그레이션, 데이터베이스 복구, admin 부트스트랩에도 선택적으로 hook Job을 쓸 수 있어요.

PostgreSQL, KMS 접근, Boundary Enterprise 라이선스 데이터, TLS 자료 같은 필수 외부 의존성은 직접 제공해야 합니다.

Boundary 컨트롤러 Helm 차트를 배포하면 PostgreSQL로 뒷받침되는 실행 중인 Boundary 컨트롤 플레인을 얻게 돼요. worker 등록과 API 트래픽을 받아들일 준비가 된 상태입니다. 이 페이지는 컨트롤러 차트 설치만 다뤄요. 데이터 플레인 용량을 추가하려면 Helm 차트로 worker 배포하기를 참고하세요.

출처: HashiCorp Boundary docs

본문

사전 요구 사항

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

• 버전 1.34 이상을 실행하는 Kubernetes 클러스터
• 대상 Kubernetes 클러스터에 접근하도록 구성된 Helm 3 이상
• Boundary 컨트롤러 상태용 PostgreSQL 15 이상 데이터베이스(도달 가능해야 함)
• 유효한 Boundary 컨트롤러 HCL 구성
• root, recovery, worker-auth 목적용 KMS(키 관리 시스템) 구성
• Boundary Enterprise 라이선스와 데이터베이스 URL
• bootstrapAdmin.enabled=true일 때 admin-username과 admin-password를 담은 기존 Kubernetes Secret
• tls.disabled=false일 때 tls.crt와 tls.key를 담은 Kubernetes TLS Secret
• 컨트롤러 배포와 hook Job이 사용할 ServiceAccount

컨트롤러 차트는 무상태(stateless) Boundary 컨트롤 플레인을 배포해요. 영구적인 컨트롤러 상태는 컨트롤러 포드가 아니라 PostgreSQL이 저장합니다.

Helm 차트로 컨트롤러를 배포하려면 다음 단계를 완료하세요.

HashiCorp Helm 리포지토리 추가

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

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

예시 출력:

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

컨트롤러 Secret 생성

차트는 secretRefs.secretName이 참조하는 기존 Kubernetes Secret에서 민감한 값을 읽어요. 최소한 데이터베이스 URL과 Boundary Enterprise 라이선스가 든 Secret을 만드세요. bootstrapAdmin.enabled=true면 부트스트랩 admin 자격 증명도 포함합니다.

Secret 생성 방법은 Kubernetes Secrets 문서를 참고하세요.

secretRefs.keys.*를 Secret에서 사용한 키 이름과 일치하도록 설정합니다. controller.config가 migration_url = "env://BOUNDARY_PG_MIGRATION_URL"을 사용한다면 secretRefs.keys.migrationUrl이 참조하는 마이그레이션 URL 키도 포함하세요.

TLS가 활성화된 경우 TLS Secret 생성

tls.disabled=false라면 설치 전에 Kubernetes TLS Secret을 만듭니다. 지침은 Kubernetes Secrets 문서를 참고하세요. Secret에는 tls.crt와 tls.key 항목이 들어 있어야 하고, 이름은 tls.secretName(기본값 boundary-controller-tls)과 일치해야 해요.

Note — bootstrapAdmin.enabled=true일 때 부트스트랩 admin Job은 컨트롤러 API Service에 연결하고 TLS 인증서를 검증합니다. 인증서에는 다음 SAN(Subject Alternative Name)이 포함되어야 해요(nameOverride나 fullnameOverride를 설정했다면 조정하세요):

• DNS:<fullname>-api (예: boundary-controller-api)

이 SAN이 없으면 Job이 시간 초과됩니다.

TLS가 비활성화되면 차트는 이 Secret을 마운트하지 않아요.

컨트롤러 구성 준비

차트는 values 파일의 controller.config 키에서 Boundary 컨트롤러 HCL을 읽습니다. 이 값을 차트 설치 전에 설정하세요.

기본 컨트롤러 구성은 controller stanza 참조의 안내를 참고하세요. 사용 가능한 컨트롤러 구성은 다음을 포함합니다:

• API 리스너
• cluster 리스너
• ops 리스너
• license와 database.url이 있는 controller 블록
• worker가 cluster 리스너에 도달할 수 있게 하는 public_cluster_addr
• root, recovery, worker-auth용 KMS 스탠자

AWS KMS를 사용하는 예시 컨트롤러 구성:

disable_mlock = true

listener "tcp" {
  address       = "0.0.0.0:9200"
  purpose       = "api"
  tls_disable   = false
  tls_cert_file = "/etc/boundary/tls/tls.crt"
  tls_key_file  = "/etc/boundary/tls/tls.key"
}

listener "tcp" {
  address = "0.0.0.0:9201"
  purpose = "cluster"
}

listener "tcp" {
  address       = "0.0.0.0:9203"
  purpose       = "ops"
  tls_disable   = false
  tls_cert_file = "/etc/boundary/tls/tls.crt"
  tls_key_file  = "/etc/boundary/tls/tls.key"
}

controller {
  name                = "boundary-controller"
  description         = "Boundary controller running in Kubernetes"
  public_cluster_addr = "boundary-controller-cluster.boundary.svc.cluster.local:9201"
  license             = "<your-license-here>"

  database {
    url = "postgres://<user>:***@<host>:5432/<dbname>?sslmode=require"
  }
}

kms "aead" {
  purpose   = "root"
  aead_type = "aes-gcm"
  key       = "sP1fnF5Xz85RrXyELHFeZg9Ad2qt4Z4bgNHVGtD6sFo="
  key_id    = "global_root"
}

kms "aead" {
  purpose   = "recovery"
  aead_type = "aes-gcm"
  key       = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
  key_id    = "global_recovery"
}

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"
    description = "All events sent to stderr"
    event_types = ["*"]
    format      = "hclog-text"
  }
}

Note — 여기 인라인 AEAD KMS 예시는 개발이나 테스트에 적합합니다. 키가 평문으로 저장되므로 구성을 읽을 수 있는 사람은 누구나 볼 수 있어요. 프로덕션 배포에는 KMS 구성에서 설명한 대로 외부 KMS 프로바이더를 사용하세요.

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

사용 가능한 차트 버전 나열

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

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

Boundary 컨트롤러 설치

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

secretRefs:
  secretName: boundary-controller-secrets

serviceAccount:
  name: default

tls:
  disabled: false

controller:
  config: |
    disable_mlock = true

    listener "tcp" {
      address       = "0.0.0.0:9200"
      purpose       = "api"
      tls_disable   = false
      tls_cert_file = "/etc/boundary/tls/tls.crt"
      tls_key_file  = "/etc/boundary/tls/tls.key"
    }

    listener "tcp" {
      address = "0.0.0.0:9201"
      purpose = "cluster"
    }

    listener "tcp" {
      address       = "0.0.0.0:9203"
      purpose       = "ops"
      tls_disable   = false
      tls_cert_file = "/etc/boundary/tls/tls.crt"
      tls_key_file  = "/etc/boundary/tls/tls.key"
    }

    controller {
      name                = "boundary-controller"
      description         = "Boundary controller running in Kubernetes"
      public_cluster_addr = "boundary-controller-cluster.boundary.svc.cluster.local:9201"
      license             = "<your-license-here>"

      database {
        url = "postgres://<user>:***@<host>:5432/<dbname>?sslmode=require"
      }
    }

    kms "aead" {
      purpose   = "root"
      aead_type = "aes-gcm"
      key       = "sP1fnF5Xz85RrXyELHFeZg9Ad2qt4Z4bgNHVGtD6sFo="
      key_id    = "global_root"
    }

    kms "aead" {
      purpose   = "recovery"
      aead_type = "aes-gcm"
      key       = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
      key_id    = "global_recovery"
    }

    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"
        description = "All events sent to stderr"
        event_types = ["*"]
        format      = "hclog-text"
      }
    }

  service:
    api:
      type: LoadBalancer
    cluster:
      type: ClusterIP
    ops:
      type: ClusterIP

릴리스를 설치하고, 데이터베이스 스키마를 초기화하고, 부트스트랩 admin을 만들려면 다음 명령을 실행해요:

$ helm install boundary-controller hashicorp/boundary-controller \
  --version 0.1.0 \
  --namespace boundary \
  --create-namespace \
  --values my-values.yaml \
  --set database.init.enabled=true \
  --set bootstrapAdmin.enabled=true \
  --wait

예시 출력:

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

아니면 데이터베이스 초기화와 부트스트랩 admin 생성 없이 설치할 수도 있어요:

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

배포 검증

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

$ kubectl get deployment,pods,svc,jobs,pdb --namespace boundary; \
  kubectl logs --namespace boundary deployment/boundary-controller

예시 출력:

NAME                                    READY   STATUS      RESTARTS   AGE
pod/boundary-controller-0               1/1     Running     0          2m
pod/boundary-controller-1               1/1     Running     0          2m
pod/boundary-controller-db-init-abcde   0/1     Completed   0          2m

NAME                                     TYPE           CLUSTER-IP     EXTERNAL-IP   PORT(S)          AGE
service/boundary-controller-api          LoadBalancer   10.0.0.10      203.0.113.5   9200:31000/TCP   2m
service/boundary-controller-cluster      ClusterIP      10.0.0.11              9201/TCP         2m
service/boundary-controller-ops          ClusterIP      10.0.0.12              9203/TCP         2m

다음을 확인하세요:

• database.init.enabled=true일 때 데이터베이스 초기화 Job이 성공적으로 완료
• bootstrapAdmin.enabled=true일 때 부트스트랩 admin Job이 성공적으로 완료
• 컨트롤러 포드가 Ready가 됨
• API, cluster, ops 서비스가 의도한 노출 모델과 일치
• 컨트롤러 API 리스너에 대한 Boundary API 요청이 성공
• worker가 public_cluster_addr에 도달하고 성공적으로 등록

컨트롤러 업그레이드

컨트롤러 배포를 업그레이드하려면 다음을 실행하세요:

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

데이터베이스 마이그레이션 시나리오는 Controller Helm chart 예시를 참고하세요.

컨트롤러 제거

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

$ helm uninstall boundary-controller --namespace boundary

문제 해결

부트스트랩 admin Job 시간 초과

부트스트랩 admin Job이 컨트롤러 API Service에 연결하는 동안 시간 초과되면, TLS Secret 생성에서 설명한 대로 TLS Secret의 인증서에 필수 SAN(DNS:<fullname>-api, 예: boundary-controller-api)이 포함되어 있는지 확인하세요. SAN이 누락되거나 불일치하면 Job이 인증서 검증에 실패하고 시간 초과됩니다.

더 알아보기 (Learn more)

worker를 배포하려면 Helm 차트로 worker 배포하기를 참고하세요.

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