Guida ai plugin di Helm

Un plugin di Helm è uno strumento a cui si può accedere tramite la CLI helm, ma che non fa parte della base di codice di Helm.

Questa guida spiega come usare e creare i plugin.

Una panoramica

I plugin di Helm sono strumenti aggiuntivi che si integrano perfettamente con Helm. Forniscono un modo per estendere il set di funzionalità principali di Helm, senza però richiedere che ogni nuova funzionalità sia scritta in in Go e di aggiungerle al core dello strumento.

I plugin di Helm hanno le seguenti caratteristiche:

• Possono essere aggiunti e rimossi da un'installazione di Helm senza impattare lo strumento principale.
• Possono essere scritti in qualsiasi linguaggio di programmazione.
• Si integrano con Helm e vengono visualizzati in helm help e in altri luoghi.

I plugin di Helm si trovano in $HELM_PLUGINS. È possibile trovarne il valore corrente, compreso il valore predefinito quando non è impostato nell'ambiente, usando il comando helm env.

Il modello a plugin di Helm è parzialmente basato sul modello a plugin di Git. A tal fine, a volte si sente parlare di helm come il porcelain layer, mentre i plugin sono il plumbing. Questo è un modo abbreviato per suggerire che Helm fornisce l'esperienza dell'utente e la logica di elaborazione di primo livello, mentre i plugin svolgono il "lavoro di dettaglio" per eseguire un'azione desiderata.

Installazione di un plugin

I plugin vengono installati con il comando $ helm plugin install <path|url>. È possibile inserire il percorso di un plugin sul file system locale o l'url di un repo VCS remoto. Il comando helm plugin install clona o copia il plugin nel percorso/url indicato in $HELM_PLUGINS

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

Se si dispone di una distribuzione tar del plugin, è sufficiente decomprimere il plugin nella cartella $HELM_PLUGINS. È anche possibile installare i plugin in formato tar direttamente da url, lanciando helm plugin install https://domain/path/to/plugin.tar.gz

La struttura del file Plugin

Per molti versi, un plugin è simile a un chart. Ogni plugin ha una cartella di primo livello e un file plugin.yaml. Possono essere presenti altri file, ma è necessario solo il file plugin.yaml.

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

Il file plugin.yaml

Il file plugin.yaml è necessario per un plugin. Contiene i seguenti campi:

name: il nome del plugin (OBBLIGATORIO)
version: Una versione in formato SemVer 2 (OBBLIGATORIA)
usage: Testo d'uso a riga singola mostrato nella guida
descrizione: Lunga descrizione mostrata in luoghi come l'help di Helm
ignoreFlags: Ignora i flag passati in Helm
platformCommand: # Configura il comando da eseguire in base alla piattaforma
  - os: OS match, può essere vuoto o omesso per corrispondere a tutti i sistemi operativi.
    arch: Architecture match, può essere vuoto o omesso per corrispondere a tutte le architetture
    command: Comando del plugin da eseguire
    args: Argomenti del comando del plugin
command: (DEPRECATO) Comando del plugin, utilizzare invece platformCommand
platformHooks: # Configura gli hook del ciclo di vita del plugin in base alla piattaforma
  install: # Comando di install
    - os: OS match, può essere vuoto o omesso per corrispondere a tutti i sistemi operativi.
      arch: Architecture match, può essere vuoto o omesso per corrispondere a tutte le architetture
      comando: Comando di installazione del plugin da eseguire
      args: Argomenti del comando di installazione del plugin
  update: # Comando di update
    - os: OS match, può essere vuoto o omesso per corrispondere a tutti i sistemi operativi.
      arch: Architecture match, può essere vuoto o omesso per corrispondere a tutte le architetture
      comando: Comando di aggiornamento del plugin da eseguire
      args: Argomenti del comando di aggiornamento del plugin
  delete: # Comando di delete plugin
    - os: OS match, può essere vuoto o omesso per corrispondere a tutti i sistemi operativi.
      arch: Architecture match, può essere vuoto o omesso per corrispondere a tutte le architetture
      comando: Comando di cancellazione del plugin da eseguire
      args: Argomenti del comando di cancellazione del plugin
