Helm Library Chart: 재사용 가능한 차트 컴포넌트 구축하기

4 분 소요

게시: November 18, 2025

Library Chart란?

Library Chart는 다른 Helm 차트에서 공유할 수 있는 템플릿 헬퍼와 정의를 제공하는 특수한 형태의 Helm 차트입니다. Helm v2부터 지원되었으며, 코드 중복을 방지(DRY: Don’t Repeat Yourself)하고 여러 차트 간의 일관성을 유지하는 것이 유일한 목표입니다.

왜 필요한가?

100개의 애플리케이션 차트를 관리한다고 가정해봅시다. 모든 차트에서 다음과 같은 작업을 반복적으로 수행해야 합니다:

일관된 규칙으로 리소스 이름 생성
모든 리소스에 표준화된 레이블(Label) 적용
기본 보안 설정(SecurityContext) 구성
ServiceAccount 생성 로직 처리

이러한 공통 로직을 각 차트마다 복사-붙여넣기 하는 대신, Library Chart로 중앙화하여 관리할 수 있습니다.

주요 특징

1. 독립 배포 불가

Library Chart는 단독으로 설치할 수 없습니다.

# 이 명령은 실패합니다
helm install mylibchart ./common

실패하는 이유는 templates/ 폴더에 Deployment.yaml, Service.yaml 같은 실제 Kubernetes 리소스 파일이 없기 때문입니다. 대신 _helpers.tpl 파일에 재사용 가능한 템플릿 함수({{ define "..." }})만 정의되어 있습니다.

2. Chart.yaml의 type 필드

Library Chart임을 명시하기 위해 Chart.yaml에 type: library를 선언합니다.

# Chart.yaml (예: bitnami/common)
apiVersion: v2
name: common
version: 2.15.0
type: library  # Library Chart 지정
description: Bitnami common library for Helm charts

일반 애플리케이션 차트와 비교:

# 애플리케이션 차트의 Chart.yaml
apiVersion: v2
name: my-app
version: 1.0.0
type: application  # 또는 생략 가능 (기본값)

사용 방법

1단계: 의존성 추가

애플리케이션 차트의 Chart.yaml에 Library Chart를 의존성으로 추가합니다.

# my-wordpress/Chart.yaml
apiVersion: v2
name: my-wordpress
version: 1.0.0
type: application

dependencies:
  - name: common
    version: 2.15.0
    repository: https://charts.bitnami.com/bitnami

2단계: 의존성 업데이트

cd my-wordpress
helm dependency update

이 명령은 charts/ 디렉토리에 common-2.15.0.tgz를 다운로드합니다.

3단계: 템플릿에서 헬퍼 함수 사용

