Втулки Helm

Втулок Helm — це інструмент, до якого можна отримати доступ через CLI helm, але який не є частиною основного коду Helm.

Наявні втулки можна знайти у відповідному розділі або шукаючи на GitHub.

Цей посібник пояснює, як використовувати та створювати втулки.

Огляд

Втулки Helm є додатковими інструментами, які безперешкодно інтегруються з Helm. Вони надають спосіб розширення основного набору функцій Helm без потреби написання кожної нової функції на Go і додавання її до основного інструменту.

Втулки Helm мають такі особливості:

• Їх можна додавати та видаляти з установки Helm без впливу на основний інструмент Helm.
• Вони можуть бути написані будь-якою мовою програмування.
• Вони інтегруються з Helm і будуть відображатися в helm help та інших місцях.

Втулки Helm знаходяться в $HELM_PLUGINS. Ви можете дізнатися поточне значення цієї змінної, включаючи стандартні значення, коли не задано в середовищі, за допомогою команди helm env.

Модель втулків Helm частково моделюється на основі моделі втулків Git. Відповідно, іноді ви можете чути, що helm називають porcelain шаром, а втулки — plumbing. Це скорочений спосіб зазначити, що Helm забезпечує користувацький досвід і верхній рівень обробки логіки, тоді як втулки виконують "детальну роботу" для виконання бажаної дії.

Встановлення втулка

Втулки встановлюються за допомогою команди $ helm plugin install <path|url>. Ви можете передати шлях до втулка у вашій локальній файловій системі або URL віддаленого репозиторію VCS. Команда helm plugin install клонуватиме або копіюватиме втулок за вказаним шляхом/URL у $HELM_PLUGINS.

$ helm plugin install https://github.com/adamreese/helm-env

Якщо у вас є дистрибутив втулка у форматі tar, просто розпакуйте втулок у теку $HELM_PLUGINS. Ви також можете встановлювати втулки tarball безпосередньо з URL, використовуючи helm plugin install https://domain/path/to/plugin.tar.gz.

Тестування локально створеного втулка

Спочатку вам потрібно знайти шлях до HELM_PLUGINS, для цього виконайте наступну команду:

helm env

Змініть поточну теку на теку, в яку встановлено HELM_PLUGINS.

Тепер ви можете додати символічне посилання на збірку вашого втулка, у цьому прикладі ми зробили це для mapkubeapis.

ln -s ~/GitHub/helm-mapkubeapis ./helm-mapkubeapis

Створення втулків

З усіх боків втулок схожий на чарт. Кожен втулок має теку верхнього рівня, а також файл plugin.yaml.

$HELM_PLUGINS/
  |- last/
      |
      |- plugin.yaml
      |- last.sh

У наведеному прикладі втулок last міститься у теці, що називається last. Він має два файли: plugin.yaml (обовʼязковий) та виконуваний скрипт, last.sh (необовʼязковий).

Ядро втулка — це простий YAML файл, названий plugin.yaml. Ось YAML для втулка, який допомагає отримати останню назву релізу:

name: "last"
version: "0.1.0"
usage: "отримати останню назву релізу"
description: "отримати останню назву релізу"
ignoreFlags: false
command: "$HELM_BIN --host $TILLER_HOST list --short --max 1 --date -r"
platformCommand:
  - os: linux
    arch: i386
    command: "$HELM_BIN list --short --max 1 --date -r"
  - os: linux
    arch: amd64
    command: "$HELM_BIN list --short --max 1 --date -r"
  - os: windows
    arch: amd64
    command: "$HELM_BIN list --short --max 1 --date -r"

name — це імʼя втулка. Коли Helm виконує цей втулок, це імʼя буде використовуватися (наприклад, helm NAME викликає цей втулок).

name повинно відповідати імені теки. У нашому прикладі втулок з name: last має бути поміщений у теку з назвою last.

Обмеження для name:

• name не може дублювати одну з наявних команд на верхньому рівні helm.
• name має бути обмежено символами ASCII a-z, A-Z, 0-9, _ та -.

version — це версія втулка за SemVer 2. usage і description використовуються для створення тексту довідки команди.