hooks: # (Deprecato) Hook del plugin, usare invece platformHooks
  install: Comando per installare il plugin
  update: Comando per aggiornare il plugin
  delete: Comando per cancellare il plugin
downloader: # Configura la capacità dei downloader
  - command: Comando da invocare
    protocolli:
      - Schema di protocollo supportato

Il campo name

Il campo name è il nome del plugin. Quando Helm esegue questo plugin, questo è il nome che utilizzerà (ad esempio, helm NAME invocherà questo plugin).

name deve corrispondere al nome della cartella. Nell'esempio precedente, ciò significa che il plugin con name: last deve essere contenuto in una cartella chiamata last.

Restrizioni su name:

• name non può duplicare uno dei comandi di primo livello esistenti helm.
• name deve essere limitato ai caratteri ASCII a-z, A-Z, 0-9, _ e -.

Il campo version

La version è la versione in formato SemVer 2 del plugin. I campi usage e description sono entrambi utilizzati per generare il testo di aiuto di un comando.

Il campo ignoreFlags

L'opzione ignoreFlags indica a Helm di non passare i flag al plugin. Quindi, se un plugin è chiamato con helm myplugin --foo e ignoreFlags: true, allora --foo viene silenziosamente scartato.

Il campo platformCommand

Il campo platformCommand configura il comando che il plugin eseguirà quando viene chiamato. Non è possibile impostare sia platformCommand che command, in quanto ciò provocherebbe un errore. Per decidere quale comando utilizzare si applicano le seguenti regole:

• Se platformCommand è presente, verrà utilizzato.
  • Se sia os che arch corrispondono alla piattaforma corrente, la ricerca si interrompe e viene utilizzato il comando
  • Se os corrisponde e arch è vuoto, verrà utilizzato il comando.
  • Se os e arch sono entrambi vuoti, verrà utilizzato il comando.
  • Se non c'è corrispondenza, Helm uscirà con un errore.
• Se platformCommand non è presente e il deprecato command è presente verrà utilizzato.
  • Se il comando è vuoto, Helm uscirà con un errore.

Il campo platformHooks

Il campo platformHooks configura i comandi che il plugin eseguirà per gli eventi del ciclo di vita. Non è possibile impostare sia platformHooks che hooks, in quanto si otterrebbe un errore. Per decidere quale comando di hook utilizzare, si applicano le seguenti regole:

• Se platformHooks è presente, verrà utilizzato e i comandi per l'evento del ciclo di vita saranno processati.
  • Se sia os che arch corrispondono alla piattaforma corrente, la ricerca si interrompe e il comando sarà utilizzato
  • Se os corrisponde e arch è vuoto, il comando verrà utilizzato.
  • Se os e arch sono entrambi vuoti, verrà utilizzato il comando.
  • Se non c'è corrispondenza, Helm salterà l'evento.
• Se platformHooks non è presente e il deprecato hooks è presente il comando per l'evento del ciclo di vita sarà usato.
  • Se il comando è vuoto, Helm salterà l'evento.

Building a Plugin

Ecco un plugin YAML per un semplice plugin che aiuta a recuperare il nome dell'ultima release:

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

I plugin possono richiedere script ed eseguibili aggiuntivi. Gli script possono essere inclusi nella cartella dei plugin e gli eseguibili possono essere scaricati tramite un hook. Il seguente è un esempio di plugin:

$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

Le variabili d'ambiente vengono interpolate prima dell'esecuzione del plugin. Il modello sopra illustra il modo preferito per indicare dove risiede il programma del plugin.

Comandi dei plugin

