Перейти до основного вмісту
Версія: 4.0.0

Втулки Helm

попередження

Цю сторінку ще не було оновлено для Helm 4. Деякі відомості можуть бути неточними або не стосуватися Helm 4. Докладнішу інформацію про нові функції, вдосконалення та істотні зміни в Helm 4 див. в Огляді Helm 4.

Втулок 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. Ви також можете встановлювати втулки з архівів безпосередньо з 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: Ігнорувати прапорці передані з Helm
platformCommand: # Параметри конфігурації команди для виконання залежно від платформи
  - os: Відповідність ОС, може бути порожньою або відсутньою для відповідності всім ОС
    arch: Відповідність архітектури, може бути порожньою або відсутньою для відповідності всім архітектурам
    command: Команда втулка для запуску
    args: Аргументи команди втулка
command: (ЗАСТАРІЛЕ) Команда втулка, використовуйте  platformCommand натомість
platformHooks: # Параметри життєвого циклу втулка залежно від платформи
  install: # Параметри команд встановлення життєвого циклу
    - os: Відповідність ОС, може бути порожньою або відсутньою для відповідності всім ОС
      arch: Відповідність архітектури, може бути порожньою або відсутньою для відповідності всім архітектурам
      command: Команда встановлення втулка для виконання
      args: Аргументи команди встановлення втулка
  update: # Параметри команд оновлення життєвого циклу
    - os: Відповідність ОС, може бути порожньою або відсутньою для відповідності всім ОС
      arch: Відповідність архітектури, може бути порожньою або відсутньою для відповідності всім архітектурам
      command: Команда оновлення втулка для виконання
      args: Аргументи команди оновлення втулка
  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: демонстраційний втулок
description: демонстраційний втулок
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 and -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>

Примітки:

  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

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

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

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

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

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

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>