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

Огляд втулків

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

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

Типи втулків​

Наразі Helm має 3 типи втулків:

  • Втулки CLI: дозволяють користувачам додавати додаткові команди CLI helm.
  • Втулки Getter: дозволяють користувачам використовувати чарти та навіть інші втулки в місцях, де ядро Helm не має вбудованої підтримки.
  • Втулки Postrenderer: дозволяють користувачам модифікувати маніфести, отримані в результаті рендерингу чартів, перед їх надсиланням до API Kubernetes.

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

Втулки CLI​

У чому полягає перевага використання втулків для створення командних підпрограм CLI helm порівняно з використанням окремих скриптів або інструментів із власними автономними командами?

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

Втулки Getter​

Helm має вбудовану підтримку для роботи з чартами та втулками у вашій локальній файловій системі або збереженими як артефакти в реєстрах OCI. Чарти також можна зберігати в HTTP-репозиторіях, а втулки — у репозиторіях VCS, таких як Git.

Втулки Helm Getter дозволяють розширити це сховище та поведінку завантаження для підтримки інших місць зберігання. Існують втулки Getter від спільноти для зберігання чартів та втулків у s3 buckets та в інших місцях. Вам знадобляться втулки getter, якщо вам потрібні додаткові опції зберігання для ваших робочих процесів Helm.

Втулки PostRenderer​

Helm дозволяє користувачам налаштовувати чарти, вводячи власні значення. Ці значення, надані користувачами, використовуються чартами для рендерингу маніфестів, які дозволяють Helm керувати вашими застосунками в Kubernetes.

Якщо ви створюєте власні чарти, ви можете оновлювати шаблони, коли вам потрібна додаткова конфігурація для відрендерених маніфестів. Однак, якщо ви використовуєте чарти спільноти, які вам не належать, пост-рендеринг дозволяє модифікувати маніфести після того, як чарти їх відрендерили, але до того, як Helm використовує їх для управління вашими ресурсами Kubernetes. Починаючи з Helm 4, для цього використовуються втулки postrenderer.

Версії API втулків​

Починаючи з Helm 4, файл plugin.yaml, що входить до складу кожного втулка, тепер має поле apiVersion, яке наразі має значення v1.

Старі втулки (до появи версій API) будуть підтримуватися протягом усього терміну дії Helm 4, тому ваші наявні втулки з Helm 3 будуть працювати до Helm 5. Однак вам слід звернутися до авторів ваших улюблених втулків із проханням оновити їх до нової системи версій.

Якщо ви розробник втулків, дізнайтеся більше про це в Посібнику для розробників втулків.

Середовища виконання втулків​

Helm наразі підтримує 2 середовища виконання втулків:

  • Середовище виконання Subprocess
  • Середовище виконання Wasm

Відповідну інформацію про кожне середовище виконання дивіться в Посібнику користувача втулків або Посібнику розробника втулків.

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

Усі файли втулка знаходяться в одній теці, яка використовується для розробки, пакування та встановлення.

Усередині теки втулка Helm очікує таку структуру:

example-plugin
├── plugin.yaml # ОБОВʼЯЗКОВИЙ
├── plugin.sh   # ОПЦІЙНИЙ для середовища Subprocess
└── plugin.wasm # ОБОВʼЯЗКОВИЙ для середовища Wasm
  • Єдиним обовʼязковим файлом є plugin.yaml.
  • Subprocess runtime може опціонально містити один або декілька власних виконуваних файлів, що містять код вашого втулка (може бути Node, Python, Go тощо). Для цього середовища виконання ви можете також викликати будь-який виконуваний файл, що вже доступний у PATH користувача, безпосередньо з поля plugin.yaml runtime configuration platformCommand.
  • Для Wasm runtime вам потрібно буде включити файл .wasm. Це код вашого втулка (може бути Node, Python, Go тощо), скомпільований у Wasm.

Plugin.yaml​

Файл plugin.yaml необхідний для роботи втулка. Це файл YAML, що містить метадані та конфігурацію втулка.

Інформація про метадані​

apiVersion: ОБОВʼЯЗКОВО — Версія API втулка. Повинна бути "v1"
type: ОБОВʼЯЗКОВО — Версія типу втулка. Може бути "cli/v1", "getter/v1" або "postrenderer/v1"
name: ОБОВʼЯЗКОВО — Назва втулка
version: ОБОВ'ЯЗКОВО — Версія втулка
runtime: ОБОВ'ЯЗКОВО — Час виконання втулка. Може бути "subprocess" або "extism/v1" (Wasm).
sourceURL: OPTIONAL — URL-адреса, що вказує на початковий код вашого втулка.
config: ЗАЛЕЖИТЬ ВІД ТИПУ ВТУЛКА.
runtimeConfig: ЗАЛЕЖИТЬ ВІД СЕРЕДОВИЩА ВИКОНАННЯ.
  • Поле config призначене для конфігурації типу втулка і має структуру, яка відрізняється залежно від типу втулка, як визначено полем type.
  • Поле runtimeConfig призначене для конфігурації середовища виконання і має структуру, яка відрізняється залежно від середовища виконання, як визначено полем runtime.
  • 💡 Хоча поле sourceURL є необовʼязковим, авторам втулків наполегливо рекомендується вказувати на початковий код втулка, оскільки це допомагає користувачам втулка зрозуміти, що робить код, і зробити свій внесок у розвиток втулка, якщо він приймає відкриті внески.

Конфігурація типу втулка​