Esistono alcune strategie per lavorare con i comandi dei plugin:

• Se un plugin include un eseguibile, l'eseguibile per un platformCommand: dovrebbe essere impacchettato nella cartella del plugin o installato tramite un hook.
• La linea platformCommand: o command: avrà le variabili d'ambiente espanse prima dell'esecuzione. $HELM_PLUGIN_DIR punterà alla cartella dei plugin.
• Il comando stesso non viene eseguito in una shell. Quindi non è possibile eseguire uno script.
• Helm inietta molte configurazioni nelle variabili d'ambiente. Si può dare un'occhiata all'ambiente per vedere quali informazioni sono disponibili.
• Helm non fa alcuna ipotesi sulla linguaggio del plugin. È possibile scriverlo in qualsiasi linguaggio si preferisca.
• I comandi sono responsabili dell'implementazione di testi di aiuto specifici per -h e --help. Helm userà usage e description per helm help e helm help myplugin, ma non gestirà helm myplugin --help.

Testare un plugin locale

Per prima cosa è necessario trovare il percorso HELM_PLUGINS e per farlo eseguire il seguente comando:

helm env

Cambiare la propria directory corrente nella directory in cui è impostato HELM_PLUGINS.

Ora si può aggiungere un collegamento simbolico all'output di compilazione del plugin, in questo esempio lo abbiamo fatto per mapkubeapis.

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

Downloader Plugins

Per impostazione predefinita, Helm è in grado di estrarre i chart tramite HTTP/S. A partire da Helm 2.4.0, i plugin possono avere una capacità speciale di scaricare chart da fonti arbitrarie.

I plugin devono dichiarare questa capacità speciale nel file plugin.yaml (livello superiore):

downloaders:
- command: "bin/mydownloader"
  protocols:
  - "myprotocol"
  - "myprotocols"

Se tale plugin è installato, Helm può interagire con il repository usando lo schema di protocollo specificato invocando il comand. Il repository speciale deve essere aggiunto in modo simile a quelli normali: helm repo add favoritemyprotocol://example.com/ Le regole per i repository speciali sono le stesse di quelli regolari: Helm deve essere in grado di scaricare il file index.yaml per poter scoprire e memorizzare nella cache l'elenco dei chart disponibili.

Il comando definito sarà invocato con il seguente schema: command certFile keyFile caFile full-URL. Le credenziali SSL provengono dalla definizione del repo memorizzate in $HELM_REPOSITORY_CONFIG. (cioè, $HELM_CONFIG_HOME/repositories.yaml). Un downloader plugin dovrebbe scaricare il contenuto grezzo su stdout e segnalare gli errori su stderr.

Il comando downloader supporta anche subcommands o argomenti, consentendo di specificare ad esempio il subcommand bin/mydownloader -d nel file plugin.yaml. Questo è utile se si vuole usare lo stesso eseguibile per il comando principale del plugin e per il comando downloader, ma con un subcommand diverso per ciascuno.

Variabili d'ambiente

Quando Helm esegue un plugin, passa l'environment esterno al plugin e inietta alcune variabili d'ambiente aggiuntive.

Variabili come KUBECONFIG sono impostate per il plugin se sono impostate nell'ambiente esterno.

Viene garantito che le seguenti variabili siano impostate:

