[Helm] Helm Chart 템플릿 파일에 대하여 - Loki Ingester StatefulSet

들어가며

 

Helm을 처음 사용할 때, 쿠버네티스 리소스를 쉽게 배포하고 관리할 수 있다는 점에서 정말 편리하다고 느꼈다.

특히, 공개된 Helm Chart 저장소에는 이미 수많은 검증된 템플릿이 존재하기 때문에, 이를 활용하면 애플리케이션을 빠르게 배포할 수 있다.

 

하지만 실제 운영 환경에서는 기본 제공되는 Helm Chart를 그대로 사용하는 경우가 많지 않다.

운영 정책이나 인프라 환경에 따라 리소스, 볼륨, 보안 설정을 조정해야 할 때가 많다.

 

이번 글에서는 Loki의 Ingester StatefulSet Helm Chart 템플릿을 분석하고, 이를 커스텀하는 방법을 설명해보겠다.

또한, Helm 템플릿에서 자주 사용하는 문법도 정리하여 실전에서 바로 적용할 수 있도록 하겠다.

Helm Chart 템플릿 구조 이해하기

Helm Chart는 기본적으로 템플릿 기반의 Kubernetes 리소스 생성 도구다.

즉, YAML 파일을 템플릿화하여 변수와 제어문을 활용해 유연한 구성을 할 수 있도록 돕는다.

 

Helm Chart의 구성 요소는 다음과 같다:

📂 Helm Chart 기본 구조

📦 loki-helm-chart
 ┣ 📂 templates
 ┃ ┣ 📜 _helpers.tpl    # 공통 템플릿 (이름, 라벨, 주석 등)
 ┃ ┣ 📜 ingress.yaml    # Ingress 리소스 템플릿
 ┃ ┣ 📜 service.yaml    # Service 리소스 템플릿
 ┃ ┣ 📜 statefulset.yaml # StatefulSet 리소스 템플릿
 ┣ 📜 values.yaml       # 사용자 정의 값 (환경별 설정)
 ┣ 📜 Chart.yaml        # Chart 메타데이터
 ┣ 📜 README.md         # 설명 문서

여기서 templates/statefulset.yaml이 우리가 분석할 파일이다.

Loki Ingester StatefulSet 템플릿 분석

아래는 Loki의 StatefulSet을 정의하는 Helm 템플릿이다.

이 템플릿을 분석하면서 Helm 문법과 운영 환경에서 커스텀하는 방법도 함께 설명하겠다.

 

🔹 if 조건문: 특정 값이 참일 때만 적용

{{- if eq .Values.ingester.kind "StatefulSet"}}
kind: StatefulSet
{{- end }}

• .Values.ingester.kind가 "StatefulSet"일 경우에만 해당 블록이 생성된다.
• eq는 if 문에서 값을 비교하는 Helm의 템플릿 함수다.
• {{- ... -}}를 사용하면 불필요한 공백이 제거된다.

 

💡 활용 예시

StatefulSet이 아니라 Deployment를 사용하려면 values.yaml에서 ingester.kind: Deployment로 변경하면 된다.

🔹 include 문법: 공통 템플릿 활용

metadata:
  name: {{ include "loki.ingesterFullname" . }}
  namespace: {{ .Release.Namespace }}
  labels:
    {{- include "loki.ingesterLabels" . | nindent 4 }}

• include를 사용하면 _helpers.tpl에 정의된 템플릿을 재사용할 수 있다.
• loki.ingesterFullname은 _helpers.tpl에서 정의한 Helm 템플릿 함수다.
• .Release.Namespace는 릴리즈 시 지정한 네임스페이스 값을 가져온다.

 

💡 활용 예시

include를 활용하면 네이밍 규칙을 표준화하고, 중복 코드 작성을 줄일 수 있다.

🔹 with: 특정 객체를 스코프 내에서 쉽게 참조

{{- with .Values.loki.annotations }}
annotations:
  {{- toYaml . | nindent 4 }}
{{- end }}

• .Values.loki.annotations가 존재하면 annotations 필드를 추가한다.
• with 블록 내부에서는 .이 loki.annotations을 가리키므로, .myKey처럼 간단히 접근할 수 있다.
• toYaml은 값을 YAML 형식으로 변환하는 Helm 내장 함수다.

💡 활용 예시

특정 환경에서만 annotations를 추가하고 싶을 때 values.yaml에서 설정을 조정하면 된다.

🔹 not: 값이 없을 경우 특정 값 적용

{{- if not .Values.ingester.autoscaling.enabled }}
  replicas: {{ .Values.ingester.replicas }}
{{- end }}

• .Values.ingester.autoscaling.enabled가 거짓(false)일 때만 replicas 값을 설정한다.
• not은 true/false 값을 반전시키는 Helm 내장 함수다.

 

💡 활용 예시

values.yaml에서 autoscaling.enabled: true로 설정하면 replicas 필드가 제거된다.

Helm Template에서 PVC 설정

Helm에서 PersistentVolumeClaim (PVC) 설정을 다루는 것도 중요하다.

Loki Ingester는 데이터 저장을 위해 PVC를 사용하거나, 필요에 따라 emptyDir을 사용할 수도 있다.

  {{- if not .Values.ingester.persistence.enabled }}
        - name: data
          emptyDir: {}
  {{- else if .Values.ingester.persistence.inMemory }}
        - name: data
          emptyDir:
            medium: Memory
  {{- else }}
  volumeClaimTemplates:
    - metadata:
        name: {{ .name }}
        {{- with .annotations }}
        annotations:
          {{- . | toYaml | nindent 10 }}
        {{- end }}
      spec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: {{ .size | quote }}
  {{- end }}

🔥 주요 로직

1. ingester.persistence.enabled: false → emptyDir(임시 디스크) 사용
2. ingester.persistence.inMemory: true → RAM 기반 저장소 사용
3. ingester.persistence.enabled: true → PVC를 생성하여 영구 저장

 

💡 활용 예시

운영 환경에서는 PVC를 사용하는 것이 안전하며, 스토리지 크기를 values.yaml에서 조정할 수 있다.

실제 운영에서 Helm Chart 커스텀하기

운영 환경에서 Helm 템플릿을 커스텀할 때 고려할 점

• 리소스 설정 조정: values.yaml에서 CPU/Mem 제한을 적절히 설정
• 볼륨 마운트 확인: PVC를 사용하거나 emptyDir을 사용할지 결정
• 보안 정책 적용: securityContext와 serviceAccountName 설정
• 업데이트 전략 선택: rollingUpdate 또는 OnDelete 설정

마무리

이번 글에서는 Loki Ingester StatefulSet의 Helm Chart 템플릿을 분석하면서 Helm 템플릿 문법과 활용법을 정리해봤다.