Controller Helm 차트 예시

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

이 컨트롤러 구성 변형들 — TLS 설정, 데이터베이스 마이그레이션, 부트스트랩 admin 생성, cluster 서비스 노출 — 을 사용해서, 컨트롤러 배포의 기본 컨트롤러 설치를 환경에 맞게 적용할 수 있어요. PostgreSQL과 KMS(키 관리 시스템) 접근이 이미 존재한다고 가정합니다.

출처: HashiCorp Boundary docs

본문

컨트롤러 Secret 생성

차트가 설치 시 읽는 값을 담은 Kubernetes Secret을 만듭니다. 최소한 데이터베이스 URL과 Boundary Enterprise 라이선스를 포함하세요. bootstrapAdmin.enabled=true면 부트스트랩 admin 자격 증명을, HCL에서 env://BOUNDARY_PG_MIGRATION_URL로 migration_url을 참조한다면 마이그레이션 URL도 포함합니다.

$ kubectl create secret generic boundary-controller-secrets \
  --namespace boundary \
  --from-literal=database-url="postgres://<user>:***@<host>:5432/<dbname>?sslmode=require" \
  --from-literal=migration-url="postgres://<migration-user>:***@<host>:5432/<dbname>?sslmode=require" \
  --from-literal=license="<your-license-here>" \
  --from-literal=admin-username="<admin-username>" \
  --from-literal=admin-password="<admin-password>"

키 이름(database-url, migration-url, license, admin-username, admin-password)은 Helm values 파일의 secretRefs.keys.*에 설정한 값과 일치해야 해요. 이 명령들은 예시로 제공됩니다 — 워크플로에 맞는 어떤 Secret 관리 방법이든 사용하세요.

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

• database { url }용 env://BOUNDARY_PG_URL
• database { migration_url }용 env://BOUNDARY_PG_MIGRATION_URL
• controller { license }용 env://BOUNDARY_LICENSE

다른 변수 이름을 쓰고 그것이 extraEnv에 선언되지 않았다면, 차트는 해당 필드와 기대 변수 이름을 식별하는 오류 메시지와 함께 렌더링 중 실패합니다.

TLS Secret 생성

tls.disabled=false(기본값)라면, 차트를 설치하기 전에 Kubernetes TLS Secret을 만드세요. Secret은 표준 kubernetes.io/tls 유형과 tls.crt, tls.key 데이터 키를 사용해야 해요.

$ kubectl create secret tls boundary-controller-tls \
  --namespace boundary \
  --cert=tls.crt \
  --key=tls.key

Secret 이름은 tls.secretName(기본값 boundary-controller-tls)과 일치해야 합니다. 이 명령들은 예시로 제공됩니다 — 워크플로에 맞는 어떤 Secret 관리 방법이든 사용하세요.

데이터베이스 초기화 활성화

첫 설치 시 사전 설치 데이터베이스 초기화 Job을 활성화해서 차트가 Boundary 스키마를 만들게 할 수 있어요.

예시 values:

database:
  init:
    enabled: true

다음 경우에 이 패턴을 사용하세요:

• 빈 PostgreSQL 데이터베이스에 대해 차트를 처음 설치할 때
• Helm이 초기 스키마 생성을 관리하기를 원할 때

database.init.enabled=true로 설정하면 Helm은 ConfigMap, Services, Deployment 및 기타 활성화된 리소스를 만들기 전에 Boundary 스키마를 초기화하는 pre-install Job을 실행합니다. 이후 설치하거나 기존 Boundary 데이터베이스에 재초기화할 때에는 이 Job을 비활성화하세요.

부트스트랩 admin 생성 활성화

첫 설치 시 사후 설치 부트스트랩 Job을 활성화해서 차트가 global password 인증 방법, 사용자, 계정, 역할을 만들게 할 수 있어요.

예시 values:

bootstrapAdmin:
  enabled: true

Helm이 초기 Boundary admin 자격 증명을 만들기를 원할 때 이 패턴을 사용하세요. 첫 설치 후, 또는 다른 워크플로로 Boundary 인증 방법과 admin 주체를 관리한다면 이 Job을 비활성화합니다.

TLS가 활성화된 컨트롤러