# my-wordpress/templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  # common 라이브러리의 fullname 헬퍼 호출
  name: {{ include "common.names.fullname" . }}
  # common 라이브러리의 표준 레이블 헬퍼 호출
  labels: {{- include "common.labels.standard" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels: {{- include "common.labels.matchLabels" . | nindent 6 }}
  template:
    metadata:
      labels: {{- include "common.labels.standard" . | nindent 8 }}
    spec:
      serviceAccountName: {{ include "common.names.serviceAccountName" . }}
      securityContext: {{- include "common.securityContext.pod" . | nindent 8 }}
      containers:
      - name: wordpress
        image: {{ .Values.image.repository }}:{{ .Values.image.tag }}
        securityContext: {{- include "common.securityContext.container" . | nindent 10 }}

실전 예제: 자체 Library Chart 생성

Library Chart 구조

my-common/
├── Chart.yaml
└── templates/
    └── _helpers.tpl

Chart.yaml

apiVersion: v2
name: my-common
version: 1.0.0
type: library
description: 우리 조직의 공통 Helm 헬퍼 라이브러리

templates/_helpers.tpl

{{/*
리소스 풀네임 생성
*/}}
{{- define "my-common.fullname" -}}
{{- $name := default .Chart.Name .Values.nameOverride -}}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
{{- end -}}

{{/*
표준 레이블
*/}}
{{- define "my-common.labels" -}}
app.kubernetes.io/name: {{ include "my-common.fullname" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- if .Values.customLabels }}
{{ toYaml .Values.customLabels }}
{{- end }}
{{- end -}}

{{/*
보안 컨텍스트
*/}}
{{- define "my-common.securityContext" -}}
runAsNonRoot: true
runAsUser: 1000
fsGroup: 1000
seccompProfile:
  type: RuntimeDefault
{{- end -}}

애플리케이션 차트에서 사용

# my-app/Chart.yaml
dependencies:
  - name: my-common
    version: 1.0.0
    repository: file://../my-common  # 로컬 경로

# my-app/templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "my-common.fullname" . }}
  labels: {{- include "my-common.labels" . | nindent 4 }}
spec:
  template:
    spec:
      securityContext: {{- include "my-common.securityContext" . | nindent 8 }}

모범 사례

1. 명명 규칙

Library Chart의 헬퍼 함수는 네임스페이스를 사용하여 충돌을 방지합니다.

# 권장
{{- define "my-common.labels.standard" -}}

# 지양 (너무 일반적)
{{- define "labels" -}}

2. 문서화

각 헬퍼 함수에 명확한 주석을 추가합니다.

{{/*
전체 리소스 이름 생성
인자:
  - .Values.nameOverride: 이름 오버라이드 (선택)
  - .Values.fullnameOverride: 전체 이름 오버라이드 (선택)
반환: 63자로 제한된 전체 리소스 이름
사용 예:
  name: {{ include "my-common.fullname" . }}
*/}}
{{- define "my-common.fullname" -}}
{{- if .Values.fullnameOverride -}}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}}
{{- else -}}
{{- $name := default .Chart.Name .Values.nameOverride -}}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
{{- end -}}
{{- end -}}

3. 버전 관리

Library Chart도 시맨틱 버저닝을 따릅니다.

Patch (1.0.1): 버그 수정, 기존 기능에 영향 없음
Minor (1.1.0): 새로운 헬퍼 함수 추가, 하위 호환성 유지
Major (2.0.0): 기존 헬퍼 함수의 동작 변경, 하위 호환성 깨짐

4. 테스트

Library Chart의 헬퍼 함수를 테스트하는 더미 차트를 생성합니다.

# test-chart/templates/test.yaml
{{- include "my-common.labels" . }}
---
{{- include "my-common.securityContext" . }}

helm template test-chart ./test-chart

실무 활용 시나리오

멀티 클러스터 환경

여러 클라이언트 클러스터(LGU+, LGD, Samsung)를 관리할 때, Library Chart로 공통 정책을 중앙화.

# security-common/templates/_helpers.tpl
{{/*
엔터프라이즈 보안 정책
*/}}
{{- define "security.podSecurityContext" -}}
runAsNonRoot: true
runAsUser: 1000
fsGroup: 1000
seccompProfile:
  type: RuntimeDefault
{{- end -}}

{{/*
네트워크 정책 레이블
*/}}
{{- define "security.networkLabels" -}}
network-policy: enabled
client: {{ .Values.client.name }}
{{- end -}}

GitOps 통합

Library Chart를 Harbor 또는 ChartMuseum에 푸시하여 Air-gapped 환경에서 활용:

# Library Chart 패키징
helm package my-common

# Harbor에 푸시
helm push my-common-1.0.0.tgz oci://harbor.internal/charts

각 클라이언트 차트에서 참조:

dependencies:
  - name: my-common
    version: 1.0.0
    repository: oci://harbor.internal/charts

정리

Library Chart는 대규모 Helm 차트 관리에서 필수적인 도구입니다. 공통 로직을 중앙화하여 일관성을 유지하고, 유지보수 부담을 크게 줄일 수 있습니다. 특히 여러 클러스터와 애플리케이션을 관리하는 플랫폼 팀에게는 표준화와 효율성 확보를 위한 핵심 패턴입니다.

X Facebook LinkedIn Bluesky

Seungho Jeong