Helm 추가 매니페스트

additionalManifests를 사용해 ClickStack Helm 차트와 함께 사용자 지정 Kubernetes 객체 배포

차트 버전 2.x 전용

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

additionalManifests 값을 사용하면 ClickStack 차트와 함께 임의의 Kubernetes 객체를 배포할 수 있습니다. 차트가 기본적으로 템플릿으로 제공하지 않는 NetworkPolicy, HorizontalPodAutoscaler, ServiceAccount, PodMonitor, 사용자 지정 인그레스 객체 등과 같은 리소스나 기타 Kubernetes API 객체를 배포할 때 사용하십시오.

​

작동 방식

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

1. 목록의 각 항목을 순회합니다
2. 항목을 YAML로 변환합니다 (toYaml)
3. 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 ... }}만 단독으로 사용하는 경우)
• 문자열이 아닌 필드(예: 숫자 포트)에는 리터럴 값 또는 이름이 지정된 포트를 사용하십시오
• 구조적 템플릿이 필요하면 raw values 파일 대신 래퍼 차트 템플릿을 사용하십시오

# values.yaml에서 유효한 표현
name: '{{ include "clickstack.fullname" . }}-app'

# values.yaml에서 유효하지 않은 표현 (따옴표 없는 템플릿 표현식)
name: {{ include "clickstack.fullname" . }}-app

# values.yaml에서 유효하지 않은 표현 (구조적 템플릿 블록)
labels:
  {{- include "clickstack.labels" . | nindent 2 }}

​

사용 가능한 차트 헬퍼

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

Helper	Description	Values-file usage
clickstack.name	차트 이름(63자로 잘림)	따옴표로 감싼 스칼라에서 안전하게 사용 가능
clickstack.fullname	릴리스가 포함된 이름	따옴표로 감싼 스칼라에서 안전하게 사용 가능
clickstack.chart	차트 이름 + 버전	따옴표로 감싼 스칼라에서 안전하게 사용 가능
clickstack.selectorLabels	셀렉터 레이블 블록	래퍼 차트 템플릿에서만 사용
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 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 hooks

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

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 Keys, 시크릿, 인그레스
• Cloud 배포 - GKE, EKS, AKS 구성
• ClickStack Helm 차트 리포지토리 - 차트 소스 코드 및 values 참고