이 부분은 모범사례 가이드의 일부로서 값(values)을 사용하는 방법을 다룬다. 여기서는 차트의 values.yaml 파일을 설계하는 데 초점을 맞추고, 값을 어떻게 구성하고 사용할지에 대한 권고사항을 제시한다.

네이밍 컨벤션

변수 이름은 소문자로 시작해야하며 단어는 카멜케이스로 구분해야 한다.

올바른 경우:

chicken: true
chickenNoodleSoup: true

잘못된 경우:

Chicken: true  # 첫 글자가 대문자이면 빌트인 변수와 충돌이 발생할 수 있다
chicken-noodle-soup: true # 변수명에 하이픈(-)을 사용하지 말자

헬름의 모든 빌트인 변수는 사용자 정의 값과 쉽게 구분할 수 있도록 대문자로 시작한다: .Release.Name, .Capabilities.KubeVersion.

평면화(flat) 값, 중첩된(nested) 값

YAML 은 유연한 형식으로, 값은 깊게 중첩되거나 평면화 될 수 있다.

중첩된 경우:

server:
  name: nginx
  port: 80

평면화된 경우:

serverName: nginx
serverPort: 80

대부분의 경우, 중첩된 경우보다는 평면화된 경우를 선호하게 된다. 그 이유는 템플릿 개발자와 사용자에게 더 간단하기 때문이다.

최적의 안전성을 위해, 모든 수준에서 중첩된 값을 확인해야 한다.

{{ if .Values.server }}
  {{ default "none" .Values.server.name }}
{{ end }}

모든 중첩된 계층에 대하여 존재 유무를 점검해야 한다. 다만 평면화된 구성의 경우, 이러한 검사를 건너뛸 수 있으므로 템플릿을 더 쉽게 읽고 사용할 수 있다.

{{ default "none" .Values.serverName }}

관련 변수가 많고 그 중 하나 이상이 선택 사항이 아닌 경우, 중첩된 값을 사용하여 가독성을 높일 수 있다.

자료형을 명확히 하자

YAML 의 유형에 대한 강제적인 규칙은 때때로 직관적이지 못하다. 예를 들어 foo: falsefoo: "false" 와 동일하지 않다. foo: 12345678 과 같은 큰 정수는 경우에 따라 수학적 표기법으로 변환된다.

유형 변환 오류를 피하는 가장 쉬운 방법은 문자열에 대해서만 명시하고 이 외에는 명시하지 않는 것이다. 혹은 더 간단하게, 모두 인용부호로 감싸서 문자열로 만드는 것이다.

종종 정수형의 캐스팅 문제를 방지하기위해, 정수도 문자열로 저장하고 템플릿에서 {{ int $value }} 를 사용하여 문자열에서 다시 정수로 변환하는 것이 유리하다.

대부분의 경우 명시적 유형 태그가 존중되므로 foo: !!string 12341234 를 문자열로 처리해야 한다. 그러나 YAML 파서는 태그를 사용하므로 한번의 구문 분석 후에는 유형 데이터가 손실된다.

사용자가 값을 어떻게 사용할지를 고려하자

값에는 다음과 같은 세 가지 출처가 있다. There are three potential sources of values:

  • 차트의 values.yaml 파일
  • helm install -f 또는 helm upgrade -f 에서 제공하는 값 파일
  • helm install 또는 helm upgrade--set 또는 --set-string 플래그에 전달된 값

값의 구조를 디자인 할 때 차트 사용자는 -f 플래그 또는 --set 옵션을 통해 값을 재정의 할 수 있다.

--set 은 표현력이 더 제한적이므로, values.yaml 파일을 작성하기 위한 첫 번째 지침은, --set 에서 쉽게 재정의 할 수 있도록 하는 것이다.

이러한 이유로 맵을 사용하여 값 파일을 구조화하는 것이 더 좋다.

--set 과 함께 사용하기 어려운 경우

servers:
  - name: foo
    port: 80
  - name: bar
    port: 81

위의 내용은 헬름 <=2.4 에서는 --set 으로 표현할 수 없다. 헬름 2.5 에서 foo 의 포트에 액세스 하는 것은 --set servers[0].port=80 이다. 사용자가 파악하기 어려울 뿐만 아니라 나중에 서버 의 순서가 변경되면 오류가 발생하기 쉽다.

사용하기 쉬운 경우:

servers:
  foo:
    port: 80
  bar:
    port: 81

foo 의 포트에 접근하는 것이 훨씬 명확하다: --set servers.foo.port=80.

values.yaml을 문서화하자

values.yaml 에 정의된 모든 속성은 문서화 되어야 한다. 문서 문자열은 설명하는 속성의 이름으로 시작하고 최소한 한 문장으로 된 설명을 제공해야 한다.

잘못된 경우:

# the host name for the webserver
serverHost: example
serverPort: 9191

올바른 경우:

# serverHost is the host name for the webserver
serverHost: example
# serverPort is the HTTP listener port for the webserver
serverPort: 9191

각 주석을 문서화하는 매개 변수의 이름으로 시작하면 문서를 쉽게 정리할 수 있으며, 문서화 도구가 문서 문자열과 이를 설명하는 매개변수를 안정적으로 연관시킬 수 있게 해준다.