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

Втулки 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.

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

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

helm env

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

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

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

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

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

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

Файл plugin.yaml​

Файл plugin.yaml обовʼязковий для втулка та містить такі поля:

name: Імʼя втулка (ОБОВʼЯЗКОВО)
version: Версія SemVer 2 (ОБОВʼЯЗКОВО)
usage: Однорядковий текст використання, що відображається в довідці
description: Розгорнутий опис, що відображається, наприклад, у helm help
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:
  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: get the last release name
description: get the last release name
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: або 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 буде розбирати глобальні прапорці для власного використання. Жоден з цих прапорців не передається втулку.

  • --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

Складніший приклад для втулка 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>