Значення

Ця частина посібника з найкращих практик охоплює використання значень. Ми надаємо рекомендації щодо структурування та використання значень, зосереджуючись на дизайні файлу values.yaml чарту.

Домовленості щодо назв

Назви змінних повинні починатися з малої літери, а слова мають розділятися верблюжим регістром (camelCase):

Правильно:

chicken: true
chickenNoodleSoup: true

Неправильно:

Chicken: true  # початкова велика літера може конфліктувати з вбудованими змінними
chicken-noodle-soup: true # не використовуйте дефіси в назвах

Зверніть увагу, що всі вбудовані змінні Helm починаються з великої літери, щоб їх легко було відрізнити від користувацьких значень: .Release.Name, .Capabilities.KubeVersion.

Пласкі або вкладені значення

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: false не те саме, що і foo: "false". Великі цілі числа, такі як foo: 12345678, у деяких випадках будуть перетворюватися на наукову нотацію.

Найпростіший спосіб уникнути помилок перетворення типів — бути явним щодо рядків і неявним щодо всього іншого. Або, коротко кажучи, беріть всі рядки в лапки.

Часто для уникнення проблем із перетворенням чисел наукової нотації вигідно зберігати ваші цілі числа у вигляді рядків і використовувати {{ int $value }} у шаблоні для перетворення з рядкового значення назад на ціле число.

У більшості випадків явні типи поважаються, тому foo: !!string 1234 має обробляти 1234 як рядок. Проте парсер YAML споживає теґи, тому дані про типи втрачаються після одного аналізу.

Розгляд використання ваших значень користувачами

Існує три потенційні джерела значень:

Файл values.yaml чарту
Файл значень, переданий за допомогою helm install -f або helm upgrade -f
Значення, передані з прапорцем --set або --set-string під час helm install або helm upgrade

При проєктуванні структури ваших значень майте на увазі, що користувачі вашого чарту можуть захотіти перевизначити їх за допомогою прапорця -f або опції --set.

Оскільки --set більш обмежений у виразності, перше правило написання файлу values.yaml — зробіть його зручним для перевизначення за допомогою --set.

З цієї причини часто краще структурувати файл значень, використовуючи map.

Важко використовувати з --set:

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

Вищенаведене не можна виразити за допомогою --set у Helm <=2.4. У Helm 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 повинна бути задокументована. Рядок документації повинен починатися з назви властивості, яку він описує, а потім надавати принаймні одне речення опису.