Поле config у файлі plugin.yaml має різні опції для кожного типу втулка. Тип втулка визначається полем type.

Конфігурація втулка CLI​

Якщо поле type має значення cli/v1, це тип втулка CLI, і дозволені такі конфігурації типу втулка:

usage: ОПЦІОНАЛЬНО — однорядковий текст використання, що показується в довідці
shortHelp: короткий опис, що показується у виводі 'helm help'
longHelp: довге повідомлення, що показується у виводі "helm help <ця-команда>"
ignoreFlags: ігнорує будь-які прапорці, передані з Helm
  • usage є необовʼязковим. Стандартно встановлено "helm PLUGIN_NAME [прапорці]", якщо не перевизначено за допомогою власного рядка використання. Рекомендовану синтаксичну конструкцію див. у [spf13/cobra.command.Command] Використовуйте коментар до поля: https://pkg.go.dev/github.com/spf13/cobra#Command
  • Перемикач ignoreFlags вказує Helm не передавати прапорці до втулка. Отже, якщо втулок викликається за допомогою helm myplugin --foo та ignoreFlags: true, то --foo мовчки відкидається.

Конфігурація втулка Getter​

Якщо поле type має значення getter/v1, це тип втулка Getter, і дозволені такі конфігурації типу втулка:

protocols: Список схем з URL-адреси чартів, які підтримує цей втулок.

Конфігурація втулка Postrenderer​

Якщо поле type має значення postrenderer/v1, це тип втулка Postrenderer, який не має жодних опцій конфігурації.

Конфігурація середовища виконання​

Поле runtimeConfig у файлі plugin.yaml має різні опції для кожного середовища виконання втулка. Середовище виконання втулка визначається полем runtime.

Конфігурація runtime Subprocess​

Якщо поле runtime має значення subprocess, це середовище виконання втулків Subprocess Runtime, і дозволені такі налаштування:

runtimeconfig:
    platformCommand: # Налаштування команди для запуску на основі платформи
        - os: відповідність ОС, може бути порожньою або пропущеною для відповідності будь-якій ОС
          arch: відповідність архітектури, може бути порожньою або пропущеною для відповідності будь-якій архітектурі
          command: команда втулка для виконання
          args: аргументи команди втулка
    platformHooks: # Налаштування хуків життєвого циклу втулка відповідно до платформи
        install: # Команди життєвого циклу встановлення
            - os: відповідність ОС, може бути порожнім або пропущеним для відповідності будь-якій ОС
              arch: відповідність архітектури, може бути порожнім або пропущеним для відповідності будь-якій архітектурі
              command: Команда встановлення втулка для виконання
              args: Аргументи команди встановлення втулка
        update: # Команди життєвого циклу оновлення
            - os: відповідність ОС, може бути порожньою або пропущеною для відповідності будь-якій ОС
              arch: відповідність архітектури, може бути порожньою або пропущеною для відповідності будь-якій архітектурі
              command: Команда оновлення втулка для виконання
              args: Аргументи команди оновлення втулка
        delete: # Команди життєвого циклу видалення
            - os: відповідність ОС, може бути порожньою або пропущеною для відповідності будь-якій ОС
              arch: відповідність архітектури, може бути порожньою або пропущеною для відповідності будь-якій архітектурі
              command: команда видалення втулка для виконання
              args: аргументи команди видалення втулка
    protocolCommands: # Obsolete/deprecated
        - protocols: [] # Протоколи — це список схем з URL-адреси чарта.
          platformCommand: [] # Та сама структура, що й "platformCommand" вище
  • ⚠️ protocolCommands позначено як obsolete/deprecated і буде видалено в майбутніх версіях системи втулків після apiVersion: v1. Це стосується лише типу втулка "getter/v1". Це залишок сумісності зі старим механізмом завантаження втулків, який було розширено для підтримки декількох протоколів у певному втулку. Команда, надана в PlatformCommand, повинна реалізовувати логіку, специфічну для протоколу, шляхом перевірки URL-адреси завантаження.

Конфігурація runtime Wasm​

Якщо поле runtime має значення extism/v1, це середовище виконання втулків Wasm Runtime, і дозволені такі налаштування:

runtimeconfig:
    memory: # Описує обмеження памʼяті, яку може бути виділено втулку
        maxPages: Максимальна кількість сторінок, яку може виділити втулок. Одна сторінка становить 64 Кб. Наприклад, 16 сторінок потребують 1 Мб. Стандартно — 4 сторінки (256 Кб).
        maxHttpResponseBytes: Максимальний розмір відповіді Extism HTTP у байтах. Стандартно — 4096 байт (4 Кбайт).
        maxVarBytes: Максимальний розмір усіх змінних Extism у байтах. Стандартно — 4096 байт (4 Кбайт).
    config: {} # Map у довільній формі, який можна передати втулку.
    allowedHosts: [] # Опціональний набір хостів, з якими цей втулок може спілкуватися. Стандартно жоден хост не дозволений.
    fileSystem:
        createTempDir: Чи створювати тимчасову теку в файловій системі. Може бути "true" або "false".
    timeout: Час очікування в мілісекундах для виконання втулка.
    hostFunctions: Імена HostFunction, відкриті в Helm, до яких втулок може отримати доступ. Див. https://extism.org/docs/concepts/host-functions/
    entryFuncName: Імʼя функції, яку потрібно викликати у втулку. Стандартно — "helm_plugin_main".
  • allowedHosts діє лише в тому випадку, якщо втулок надсилає HTTP-запити. Якщо не вказано, жодні хости не дозволені.