Values
Values
이 문서는 모범 사례 가이드에서 values 사용법을 다뤄요. 차트의 values.yaml 파일 설계에 초점을 맞춰 values를 어떻게 구조화하고 사용해야 하는지 권장 사항을 제시해요.
출처: 문서
본문
이 모범 사례 가이드의 이 부분은 values 사용법을 다뤄요. 이 부분에서는 차트의 values.yaml 파일 설계에 초점을 맞춰 values를 어떻게 구조화하고 사용해야 하는지 권장 사항을 제공해요.
명명 규칙 (Naming Conventions)
변수 이름은 소문자로 시작해야 하고, 단어는 카멜케이스로 구분해야 해요:
올바른 예:
chicken: true
chickenNoodleSoup: true
잘못된 예:
Chicken: true # 대문자 시작은 내장 변수와 충돌할 수 있음
chicken-noodle-soup: true # 이름에 하이픈을 사용하지 마세요
Helm의 내장 변수는 모두 대문자로 시작해서 사용자 정의 값과 쉽게 구분된다는 점에 유의하세요: .Release.Name, .Capabilities.KubeVersion.
평탄한 값 vs 중첩된 값 (Flat or Nested Values)
YAML은 유연한 형식이라 값은 깊게 중첩되거나 평탄하게 펼쳐질 수 있어요.
중첩:
server:
name: nginx
port: 80
평탄:
serverName: nginx
serverPort: 80
대부분의 경우 중첩보다는 평탄한 구조를 선호해야 해요. 템플릿 개발자와 사용자에게 더 단순하기 때문이에요.
최적의 안전성을 위해 중첩된 값은 모든 레벨에서 검사해야 해요:
{{ if .Values.server }}
{{ default "none" .Values.server.name }}
{{ end }}
중첩의 각 레이어마다 존재 검사(existence check)를 해야 해요. 하지만 평탄한 구성에서는 그러한 검사를 생략할 수 있어 템플릿을 읽고 사용하기 더 쉬워져요.
{{ default "none" .Values.serverName }}
연관된 변수가 많고 그중 적어도 하나가 필수(비선택)일 때는 가독성을 높이기 위해 중첩된 값을 사용해도 돼요.
타입을 명확히 하기 (Make Types Clear)
YAML의 타입 강제 변환(유형 강제) 규칙은 때로 직관에 반해요. 예를 들어 foo: false는 foo: "false"와 같지 않아요. foo: 12345678 같은 큰 정수는 어떤 경우에는 과학적 표기법으로 변환돼요.
타입 변환 오류를 피하는 가장 쉬운 방법은 문자열에 대해서는 명시적으로, 나머지에는 암시적으로 두는 거예요. 즉, 간단히 말해 모든 문자열을 따옴표로 감싸세요.
정수 캐스팅 문제를 피하기 위해 정수를 문자열로 저장한 다음 템플릿에서 {{ int $value }}를 사용해 문자열을 다시 정수로 변환하는 것이 유리할 때가 많아요.
대부분의 경우 명시적 타입 태그가 존중되므로 foo: !!string 1234는 1234를 문자열로 취급해야 해요. 하지만 YAML 파서는 태그를 소비하므로 한 번 파싱하면 타입 데이터는 사라져요.
사용자가 값을 어떻게 사용할지 고려하기 (Consider How Users Will Use Your Values)
값에는 세 가지 잠재적 출처가 있어요:
-
차트의
values.yaml파일 -
helm install -f또는helm upgrade -f로 제공되는 values 파일 -
helm install또는helm upgrade의--set또는--set-string플래그로 전달되는 값
values 구조를 설계할 때는 차트 사용자가 -f 플래그나 --set 옵션을 통해 값을 오버라이드하려 할 수 있다는 점을 염두에 두세요.
--set은 표현력이 더 제한적이므로, values.yaml 파일을 작성하는 첫 번째 지침은 --set에서 오버라이드하기 쉽게 만들기예요.
이런 이유로 values 파일을 맵(map)을 사용해 구조화하는 것이 더 좋을 때가 많아요.
--set으로 사용하기 어려운 예:
servers:
- name: foo
port: 80
- name: bar
port: 81
위 내용은 Helm <=2.4에서는 --set으로 표현할 수 없어요. Helm 2.5에서 foo의 포트에 접근하려면 --set servers[0].port=80이에요. 사용자가 알아내기 더 어려울 뿐만 아니라 나중에 servers의 순서가 바뀌면 오류가 발생하기 쉬워요.
사용하기 쉬운 예:
servers:
foo:
port: 80
bar:
port: 81
foo의 포트에 접근하는 것이 훨씬 명확해요: --set servers.foo.port=80.
values.yaml 문서화하기 (Document 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
각 주석을 문서화 대상 매개변수의 이름으로 시작하면 grep으로 문서를 추출하기 쉬워지고, 문서화 도구가 문서 문자열과 설명 대상 매개변수를 안정적으로 연관 지을 수 있게 돼요.