Втулки 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. Якщо ви встановлюєте з VCS, ви можете вказати версію за допомогою аргументу --version.

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

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

Структура файлів втулка

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

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

Файл plugin.yaml

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

name: Назва втулка (ОБОВʼЯЗКОВО)
version: Версія в форматі SemVer 2 (ОБОВʼЯЗКОВО)
usage: Однорядковий текст використання, який показується у довідці
description: Довгий опис, який покзується в таких місцях як довідка helm
ignoreFlags: Ignore flags передані з Helm
platformCommand: # Налаштування команди запуску в залежності від платформи
  - os: Відповідність ОС, може бути порожнім або пропущеним, щоб відповідати всім ОС
    arch: Відповідність архітектурі, може бути порожнім або пропущеним, щоб відповідати всім архітектурам
    command: Команда втулка для виконання
    args: Аргументи команди втулка
command: (ЗАСТАРІЛО) Команда втулка, замість неї використовуйте platformCommand
platformHooks: # Налаштування життєвого циклу в залежності від платформи
  install: # Команди життевого циклу Install
    - os: Відповідність ОС, може бути порожнім або пропущеним, щоб відповідати всім ОС
      arch: Відповідність архітектурі, може бути порожнім або пропущеним, щоб відповідати всім архітектурам
      command: Команда встановлення втулка
      args: Аргументи команди встановлення втулка
  update: # Команди життевого циклу Update
    - os: Відповідність ОС, може бути порожнім або пропущеним, щоб відповідати всім ОС
      arch: Відповідність архітектурі, може бути порожнім або пропущеним, щоб відповідати всім архітектурам
      command: Команди оновлення втулка
      args: Аргументи команди оновлення втука
  delete: # Команди життевого циклу Delete
    - os: Відповідність ОС, може бути порожнім або пропущеним, щоб відповідати всім ОС
      arch: Відповідність архітектурі, може бути порожнім або пропущеним, щоб відповідати всім архітектурам
      command: Команди вилучення втулка
      args: Аргументи команди вилучення втулка
hooks: # (Застаріло) Хуки життʼвого циклу втулка, натомість використовуйте platformHooks
  install: Команда встановлення втулка
  update: Команда оновлення втулка
  delete: Команда вилучення втулка
downloaders: # Налаштування можливостей завантажувачів
  - command: Команда для виклику
    protocols:
      - Підтримувана схема протоколу

Поле `name`

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

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

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

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

Поле `version`

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

Поле `ignoreFlags`

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

Поле `platformCommand`

Параметр platformCommand налаштовує команду, яку виконуватиме втулок під час виклику. Ви не можете встановити обидва значення platformCommand та command, оскільки це призведе до помилки. Наступні правила будуть застосовуватися при прийнятті рішення про те, яку команду використовувати:

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

Поле `platformHooks`

За допомогою platformHooks налаштовуються команди, які втулок буде виконувати для подій життєвого циклу. Ви не можете встановити одночасно platformHooks та hooks, оскільки це призведе до помилки. Наступні правила будуть застосовуватися при прийнятті рішення про те, яку команду хука використовувати:

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

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

Тут описано YAML для простого втулка, який допомагає отримати останню назву випуску:

name: last
version: 0.1.0
usage: отримує назву останнього випуску
description: отримує опис останнього випуску
ignoreFlags: false
platformCommand:
  - command: ${HELM_BIN}
    args:
      - list
      - --short
      - --max=1
      - --date
      - -r

Втулки можуть потребувати додаткових скриптів і виконуваних файлів. Скрипти можна включити до теки втулка, а виконувані файли можна завантажити за допомогою хука. Нижче наведено приклад втулка:

$HELM_PLUGINS/
  |- myplugin/
    |- scripts/
      |- install.ps1
      |- install.sh
    |- plugin.yaml

name: myplugin
version: 0.1.0
usage: example plugin
description: example plugin
ignoreFlags: false
platformCommand:
  - command: ${HELM_PLUGIN_DIR}/bin/myplugin
  - os: windows
    command: ${HELM_PLUGIN_DIR}\bin\myplugin.exe
platformHooks:
  install:
    - command: ${HELM_PLUGIN_DIR}/scripts/install.sh
    - os: windows
      command: pwsh
      args:
        - -c
        - ${HELM_PLUGIN_DIR}\scripts\install.ps1
  update:
    - command: ${HELM_PLUGIN_DIR}/scripts/install.sh
      args:
        - -u
    - os: windows
      command: pwsh
      args:
        - -c
        - ${HELM_PLUGIN_DIR}\scripts\install.ps1
        - -Update

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

Команди втулка

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

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

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

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

helm env

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

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

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

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

Стандартно 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 буде розбирати глобальні прапорці для власного використання. Жоден з цих прапорців не передається втулку.

--burst-limit: Це перетворюється в $HELM_BURST_LIMIT
--debug: Якщо цей прапорець вказаний, $HELM_DEBUG встановлюється в 1
--kube-apiserver: Це перетворюється в $HELM_KUBEAPISERVER
--kube-as-group: Це перетворюється в $HELM_KUBEASGROUPS
--kube-as-user: Це перетворюється в $HELM_KUBEASUSER
--kube-ca-file: Це перетворюється в $HELM_KUBECAFILE
--kube-context: Це перетворюється в $HELM_KUBECONTEXT
--kube-insecure-skip-tls-verify: Це перетворюється в $HELM_KUBEINSECURE_SKIP_TLS_VERIFY
--kube-tls-server-name: Це перетворюється в $HELM_KUBETLS_SERVER_NAME
--kube-token: Це перетворюється в $HELM_KUBETOKEN
--kubeconfig: Це перетворюється в $KUBECONFIG
--namespace та -n: Це перетворюється в $HELM_NAMESPACE
--qps: Це перетворюється в $HELM_QPS
--registry-config: Це перетворюється в $HELM_REGISTRY_CONFIG
--repository-cache: Це перетворюється в $HELM_REPOSITORY_CACHE
--repository-config: Це перетворюється в $HELM_REPOSITORY_CONFIG

Втулки повинні відображати текст довідки та виходити для -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>

Примітки:

Усі секції є необовʼязковими, але їх слід надати, якщо треба.
Прапорці не повинні включати префікс - або --.
Як короткі, так і довгі прапорці можуть і повинні бути вказані. Короткий прапорець не потребує асоціації з відповідною довгою формою, але обидві форми слід перерахувати.
Прапорці не потрібно упорядковувати будь-яким чином, але їх слід перераховувати в правильному місці в ієрархії підкоманд файлу.
Глобальні прапорці Helm вже обробляються механізмом автозавершення Helm, тому втулкам не потрібно вказувати наступні прапорці --debug, --namespace або -n, --kube-context, і --kubeconfig, або будь-які інші глобальні прапорці.
Список 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 і, якщо знайде його, вивести правильні завершення.

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

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