github.com/vtuson/helm@v2.8.2+incompatible/docs/plugins.md (about)

     1  # The Helm Plugins Guide
     2  
     3  Helm 2.1.0 introduced the concept of a client-side Helm _plugin_. A plugin is a
     4  tool that can be accessed through the `helm` CLI, but which is not part of the
     5  built-in Helm codebase.
     6  
     7  Existing plugins can be found on [related](related.md#helm-plugins) section or by searching [Github](https://github.com/search?q=topic%3Ahelm-plugin&type=Repositories).
     8  
     9  This guide explains how to use and create plugins.
    10  
    11  ## An Overview
    12  
    13  Helm plugins are add-on tools that integrate seamlessly with Helm. They provide
    14  a way to extend the core feature set of Helm, but without requiring every new
    15  feature to be written in Go and added to the core tool.
    16  
    17  Helm plugins have the following features:
    18  
    19  - They can be added and removed from a Helm installation without impacting the
    20    core Helm tool.
    21  - They can be written in any programming language.
    22  - They integrate with Helm, and will show up in `helm help` and other places.
    23  
    24  Helm plugins live in `$(helm home)/plugins`.
    25  
    26  The Helm plugin model is partially modeled on Git's plugin model. To that end,
    27  you may sometimes hear `helm` referred to as the _porcelain_ layer, with
    28  plugins being the _plumbing_. This is a shorthand way of suggesting that
    29  Helm provides the user experience and top level processing logic, while the
    30  plugins do the "detail work" of performing a desired action.
    31  
    32  ## Installing a Plugin
    33  
    34  Plugins are installed using the `$ helm plugin install <path|url>` command. You can pass in a path to a plugin on your local file system or a url of a remote VCS repo. The `helm plugin install` command clones or copies the plugin at the path/url given into `$ (helm home)/plugins`
    35  
    36  ```console
    37  $ helm plugin install https://github.com/technosophos/helm-template
    38  ```
    39  
    40  If you have a plugin tar distribution, simply untar the plugin into the
    41  `$(helm home)/plugins` directory.
    42  
    43  You can also install tarball plugins directly from url by issuing `helm plugin install http://domain/path/to/plugin.tar.gz`
    44  
    45  ## Building Plugins
    46  
    47  In many ways, a plugin is similar to a chart. Each plugin has a top-level
    48  directory, and then a `plugin.yaml` file.
    49  
    50  ```
    51  $(helm home)/plugins/
    52    |- keybase/
    53        |
    54        |- plugin.yaml
    55        |- keybase.sh
    56  
    57  ```
    58  
    59  In the example above, the `keybase` plugin is contained inside of a directory
    60  named `keybase`. It has two files: `plugin.yaml` (required) and an executable
    61  script, `keybase.sh` (optional).
    62  
    63  The core of a plugin is a simple YAML file named `plugin.yaml`.
    64  Here is a plugin YAML for a plugin that adds support for Keybase operations:
    65  
    66  ```
    67  name: "keybase"
    68  version: "0.1.0"
    69  usage: "Integrate Keybase.io tools with Helm"
    70  description: |-
    71    This plugin provides Keybase services to Helm.
    72  ignoreFlags: false
    73  useTunnel: false
    74  command: "$HELM_PLUGIN_DIR/keybase.sh"
    75  ```
    76  
    77  The `name` is the name of the plugin. When Helm executes it plugin, this is the
    78  name it will use (e.g. `helm NAME` will invoke this plugin).
    79  
    80  _`name` should match the directory name._ In our example above, that means the
    81  plugin with `name: keybase` should be contained in a directory named `keybase`.
    82  
    83  Restrictions on `name`:
    84  
    85  - `name` cannot duplicate one of the existing `helm` top-level commands.
    86  - `name` must be restricted to the characters ASCII a-z, A-Z, 0-9, `_` and `-`.
    87  
    88  `version` is the SemVer 2 version of the plugin.
    89  `usage` and `description` are both used to generate the help text of a command.
    90  
    91  The `ignoreFlags` switch tells Helm to _not_ pass flags to the plugin. So if a
    92  plugin is called with `helm myplugin --foo` and `ignoreFlags: true`, then `--foo`
    93  is silently discarded.
    94  
    95  The `useTunnel` switch indicates that the plugin needs a tunnel to Tiller. This
    96  should be set to `true` _anytime a plugin talks to Tiller_. It will cause Helm
    97  to open a tunnel, and then set `$TILLER_HOST` to the right local address for that
    98  tunnel. But don't worry: if Helm detects that a tunnel is not necessary because
    99  Tiller is running locally, it will not create the tunnel.
   100  
   101  Finally, and most importantly, `command` is the command that this plugin will
   102  execute when it is called. Environment variables are interpolated before the plugin
   103  is executed. The pattern above illustrates the preferred way to indicate where
   104  the plugin program lives.
   105  
   106  There are some strategies for working with plugin commands:
   107  
   108  - If a plugin includes an executable, the executable for a `command:` should be
   109    packaged in the plugin directory.
   110  - The `command:` line will have any environment variables expanded before
   111    execution. `$HELM_PLUGIN_DIR` will point to the plugin directory.
   112  - The command itself is not executed in a shell. So you can't oneline a shell script.
   113  - Helm injects lots of configuration into environment variables. Take a look at
   114    the environment to see what information is available.
   115  - Helm makes no assumptions about the language of the plugin. You can write it
   116    in whatever you prefer.
   117  - Commands are responsible for implementing specific help text for `-h` and `--help`.
   118    Helm will use `usage` and `description` for `helm help` and `helm help myplugin`,
   119    but will not handle `helm myplugin --help`.
   120  
   121  ## Downloader Plugins
   122  By default, Helm is able to fetch Charts using HTTP/S. As of Helm 2.4.0, plugins
   123  can have a special capability to download Charts from arbitrary sources.
   124  
   125  Plugins shall declare this special capability in the `plugin.yaml` file (top level):
   126  
   127  ```
   128  downloaders:
   129  - command: "bin/mydownloader"
   130    protocols:
   131    - "myprotocol"
   132    - "myprotocols"
   133  ```
   134  
   135  If such plugin is installed, Helm can interact with the repository using the specified
   136  protocol scheme by invoking the `command`. The special repository shall be added
   137  similarily to the regular ones: `helm repo add favorite myprotocol://example.com/`
   138  The rules for the special repos are the same to the regular ones: Helm must be able
   139  to download the `index.yaml` file in order to discover and cache the list of
   140  available Charts.
   141  
   142  The defined command will be invoked with the following scheme:
   143  `command certFile keyFile caFile full-URL`. The SSL credentials are coming from the
   144  repo definition, stored in `$HELM_HOME/repository/repositories.yaml`. Downloader
   145  plugin is expected to dump the raw content to stdout and report errors on stderr.
   146  
   147  ## Environment Variables
   148  
   149  When Helm executes a plugin, it passes the outer environment to the plugin, and
   150  also injects some additional environment variables.
   151  
   152  Variables like `KUBECONFIG` are set for the plugin if they are set in the
   153  outer environment.
   154  
   155  The following variables are guaranteed to be set:
   156  
   157  - `HELM_PLUGIN`: The path to the plugins directory
   158  - `HELM_PLUGIN_NAME`: The name of the plugin, as invoked by `helm`. So
   159    `helm myplug` will have the short name `myplug`.
   160  - `HELM_PLUGIN_DIR`: The directory that contains the plugin.
   161  - `HELM_BIN`: The path to the `helm` command (as executed by the user).
   162  - `HELM_HOME`: The path to the Helm home.
   163  - `HELM_PATH_*`: Paths to important Helm files and directories are stored in
   164    environment variables prefixed by `HELM_PATH`.
   165  - `TILLER_HOST`: The `domain:port` to Tiller. If a tunnel is created, this
   166    will point to the local endpoint for the tunnel. Otherwise, it will point
   167    to `$HELM_HOST`, `--host`, or the default host (according to Helm's rules of
   168    precedence).
   169  
   170  While `HELM_HOST` _may_ be set, there is no guarantee that it will point to the
   171  correct Tiller instance. This is done to allow plugin developer to access
   172  `HELM_HOST` in its raw state when the plugin itself needs to manually configure
   173  a connection.
   174  
   175  ## A Note on `useTunnel`
   176  
   177  If a plugin specifies `useTunnel: true`, Helm will do the following (in order):
   178  
   179  1. Parse global flags and the environment
   180  2. Create the tunnel
   181  3. Set `TILLER_HOST`
   182  4. Execute the plugin
   183  5. Close the tunnel
   184  
   185  The tunnel is removed as soon as the `command` returns. So, for example, a
   186  command cannot background a process and assume that that process will be able
   187  to use the tunnel.
   188  
   189  ## A Note on Flag Parsing
   190  
   191  When executing a plugin, Helm will parse global flags for its own use. Some of
   192  these flags are _not_ passed on to the plugin.
   193  
   194  - `--debug`: If this is specified, `$HELM_DEBUG` is set to `1`
   195  - `--home`: This is converted to `$HELM_HOME`
   196  - `--host`: This is converted to `$HELM_HOST`
   197  - `--kube-context`: This is simply dropped. If your plugin uses `useTunnel`, this
   198    is used to set up the tunnel for you.
   199  
   200  Plugins _should_ display help text and then exit for `-h` and `--help`. In all
   201  other cases, plugins may use flags as appropriate.