컨트롤러 리스너의 API와 ops 트래픽을 암호화하려면 TLS를 활성화하세요. Kubernetes TLS Secret을 제공하고 프로브 스킴을 HTTPS와 정렬된 상태로 유지합니다.

Note — TLS 인증서에는 다음 SAN(Subject Alternative Name)이 포함되어야 해요(nameOverride나 fullnameOverride를 설정했다면 조정하세요):

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

부트스트랩 admin Job은 이 이름에 대해 인증서를 검증합니다 — 없으면 Job이 시간 초과돼요.

예시 values:

tls:
  disabled: false
  secretName: boundary-controller-tls
  mountPath: /etc/boundary/tls

일치하는 HCL — tls_disable = false를 설정하고 API와 ops 리스너에 tls_cert_file과 tls_key_file을 추가합니다:

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:9203"
  purpose       = "ops"
  tls_disable   = false
  tls_cert_file = "/etc/boundary/tls/tls.crt"
  tls_key_file  = "/etc/boundary/tls/tls.key"
}

TLS가 비활성화된 컨트롤러

컨트롤러 리스너가 TLS를 종료하는 업스트림 프록시나 로드 밸런서로 보호되거나, 암호화가 필요 없는 비프로덕션 환경에서는 TLS를 비활성화하세요.

예시 values:

tls:
  disabled: true

일치하는 HCL — TLS가 활성화되어 있던 각 리스너에 tls_disable = true를 설정하고 tls_cert_file과 tls_key_file 설정을 제거합니다:

listener "tcp" {
  address     = "0.0.0.0:9200"
  purpose     = "api"
  tls_disable = true
}

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

tls.disabled=true면 차트는 TLS Secret을 마운트하지 않고 프로브 스킴은 기본적으로 HTTP가 됩니다.

내부 전용 cluster 서비스

모든 worker가 클러스터 안에서 실행되거나 사설 네트워킹으로 연결한다면, cluster 리스너를 내부로 유지하고 public_cluster_addr을 worker가 도달할 수 있는 사설 DNS 이름이나 내부 로드 밸런서 주소로 설정하세요.

예시 values:

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

일치하는 HCL:

controller {
  name = "boundary-controller"
  public_cluster_addr = "boundary-controller-cluster.boundary.svc.cluster.local:9201"
  license = "env://BOUNDARY_LICENSE"

  database {
    url = "env://BOUNDARY_PG_URL"
  }
}

외부에서 접근 가능한 cluster 서비스

worker가 다른 네임스페이스나 클러스터 바깥에서 실행된다면, 기본 ClusterIP cluster 서비스가 도달 가능하지 않을 수 있어요. cluster 서비스를 LoadBalancer로 구성하면 worker가 네임스페이스 바깥에서 public_cluster_addr에 연결할 수 있습니다.

예시 values:

controller:
  service:
    cluster:
      type: LoadBalancer
      port: 9201
      targetPort: 9201

일치하는 HCL — 로드 밸런서가 프로비저닝된 후 public_cluster_addr을 업데이트합니다:

controller {
  name = "boundary-controller"
  public_cluster_addr = "<LOAD_BALANCER_ADDRESS>:9201"
  license = "env://BOUNDARY_LICENSE"

  database {
    url = "env://BOUNDARY_PG_URL"
  }
}

외부 주소가 할당될 때까지 cluster Service를 지켜봅니다:

$ kubectl get svc boundary-controller-cluster --namespace boundary --watch

예시 출력:

NAME                          TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)          AGE
boundary-controller-cluster   LoadBalancer   10.0.0.123     <pending>       9201:31234/TCP   10s
boundary-controller-cluster   LoadBalancer   10.0.0.123     203.0.113.10    9201:31234/TCP   45s

controller.config의 public_cluster_addr을 할당된 주소로 업데이트한 다음 업그레이드합니다:

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

worker 등록과 컨트롤러 클러스터링에 인터넷 접근 엔드포인트가 필요 없을 때 이 패턴을 사용하세요.

사전 구성된 DNS 주소가 있는 컨트롤러

컨트롤러의 cluster 리스너에 대한 DNS 이름을 이미 관리하고 있다면, 설치 전에 public_cluster_addr을 그 주소로 설정하세요:

controller {
  name = "boundary-controller"
  public_cluster_addr = "boundary-controller.example.com:9201"
  license = "env://BOUNDARY_LICENSE"

  database {
    url = "env://BOUNDARY_PG_URL"
  }
}

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

마이그레이션 URL 구성

스키마 마이그레이션에 다른 PostgreSQL 연결 문자열을 사용한다면, 컨트롤러 HCL에 migration_url을 평문 값으로 직접 설정하세요.

일치하는 HCL:

controller {
  name = "boundary-controller"
  public_cluster_addr = "boundary-controller-cluster.boundary.svc.cluster.local:9201"
  license = "<your-license-here>"

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

마이그레이션 URL에 평문으로 저장해서는 안 되는 자격 증명이 들어 있다면, 대신 env://BOUNDARY_PG_MIGRATION_URL로 참조하고 값을 secretRefs.keys.migrationUrl로 올바른 키를 가리키면서 databaseUrl과 같은 Kubernetes Secret에 저장할 수 있어요.

데이터베이스 마이그레이션이 있는 버전 업그레이드

Warning — 마이그레이션이나 복구를 실행하기 전에 PostgreSQL 백업을 받으세요.

스키마 변경이 필요한 Boundary 버전으로 업그레이드할 때는 먼저 컨트롤러 포드를 중지한 다음, Helm 업그레이드 중에 마이그레이션 Job을 실행하세요.

컨트롤러를 0으로 스케일:

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

마이그레이션 실행:

$ helm upgrade boundary-controller hashicorp/boundary-controller \
  --version 0.1.0 \
  --namespace boundary \
  --values my-values.yaml \
  --set controller.replicas=0 \
  --set database.migrate.enabled=true \
  --rollback-on-failure \
  --wait

또는 특정 버전에 대한 복구 마이그레이션도 함께 실행하려면:

$ helm upgrade boundary-controller hashicorp/boundary-controller \
  --version 0.1.0 \
  --namespace boundary \
  --values my-values.yaml \
  --set controller.replicas=0 \
  --set database.migrate.enabled=true \
  --set database.repair.version=<version_id> \
  --rollback-on-failure \
  --wait

마이그레이션이 완료된 후 모든 마이그레이션 플래그를 재설정하고 컨트롤러 레플리카 수를 복원합니다:

Note — controller.replicas를 배포에 필요한 수로 설정하세요. 다음 예시는 차트 기본값이기 때문에 2를 사용합니다.

$ helm upgrade boundary-controller hashicorp/boundary-controller \
  --version 0.1.0 \
  --namespace boundary \
  --values my-values.yaml \
  --set database.migrate.enabled=false \
  --set database.repair.version="" \
  --set controller.replicas=2 \
  --rollback-on-failure \
  --wait

Note — --reset-values 플래그를 쓰면 database.migrate.enabled도 재설정되지만, 모든 Helm values를 차트 기본값으로 재설정해서 이전에 --set이나 --set-file로 적용한 오버라이드를 모두 버려요. 다른 릴리스 값에 영향을 주지 않고 마이그레이션 플래그만 비활성화하려면 --set database.migrate.enabled=false를 사용하세요.

서비스 포트 변경

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

예시 values:

controller:
  service:
    api:
      port: 9210
      targetPort: 9210

일치하는 HCL:

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

차트는 이 설정들을 자동으로 동기화하지 않아요. cluster와 ops 리스너의 포트도 바뀐다면 같은 패턴을 적용하세요.

문제 해결

마이그레이션 Job 실패

database.migrate.enabled=true로 시작된 마이그레이션 Job이 실패하면, 마이그레이션이 성공할 때까지 컨트롤러 포드는 0으로 스케일된 채 유지됩니다. 마이그레이션이나 복구를 실행하기 전에 받아 둔 PostgreSQL 백업을 참조해서 데이터베이스를 복원한 다음, database.migrate.enabled=true를 다시 설정하고 helm upgrade를 다시 실행하기 전에 근본 원인(예: 잘못된 database.repair.version)을 고쳐야 해요.

더 알아보기 (Learn more)

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