Перемикач ignoreFlags вказує Helm, що не слід передавати прапорці втулку. Якщо втулок викликаний з helm myplugin --foo і ignoreFlags: true, тоді --foo буде мовчки відкинуто.

Нарешті, і найголовніше, platformCommand або command — це команда, яку цей втулок виконає, коли його викликають. Розділ platformCommand визначає специфічні для ОС/Архітектури варіації команди. Наступні правила застосовуються при визначенні, яку команду використовувати:

• Якщо platformCommand присутній, він буде перевірений першим.
• Якщо os та arch відповідають поточній платформі, пошук зупиниться, і команда буде використана.
• Якщо os відповідає і немає більш специфічного arch відповідності, команда буде використана.
• Якщо жодної відповідності platformCommand не знайдено, буде використана стандартна команда command.
• Якщо жодної відповідності не знайдено в platformCommand і command не присутній, Helm завершить виконання з помилкою.

Змінні середовища підставляються перед виконанням втулка. Шаблон вище ілюструє рекомендований спосіб вказівки, де знаходиться програма втулка.

Є кілька стратегій для роботи з командами втулків:

• Якщо втулок включає виконуваний файл, виконуваний файл для platformCommand: або command: має бути упакований у теку втулка.
• Рядок platformCommand: або command: буде мати розширені змінні середовища перед виконанням. $HELM_PLUGIN_DIR вказуватиме на теку втулка.
• Команда сама по собі не виконується в оболонці. Тому ви не можете використовувати однорядковий скрипт оболонки.
• Helm вбудовує багато конфігурацій у змінні середовища. Ознайомтеся з середовищем, щоб дізнатися, яка інформація доступна.
• Helm не робить припущень щодо мови втулка. Ви можете написати його будь-якою мовою, яка вам подобається.
• Команди відповідають за реалізацію специфічного тексту допомоги для -h та --help. Helm використовуватиме usage та description для helm help та helm help myplugin, але не обробляє helm myplugin --help.

Завантажувач втулків

Стандартно Helm здатен завантажувати чарти за допомогою HTTP/S. Починаючи з версії Helm 2.4.0, втулки можуть мати спеціальну можливість завантажувати чарти з довільних джерел.

Втулки повинні оголосити цю спеціальну можливість у файлі plugin.yaml (на верхньому рівні):

downloaders:
- command: "bin/mydownloader"
  protocols:
  - "myprotocol"
  - "myprotocols"

Якщо такий втулок встановлений, Helm може взаємодіяти з репозиторієм, використовуючи вказану схему протоколу, викликавши command. Спеціальний репозиторій слід додати так само як і звичайні: helm repo add favorite myprotocol://example.com/. Правила для спеціальних репозиторіїв такі ж, як і для звичайних: Helm повинен бути здатен завантажити файл index.yaml, щоб виявити та зберегти список доступних чартів.

Визначена команда буде викликана за схемою: command certFile keyFile caFile full-URL. Облікові відомості SSL беруться з визначення репозиторію, що зберігається в $HELM_REPOSITORY_CONFIG (тобто $HELM_CONFIG_HOME/repositories.yaml). Очікується, що команда завантажувача виведе сирий контент на stdout і повідомить про помилки на stderr.

Команда завантажувача також підтримує підкоманди або аргументи, що дозволяє, наприклад, вказати bin/mydownloader subcommand -d у plugin.yaml. Це корисно, якщо ви хочете використовувати один і той же виконуваний файл для основної команди втулка та команди завантажувача, але з різною підкомандою для кожної.

Змінні середовища

Коли Helm виконує втулок, він передає зовнішнє середовище втулку та також вбудовує деякі додаткові змінні середовища.

Змінні, такі як KUBECONFIG, встановлюються для втулка, якщо вони встановлені у зовнішньому середовищі.

Гарантовано будуть встановлені такі змінні:

• HELM_PLUGINS: Шлях до теки втулків.
• HELM_PLUGIN_NAME: Імʼя втулка, яке використовується при виклику через helm. Тобто helm myplug матиме коротке імʼя myplug.
• HELM_PLUGIN_DIR: Тека, що містить втулок.
• HELM_BIN: Шлях до команди helm (як виконана користувачем).
• HELM_DEBUG: Вказує, чи був встановлений прапорець налагодження.
• HELM_REGISTRY_CONFIG: Місце для конфігурації реєстру (якщо використовується). Зазначте, що використання Helm з реєстрами є експериментальною функцією.
• HELM_REPOSITORY_CACHE: Шлях до кеш-файлів репозиторіїв.
• HELM_REPOSITORY_CONFIG: Шлях до файлу конфігурації репозиторію.
• HELM_NAMESPACE: Простір імен, вказаний команді helm (зазвичай за допомогою прапорця -n).
• HELM_KUBECONTEXT: Назва контексту конфігурації Kubernetes, наданого команді helm.

Крім того, якщо конфігураційний файл Kubernetes був явно вказаний, він буде встановлений як змінна KUBECONFIG.

Примітка про парсинг прапорців

При виконанні втулка Helm буде розбирати глобальні прапорці для власного використання. Жоден з цих пропорців не передається втулку.

• --debug: Якщо цей прапорець вказаний, $HELM_DEBUG встановлюється в 1.
• --registry-config: Це перетворюється в $HELM_REGISTRY_CONFIG.
• --repository-cache: Це перетворюється в $HELM_REPOSITORY_CACHE.
• --repository-config: Це перетворюється в $HELM_REPOSITORY_CONFIG.
• --namespace та -n: Це перетворюється в $HELM_NAMESPACE.
• --kube-context: Це перетворюється в $HELM_KUBECONTEXT.
• --kubeconfig: Це перетворюється в $KUBECONFIG.

Втулки повинні відображати текст довідки та виходити для -h та --help. У всіх інших випадках втулки можуть використовувати прапорці за потреби.

Надання автозавершення оболонки

Починаючи з Helm 3.2, втулок може додатково підтримувати автозавершення оболонки як частину наявного механізму автозавершення Helm.

Статичне автозавершення

Якщо втулок надає свої власні прапорці та/або підкоманди, він може сповістити Helm про них, маючи файл completion.yaml, розташований у кореневій теці втулка. Файл completion.yaml має форму:

name: <pluginName>
flags:
- <flag 1>
- <flag 2>
validArgs:
- <arg value 1>
- <arg value 2>
commands:
  name: <commandName>
  flags:
  - <flag 1>
  - <flag 2>
  validArgs:
  - <arg value 1>
  - <arg value 2>
  commands:
     <and so on, recursively>

Примітки:

1. Усі секції є необовʼязковими, але їх слід надати, якщо треба.
2. Прапорці не повинні включати префікс - або --.
3. Як короткі, так і довгі прапорці можуть і повинні бути вказані. Короткий прапорець не потребує асоціації з відповідною довгою формою, але обидві форми слід перерахувати.
4. Прапорці не потрібно упорядковувати будь-яким чином, але їх слід перераховувати в правильному місці в ієрархії підкоманд файлу.
5. Глобальні прапорці Helm вже обробляються механізмом автозавершення Helm, тому втулкам не потрібно вказувати наступні прапорці --debug, --namespace або -n, --kube-context, і --kubeconfig, або будь-які інші глобальні прапорці.
6. Список validArgs надає статичний список можливих завершень для першого параметра після підкоманди. Можливо не завжди надати такий список заздалегідь (див. розділ Динамічне завершення нижче), у цьому випадку розділ validArgs можна пропустити.

Файл completion.yaml є повністю необовʼязковим. Якщо він не надається, Helm просто не буде надавати автозавершення оболонки для втулка (якщо не підтримується Динамічне завершення втулком). Крім того, додавання файлу completion.yaml є сумісним з попередніми версіями та не вплине на поведінку втулка при використанні старіших версій Helm.

Як приклад, для втулка fullstatus, який не має підкоманд, але приймає ті ж прапорці, що й команда helm status, файл completion.yaml виглядає так:

name: fullstatus
flags:
- o
- output
- revision

Складніший приклад для втулка 2to3, має файл completion.yaml наступного вигляду:

name: 2to3
commands:
- name: cleanup
  flags:
  - config-cleanup
  - dry-run
  - l
  - label
  - release-cleanup
  - s
  - release-storage
  - tiller-cleanup
  - t
  - tiller-ns
  - tiller-out-cluster
