Руководство по плагинам Helm

Плагин Helm — это инструмент, доступный через CLI helm, но не являющийся частью встроенной кодовой базы Helm.

Существующие плагины можно найти в разделе связанные проекты или в результатах поиска на GitHub.

В этом руководстве описывается, как использовать и создавать плагины.

Обзор

Плагины Helm — это дополнительные инструменты, которые легко интегрируются с Helm. Они позволяют расширять основную функциональность Helm без необходимости писать каждую новую возможность на Go и добавлять её в основной инструмент.

Плагины 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. Вы также можете установить плагин непосредственно из 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 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: # (Устарело) Хуки жизненного цикла плагина, используйте 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: 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: должен быть упакован в директорию плагина или установлен через хук.
• В строке platformCommand: или command: все переменные окружения будут раскрыты перед выполнением. $HELM_PLUGIN_DIR будет указывать на директорию плагина.
• Сама команда не выполняется в оболочке. Поэтому нельзя записать shell-скрипт в одну строку.
• 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: Указывает, был ли установлен флаг debug в helm.
• HELM_REGISTRY_CONFIG: Расположение конфигурации реестра (при использовании). Обратите внимание, что использование Helm с реестрами является экспериментальной возможностью.
• HELM_REPOSITORY_CACHE: Путь к файлам кеша репозиториев.
• HELM_REPOSITORY_CONFIG: Путь к файлу конфигурации репозиториев.
• HELM_NAMESPACE: 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:
     <и так далее, рекурсивно>

Примечания:

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 может вывести все имена релизов (в namespace 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>