• HELM_PLUGINS:Il percorso della cartella dei plugin.
• HELM_PLUGIN_NAME: Il nome del plugin, come invocato da helm. Quindi helm myplug avrà il nome breve myplug.
• HELM_PLUGIN_DIR: La directory che contiene il plugin.
• HELM_BIN: Il percorso del comando helm (come eseguito dall'utente).
• HELM_DEBUG: Indica se il flag di debug è stato impostato da helm.
• HELM_REGISTRY_CONFIG: Il percorso della configurazione del registry (se se si usa). Si noti che l'uso di Helm con i registry è una funzione sperimentale.
• HELM_REPOSITORY_CACHE: Il percorso dei file della cache del repository.
• HELM_REPOSITORY_CONFIG: Il percorso del file di configurazione del repository.
• HELM_NAMESPACE: Il namespace dato al comando helm (generalmente usando il flag il flag -n).
• HELM_KUBECONTEXT: Il nome del contesto di configurazione di Kubernetes dato al comando helm.

Inoltre, se è stato specificato esplicitamente un file di configurazione di Kubernetes, esso verrà sarà impostato come variabile KUBECONFIG.

Una nota sul flag parsing

Quando si esegue un plugin, Helm analizza i flag globali per il proprio uso. Nessuno di questi flag viene passato al plugin.

• --debug: Se viene specificato, $HELM_DEBUG viene impostato a 1.
• --registry-config: Viene convertito in $HELM_REGISTRY_CONFIG.
• --repository-cache: Viene convertito in $HELM_REPOSITORY_CACHE.
• --repository-config: Viene convertito in $HELM_REPOSITORY_CONFIG.
• --namespace e -n: Viene convertito in $HELM_NAMESPACE.
• --kube-context: Viene convertito in $HELM_KUBECONTEXT.
• --kubeconfig: Viene convertito in $KUBECONFIG.

I plugin dovrebbero mostrare un testo di aiuto e poi uscire per -h e --help. In tutti gli altri casi, i plugin possono usare i flag come meglio credono.

Supporto per l'autocompletamento della shell

A partire da Helm 3.2, un plugin può opzionalmente fornire il supporto per il completamento automatico della shell come parte del meccanismo di autocompletamento di Helm.

Autocompletamento statico

Se un plugin fornisce i propri flag e/o sotto-comandi, può informare Helm di questi, disponendo di un file completion.yaml che si trova nella cartella principale del plugin. Il file completion.yaml ha la forma:

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>

Note:

1. Tutte le sezioni sono facoltative ma devono essere fornite se applicabili.

2. I flag non devono includere il prefisso - o --.

3. Possono e devono essere specificati flag sia brevi che lunghi. Un flag breve non deve necessariamente essere associato alla corrispondente forma lunga, ma entrambe le forme devono essere elencate.

4. I flag non devono essere ordinati in alcun modo, ma devono essere elencati nel punto corretto della gerarchia dei sottocomandi del file.

5. I flag globali esistenti di Helm sono già gestiti dal meccanismo di autocompletamento di Helm, quindi i plugin non devono specificare i seguenti flag --debug, --namespace o -n, --kube-context e --kubeconfig, o qualsiasi altro flag globale.

6. L'elenco validArgs fornisce un elenco statico di possibili completamenti del primo parametro di un sottocomando. Non è sempre possibile fornire tale elenco in anticipo (vedere la sezione Completamento dinamico), nel qual caso la sezione validArgs può essere omessa.

Il file completion.yaml è del tutto opzionale. Se non viene fornito, Helm non fornirà semplicemente il completamento automatico della shell per il plugin (a meno che Completamento dinamico sia supportato dal plugin). Inoltre, aggiungendo un file completion.yaml è compatibile con le versioni precedenti e non avrà alcun impatto sul comportamento del plugin quando si utilizzano versioni precedenti di helm.

A titolo di esempio, per il [fullstatus ](https://github.com/marckhouzam/helm-fullstatus) che non ha sottocomandi, ma accetta gli stessi flag del comando helm status, il file file completion.yaml` è:

name: fullstatus
flags:
- o
- output
- revision

Un esempio più complesso per il 2to3, ha un file completion.yaml del tipo:

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

Completamento dinamico

Sempre a partire da Helm 3.2, i plugin possono fornire il proprio completamento automatico della shell. L'autocompletamento dinamico della shell è il completamento dei valori dei parametri o dei flag che non possono essere definiti in anticipo. Ad esempio, il completamento dei nomi delle release di helm attualmente disponibili sul cluster.

Affinché il plugin supporti l'autocompletamento dinamico, deve fornire un file eseguibile chiamato plugin.complete nella sua directory principale. Quando lo script di completamento di Helm richiede un completamento dinamico per il plugin, eseguirà il file plugin.complete., passandogli la riga di comando che deve essere completata. L'eseguibile plugin.complete dovrà avere la logica per determinare quali siano le scelte corrette per il completamento e inviarle allo standard per essere utilizzato dallo script di completamento di Helm.

Il file plugin.complete è del tutto opzionale. Se non viene fornito, Helm non fornirà il completamento automatico dinamico per il plugin. Inoltre, l'aggiunta di un file plugin.complete è compatibile con le versioni precedenti e non avrà alcun impatto sul comportamento del plugin quando si utilizza con versioni precedenti di Helm.

L'output dello script plugin.complete dovrebbe essere un elenco separato da new-line char come ad esempio:

rel1
rel2
rel3

Quando viene richiamato plugin.complete, l'ambiente del plugin viene impostato come quando viene richiamato lo script principale del plugin. Pertanto, le variabili $HELM_NAMESPACE, $HELM_KUBECONTEXT e tutte le altre variabili del plugin saranno già impostate e i corrispondenti flag globali saranno rimossi.

Il file plugin.complete può essere in qualsiasi forma eseguibile; può essere uno script di shell, un programma Go o qualsiasi altro tipo di programma che Helm può eseguire. Il file plugin.complete deve avere i permessi di esecuzione per l'utente. Il file plugin.complete deve terminare con codice di successo (valore 0).

In alcuni casi, il completamento dinamico richiederà di ottenere informazioni dal cluster Kubernetes.Ad esempio, il plugin helm fullstatus richiede come input il nome di una release. Nel plugin fullstatus, per il suo script plugin.complete fornisce il completamento per i nomi dei rilasci correnti, può semplicemente eseguire helm list -q e produrre il risultato.

Se si vuole usare lo stesso eseguibile per l'esecuzione del plugin e per il suo completamento, lo script plugin.complete deve richiamare l'eseguibile del plugin principale con qualche parametro o flag speciale; quando l'eseguibile principale del plugin rileva il parametro o il flag speciale, saprà di dover eseguire il completamento. Nel nostro esempio, plugin.complete potrebbe essere implementato in questo modo:

#!/usr/bin/env sh

# "$@" is the entire command-line that requires completion.
# It is important to double-quote the "$@" variable to preserve a possibly empty last parameter.
$HELM_PLUGIN_DIR/status.sh --complete "$@"

Il vero script del plugin fullstatus (status.sh) deve quindi cercare il flag --complete e, se lo trova, stampare il completamento corretto.

Suggerimenti e trucchi

1. La shell filtra automaticamente le scelte di completamento che non corrispondono all'input dell'utente. Un plugin può quindi restituire tutti i completamenti rilevanti senza rimuovere quelli che non corrispondono all'input dell'utente. Ad esempio, se la riga di comando è helm fullstatus ngin<TAB>, lo script plugin.complete può stampare tutti i nomi dei rilasci (dello spazio dei nomi default), non solo quelli che iniziano con ngin. ; la shell manterrà solo quelli che iniziano con ngin.
2. Per semplificare il supporto al completamento dinamico, specialmente se si ha un plugin complesso, si può fare in modo che lo script plugin.complete chiami lo script principale del plugin e richieda le scelte di completamento. Si veda la sezione Completamento dinamico per un esempio.
3. Per eseguire il debug del completamento dinamico e del file plugin.complete, si può eseguire il comando seguente per vedere i risultati del completamento:
   • helm __complete <nomeplugin> <argomenti da completare>. Per esempio:
   • helm __complete fullstatus --output js<ENTER>,
   • helm __complete fullstatus -o json ""<ENTER>.