- name: convert
  flags:
  - delete-v2-releases
  - dry-run
  - l
  - label
  - s
  - release-storage
  - release-versions-max
  - t
  - tiller-ns
  - tiller-out-cluster
- name: move
  commands:
  - name: config
    flags:
    - dry-run

Динамічне автозавершення

Починаючи з Helm 3.2, втулки можуть надавати динамічне автозавершення оболонки. Динамічне автозавершення забезпечує завершення значень параметрів або прапорців, які не можуть бути визначені заздалегідь. Наприклад, завершення імен Helm релізів, які наразі доступні в кластері.

Щоб втулок підтримував динамічне автозавершення, він повинен надати виконуваний файл з назвою plugin.complete у своїй кореневій теці. Коли скрипт автозавершення Helm потребує динамічного завершення для втулка, він виконає файл plugin.complete, передаючи йому командний рядок, який потрібно завершити. Виконуваний файл plugin.complete повинен містити логіку для визначення правильних варіантів завершення та виводити їх на стандартний вихід, щоб їх можна було спожити скриптом автозавершення Helm.

Файл plugin.complete є повністю необовʼязковим. Якщо він не надається, Helm просто не буде надавати динамічне автозавершення для втулка. Крім того, додавання файлу plugin.complete є сумісним з попередніми версіями та не вплине на поведінку втулка при використанні старіших версій Helm.

Вихідний результат скрипту plugin.complete повинен бути списком, розділеним новими рядками, наприклад:

rel1
rel2
rel3

Коли plugin.complete викликаний, середовище втулка встановлено так само, як і при виклику основного скрипту втулка. Отже, змінні $HELM_NAMESPACE, $HELM_KUBECONTEXT та всі інші змінні втулка вже будуть встановлені, а відповідні глобальні прапорці будуть видалені.

Файл plugin.complete може бути будь-якої виконуваної форми; це може бути shell-скрипт, програма на Go або будь-яка інша програма, яку Helm може виконати. Файл plugin.complete повинен мати права на виконання для користувача. Файл plugin.complete повинен завершитися з кодом успіху (значення 0).

У деяких випадках динамічне завершення вимагатиме отримання інформації з кластера Kubernetes. Наприклад, втулок helm fullstatus потребує імені релізу як вводу. У втулку fullstatus, щоб скрипт plugin.complete надав завершення для поточних імен релізів, він може просто виконати helm list -q і вивести результат.

Якщо ви бажаєте використовувати один і той же виконуваний файл для виконання втулка та для завершення втулка, скрипт plugin.complete може викликати основний виконуваний файл втулка з певним спеціальним параметром або прапорцем; коли основний виконуваний файл втулка виявляє спеціальний параметр або прапорець, він буде знати, що потрібно виконати завершення. У нашому прикладі plugin.complete може бути реалізований так:

#!/usr/bin/env sh

# "$@" є всім командним рядком, який потребує завершення.
# Важливо використовувати подвійні лапки в змінній "$@", щоб зберегти можливий пустий останній параметр.
$HELM_PLUGIN_DIR/status.sh --complete "$@"

Справжній скрипт втулка fullstatus (status.sh) повинен тоді шукати прапорець --complete і, якщо знайде його, вивести правильні завершення.

Поради та підказки

1. Оболонка автоматично відфільтровує варіанти завершення, які не відповідають введенню користувача. Отже, втулок може повернути всі відповідні завершення без видалення тих, які не відповідають введенню користувача. Наприклад, якщо командний рядок helm fullstatus ngin<TAB>, скрипт plugin.complete може вивести всі імена релізів (з простору імен default), а не лише ті, що починаються з ngin; оболонка зберігає лише ті, що починаються з ngin.
2. Щоб спростити підтримку динамічного завершення, особливо якщо у вас складний втулок, ви можете налаштувати скрипт plugin.complete, щоб він викликав основний скрипт втулка і запитував варіанти завершення. Дивіться розділ Динамічне завершення вище для прикладу.
3. Для налагодження динамічного завершення та файлу plugin.complete можна виконати наступне, щоб побачити результати завершення:
   • helm __complete <pluginName> <arguments to complete>. Наприклад:
   • helm __complete fullstatus --output js<ENTER>,
   • helm __complete fullstatus -o json ""<ENTER>