Helm 추가 매니페스트

차트 버전 2.x에서만 사용 가능

additionalManifests 기능은 v2.x 서브차트 기반 Helm 차트에서만 사용할 수 있습니다.

additionalManifests 값을 사용하면 ClickStack 차트와 함께 임의의 Kubernetes 객체를 배포할 수 있습니다. NetworkPolicy, HorizontalPodAutoscaler, ServiceAccount, PodMonitor, 사용자 지정 Ingress 객체처럼 차트에서 기본적으로 템플릿으로 제공하지 않는 리소스나 기타 Kubernetes API 객체에 활용하십시오.

작동 방식

additionalManifests의 각 항목은 완전한 Kubernetes 리소스 정의입니다. 이 차트는 다음을 수행합니다.

목록의 각 항목을 순회합니다
항목을 YAML로 변환합니다(toYaml)
Helm tpl을 사용해 해당 YAML의 템플릿 표현식을 평가합니다

템플릿 표현식은 다음을 참조할 수 있습니다.

.Release.Name, .Release.Namespace
include "clickstack.fullname" . 및 기타 차트 헬퍼
.Values.*

additionalManifests:
  - apiVersion: v1
    kind: ConfigMap
    metadata:
      name: '{{ include "clickstack.fullname" . }}-custom'
    data:
      release: '{{ .Release.Name }}'

values 파일 제약 사항

additionalManifests는 values 파일에서 구성되며, values 파일은 tpl이 실행되기 전에 YAML로 파싱됩니다.

values 파일의 {{ ... }}는 반드시 따옴표로 감싼 문자열 안에 있어야 합니다
구조적 템플릿 블록은 유효한 values YAML이 아닙니다(예: {{- include ... | nindent ... }}만 단독으로 사용하는 경우)
문자열이 아닌 필드(예: 숫자 포트)에는 리터럴 값 또는 이름 있는 포트를 사용하십시오
구조적 템플릿이 필요하면 원시 values 파일 대신 래퍼 차트 템플릿을 사용하십시오

# Valid in values.yaml
name: '{{ include "clickstack.fullname" . }}-app'

# Invalid in values.yaml (unquoted template expression)
name: {{ include "clickstack.fullname" . }}-app

# Invalid in values.yaml (structural template block)
labels:
  {{- include "clickstack.labels" . | nindent 2 }}

사용 가능한 차트 헬퍼

이러한 헬퍼는 templates/_helpers.tpl에 정의되어 있습니다:

헬퍼	Description	Values-file usage
`clickstack.name`	차트 이름(63자까지 잘림)	따옴표로 묶인 스칼라에서 안전하게 사용 가능
`clickstack.fullname`	릴리스가 포함된 이름	따옴표로 묶인 스칼라에서 안전하게 사용 가능
`clickstack.chart`	차트 이름 + 버전	따옴표로 묶인 스칼라에서 안전하게 사용 가능
`clickstack.selectorLabels`	selector 레이블 블록	래퍼 차트 템플릿에서만 사용
`clickstack.labels`	표준 레이블 블록	래퍼 차트 템플릿에서만 사용
`clickstack.mongodb.fullname`	MongoDB CR 이름	따옴표로 묶인 스칼라에서 안전하게 사용 가능
`clickstack.clickhouse.fullname`	ClickHouse CR 이름	따옴표로 묶인 스칼라에서 안전하게 사용 가능
`clickstack.otel.fullname`	OTel collector 이름	따옴표로 묶인 스칼라에서 안전하게 사용 가능

예제

ServiceAccount

additionalManifests:
  - apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: '{{ include "clickstack.fullname" . }}'
      namespace: '{{ .Release.Namespace }}'
      labels:
        app.kubernetes.io/name: '{{ include "clickstack.name" . }}'
        app.kubernetes.io/instance: '{{ .Release.Name }}'
      annotations:
        eks.amazonaws.com/role-arn: "arn:aws:iam::123456789:role/my-role"

NetworkPolicy

HyperDX 파드로 들어오는 트래픽을 제한합니다:

additionalManifests:
  - apiVersion: networking.k8s.io/v1
    kind: NetworkPolicy
    metadata:
      name: '{{ include "clickstack.fullname" . }}-allow-ingress'
    spec:
      podSelector:
        matchLabels:
          app.kubernetes.io/name: '{{ include "clickstack.name" . }}'
          app.kubernetes.io/instance: '{{ .Release.Name }}'
      policyTypes:
        - Ingress
      ingress:
        - from:
            - namespaceSelector:
                matchLabels:
                  kubernetes.io/metadata.name: ingress-nginx
          ports:
            - protocol: TCP
              port: 3000
            - protocol: TCP
              port: 8000

HorizontalPodAutoscaler

