템플릿

템플릿 (Templates)

이 문서는 모범 사례 가이드에서 템플릿에 초점을 맞춰 다뤄요. templates/ 디렉터리 구조, 템플릿 이름 규칙, 포맷팅, 주석, JSON 사용 방법을 설명해요.

출처: 문서

본문

이 모범 사례 가이드의 이 부분은 템플릿에 초점을 맞춰요.

templates/ 구조 (Structure of templates/)

templates/ 디렉터리는 다음과 같이 구조화해야 해요:

  • 템플릿 파일이 YAML 출력을 생성하면 확장자는 .yaml이어야 해요. 포맷된 콘텐츠를 생성하지 않는 템플릿 파일에는 .tpl 확장자를 사용할 수 있어요.

  • 템플릿 파일 이름은 카멜케이스가 아니라 대시 표기법을 사용해야 해요 (my-example-configmap.yaml).

  • 각 리소스 정의는 고유한 템플릿 파일에 있어야 해요.

  • 템플릿 파일 이름은 이름에 리소스 종류를 반영해야 해요. 예: foo-pod.yaml, bar-svc.yaml.

정의된 템플릿의 이름 (Names of Defined Templates)

정의된 템플릿({{ define }} 지시문 안에서 생성된 템플릿)은 전역적으로 접근 가능해요. 즉, 차트와 그 모든 서브차트는 {{ define }}로 생성된 모든 템플릿에 접근할 수 있어요.

그러므로 모든 정의된 템플릿 이름은 네임스페이스화되어야 해요.

올바른 예:

{{- define "nginx.fullname" }}
{{/* ... */}}
{{ end -}}

잘못된 예:

{{- define "fullname" -}}
{{/* ... */}}
{{ end -}}

새 차트는 helm create 명령으로 만들 것을 강력히 권장해요. 템플릿 이름이 이 모범 사례에 따라 자동으로 정의되기 때문이에요.

템플릿 포맷팅 (Formatting Templates)

템플릿은 두 칸 공백으로 들여써야 해요 (탭 절대 안 됨).

템플릿 지시문은 여는 중괄호 뒤와 닫는 중괄호 앞에 공백이 있어야 해요:

올바른 예:

{{ .foo }}
{{ print "foo" }}
{{- print "bar" -}}

잘못된 예:

{{.foo}}
{{print "foo"}}
{{-print "bar"-}}

가능한 곳에서는 템플릿이 공백을 chomp(잘라내기)해야 해요:

foo:
  {{- range .Values.items }}
  {{ . }}
  {{ end -}}

블록(제어 구조 같은)은 템플릿 코드의 흐름을 나타내도록 들여쓸 수 있어요.

{{ if $foo -}}
  {{- with .Bar }}Hello{{ end -}}
{{- end -}}

하지만 YAML은 공백 중심의 언어이므로 코드 들여쓰기가 그 규칙을 따르는 것이 항상 가능한 것은 아니에요.

생성된 템플릿의 공백 (Whitespace in Generated Templates)

생성된 템플릿의 공백 양은 최소로 유지하는 것이 좋아요. 특히 여러 빈 줄이 서로 인접해서 나타나서는 안 돼요. 하지만 가끔의 빈 줄(특히 논리적 섹션 사이)은 괜찮아요.

이것이 가장 좋아요:

apiVersion: batch/v1
kind: Job
metadata:
  name: example
  labels:
    first: first
    second: second

이것은 괜찮아요:

apiVersion: batch/v1
kind: Job

metadata:
  name: example

  labels:
    first: first
    second: second

하지만 이것은 피해야 해요:

apiVersion: batch/v1
kind: Job

metadata:
  name: example

  labels:
    first: first

    second: second

주석 (YAML 주석 vs. 템플릿 주석) (Comments (YAML Comments vs. Template Comments))

YAML과 Helm 템플릿 모두 주석 표시가 있어요.

YAML 주석:

# This is a comment
type: sprocket

템플릿 주석:

{{- /*
This is a comment.
*/}}
type: frobnitz

템플릿 주석은 템플릿의 기능을 문서화할 때 사용해야 해요. 예를 들어 정의된 템플릿을 설명할 때요:

{{- /*
mychart.shortname provides a 6 char truncated version of the release name.
*/}}
{{ define "mychart.shortname" -}}
{{ .Release.Name | trunc 6 }}
{{- end -}}

템플릿 안에서 YAML 주석은 Helm 사용자가 디버깅 중에 (어쩌면) 주석을 볼 수 있는 것이 유용할 때 사용할 수 있어요.

# This may cause problems if the value is more than 100Gi
memory: {{ .Values.maxMem | quote }}

위 주석은 사용자가 helm install --debug를 실행할 때 보이지만, {{- /* */}} 섹션에 지정된 주석은 보이지 않아요.

특정 템플릿 함수가 필요로 할 수 있는 Helm 값이 포함된 템플릿 섹션에 # YAML 주석을 추가하는 것에 주의하세요.

예를 들어 위 예제에 required 함수가 도입되고 maxMem이 설정되지 않으면, # YAML 주석이 렌더링 오류를 일으킬 수 있어요.

올바른 예: helm template는 이 블록을 렌더링하지 않아요

{{- /*
# This may cause problems if the value is more than 100Gi
memory: {{ required "maxMem must be set" .Values.maxMem | quote }}
*/ -}}

잘못된 예: helm template는 Error: execution error at (templates/test.yaml:2:13): maxMem must be set을 반환해요

# This may cause problems if the value is more than 100Gi
# memory: {{ required "maxMem must be set" .Values.maxMem | quote }}

YAML 주석이 그대로 남는 이러한 동작의 또 다른 예는 템플릿 디버깅을 검토하세요.

템플릿과 템플릿 출력에서의 JSON 사용 (Use of JSON in Templates and Template Output)

YAML은 JSON의 상위 집합이에요. 어떤 경우에는 JSON 구문을 사용하는 것이 다른 YAML 표현보다 더 읽기 쉬울 수 있어요.

예를 들어 이 YAML은 리스트를 표현하는 일반적인 YAML 방식에 가까워요:

arguments:
  - "--dirname"
  - "/foo"

하지만 JSON 리스트 스타일로 접으면 읽기 더 쉬워요:

arguments: ["--dirname", "/foo"]

가독성을 높이기 위해 JSON을 사용하는 것은 좋아요. 하지만 더 복잡한 구문을 표현하는 데 JSON 구문을 사용해서는 안 돼요.

YAML 안에 임베디드된 순수 JSON(예: init 컨테이너 구성)을 다룰 때는 당연히 JSON 형식을 사용하는 것이 적절해요.

더 알아보기 (Learn more)