additionalManifests:
  - apiVersion: autoscaling/v2
    kind: HorizontalPodAutoscaler
    metadata:
      name: '{{ include "clickstack.fullname" . }}-hpa'
    spec:
      scaleTargetRef:
        apiVersion: apps/v1
        kind: Deployment
        name: '{{ include "clickstack.fullname" . }}-app'
      minReplicas: 2
      maxReplicas: 10
      metrics:
        - type: Resource
          resource:
            name: cpu
            target:
              type: Utilization
              averageUtilization: 75

PodMonitor (Prometheus Operator)

additionalManifests:
  - apiVersion: monitoring.coreos.com/v1
    kind: PodMonitor
    metadata:
      name: '{{ include "clickstack.fullname" . }}'
      labels:
        release: prometheus
    spec:
      selector:
        matchLabels:
          app.kubernetes.io/name: '{{ include "clickstack.name" . }}'
          app.kubernetes.io/instance: '{{ .Release.Name }}'
      podMetricsEndpoints:
        - port: app
          interval: 30s

AWS ALB 인그레스

AWS Load Balancer Controller를 사용하는 경우, 차트에 기본 제공되는 nginx 인그레스를 비활성화하고 사용자 지정 ALB 인그레스를 정의합니다:

hyperdx:
  ingress:
    enabled: false

additionalManifests:
  - apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: '{{ include "clickstack.fullname" . }}-alb'
      annotations:
        alb.ingress.kubernetes.io/scheme: internet-facing
        alb.ingress.kubernetes.io/target-type: ip
        alb.ingress.kubernetes.io/certificate-arn: "arn:aws:acm:us-east-1:123456789:certificate/abc-123"
        alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS":443}]'
        alb.ingress.kubernetes.io/ssl-redirect: "443"
        alb.ingress.kubernetes.io/group.name: clickstack
        alb.ingress.kubernetes.io/healthcheck-path: /api/health
    spec:
      ingressClassName: alb
      rules:
        - host: clickstack.example.com
          http:
            paths:
              - path: /
                pathType: Prefix
                backend:
                  service:
                    name: '{{ include "clickstack.fullname" . }}-app'
                    port:
                      name: app

내부 OTel collector 인그레스와 HPA를 포함한 전체 ALB 설정 예시는 ALB example values에서 확인하십시오.

TargetGroupBinding

TargetGroupBinding 리소스를 명시적으로 지정해야 하는 ALB 시나리오의 경우:

additionalManifests:
  - apiVersion: elbv2.k8s.aws/v1beta1
    kind: TargetGroupBinding
    metadata:
      name: '{{ include "clickstack.fullname" . }}-tgb'
    spec:
      serviceRef:
        name: '{{ include "clickstack.fullname" . }}-app'
        port: app
      targetGroupARN: "arn:aws:elasticloadbalancing:us-east-1:123456789:targetgroup/my-tg/abc123"
      targetType: ip

심화: 래퍼 차트 템플릿

include "clickstack.labels" . | nindent 4와 같은 구조적 헬퍼가 필요하면, 해당 블록을 values 파일에 직접 넣지 말고 래퍼 차트 템플릿(templates/*.yaml)에서 렌더링하세요.

래퍼 차트 템플릿 스니펫 예시:

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "clickstack.fullname" . }}-extra
  labels:
    {{- include "clickstack.labels" . | nindent 4 }}
data:
  appPort: "{{ .Values.hyperdx.ports.app }}"

팁

Helm 훅

각 additionalManifests 항목은 각각 별도의 YAML 문서로 렌더링됩니다. Helm 훅 어노테이션을 추가하여 설치/업그레이드 순서를 제어할 수 있습니다:

additionalManifests:
  - apiVersion: batch/v1
    kind: Job
    metadata:
      name: post-install-job
      annotations:
        helm.sh/hook: post-install
        helm.sh/hook-delete-policy: hook-succeeded
    spec:
      template:
        spec:
          restartPolicy: Never
          containers:
            - name: migrate
              image: my-migration-image:latest
              command: ["./migrate.sh"]

CRD 적용 순서

추가 매니페스트에 커스텀 리소스(예: PodMonitor)가 포함된 경우, 설치 또는 업그레이드를 수행하기 전에 해당 CRD가 클러스터에 이미 존재해야 합니다.

여러 리소스 조합하기

additionalManifests는 목록입니다. 항목은 목록 순서대로 렌더링되며, 각 항목은 각각 별도의 YAML 문서로 처리됩니다.

다음 단계

주요 Helm 가이드 - 기본 설치
구성 가이드 - API 키, 시크릿 및 인그레스
Cloud 배포 - GKE, EKS 및 AKS 구성
ClickStack Helm 차트 저장소 - 차트 소스 코드 및 values 참조

작동 방식​

values 파일 제약 사항​

사용 가능한 차트 헬퍼​

예제​

ServiceAccount​

NetworkPolicy​

HorizontalPodAutoscaler​

PodMonitor (Prometheus Operator)​

AWS ALB 인그레스​

TargetGroupBinding​

심화: 래퍼 차트 템플릿​

팁​

Helm 훅​

CRD 적용 순서​

여러 리소스 조합하기​

다음 단계​