github.com/cloudposse/helm@v2.2.3+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  This guide explains how to use and create plugins.
     8  
     9  ## An Overview
    10  
    11  Helm plugins are add-on tools that integrate seamlessly with Helm. They provide
    12  a way to extend the core feature set of Helm, but without requiring every new
    13  feature to be written in Go and added to the core tool.
    14  
    15  Helm plugins have the following features:
    16  
    17  - They can be added and removed from a Helm installation without impacting the
    18    core Helm tool.
    19  - They can be written in any programming language.
    20  - They integrate with Helm, and will show up in `helm help` and other places.
    21  
    22  Helm plugins live in `$(helm home)/plugins`.
    23  
    24  The Helm plugin model is partially modeled on Git's plugin model. To that end,
    25  you may sometimes hear `helm` referred to as the _porcelain_ layer, with
    26  plugins being the _plumbing_. This is a shorthand way of suggesting that
    27  Helm provides the user experience and top level processing logic, while the
    28  plugins do the "detail work" of performing a desired action.
    29  
    30  ## Installing a Plugin
    31  
    32  A Helm plugin management system is in the works. But in the short term, plugins
    33  are installed by copying the plugin directory into `$(helm home)/plugins`.
    34  
    35  ```console
    36  $ cp -a myplugin/ $(helm home)/plugins/
    37  ```
    38  
    39  If you have a plugin tar distribution, simply untar the plugin into the
    40  `$(helm home)/plugins` directory.
    41  
    42  ## Building Plugins
    43  
    44  In many ways, a plugin is similar to a chart. Each plugin has a top-level
    45  directory, and then a `plugin.yaml` file.
    46  
    47  ```
    48  $(helm home)/plugins/
    49    |- keybase/
    50        |
    51        |- plugin.yaml
    52        |- keybase.sh
    53  
    54  ```
    55  
    56  In the example above, the `keybase` plugin is contained inside of a directory
    57  named `keybase`. It has two files: `plugin.yaml` (required) and an executable
    58  script, `keybase.sh` (optional).
    59  
    60  The core of a plugin is a simple YAML file named `plugin.yaml`.
    61  Here is a plugin YAML for a plugin that adds support for Keybase operations:
    62  
    63  ```
    64  name: "keybase"
    65  version: "0.1.0"
    66  usage: "Integreate Keybase.io tools with Helm"
    67  description: |-
    68    This plugin provides Keybase services to Helm.
    69  ignoreFlags: false
    70  useTunnel: false
    71  command: "$HELM_PLUGIN_DIR/keybase.sh"
    72  ```
    73  
    74  The `name` is the name of the plugin. When Helm executes it plugin, this is the
    75  name it will use (e.g. `helm NAME` will invoke this plugin).
    76  
    77  _`name` should match the directory name._ In our example above, that means the
    78  plugin with `name: keybase` should be contained in a directory named `keybase`.
    79  
    80  Restrictions on `name`:
    81  
    82  - `name` cannot duplicate one of the existing `helm` top-level commands.
    83  - `name` must be restricted to the characters ASCII a-z, A-Z, 0-9, `_` and `-`.
    84  
    85  `version` is the SemVer 2 version of the plugin.
    86  `usage` and `description` are both used to generate the help text of a command.
    87  
    88  The `ignoreFlags` switch tells Helm to _not_ pass flags to the plugin. So if a
    89  plugin is called with `helm myplugin --foo` and `ignoreFlags: true`, then `--foo`
    90  is silently discarded.
    91  
    92  The `useTunnel` switch indicates that the plugin needs a tunnel to Tiller. This
    93  should be set to `true` _anytime a plugin talks to Tiller_. It will cause Helm
    94  to open a tunnel, and then set `$TILLER_HOST` to the right local address for that
    95  tunnel. But don't worry: if Helm detects that a tunnel is not necessary because
    96  Tiller is running locally, it will not create the tunnel.
    97  
    98  Finally, and most importantly, `command` is the command that this plugin will
    99  execute when it is called. Environment variables are interpolated before the plugin
   100  is executed. The pattern above illustrates the preferred way to indicate where
   101  the plugin program lives.
   102  
   103  There are some strategies for working with plugin commands:
   104  
   105  - If a plugin includes an executable, the executable for a `command:` should be
   106    packaged in the plugin directory.
   107  - The `command:` line will have any environment variables expanded before
   108    execution. `$HELM_PLUGIN_DIR` will point to the plugin directory.
   109  - The command itself is not executed in a shell. So you can't oneline a shell script.
   110  - Helm injects lots of configuration into environment variables. Take a look at
   111    the environment to see what information is available.
   112  - Helm makes no assumptions about the language of the plugin. You can write it
   113    in whatever you prefer.
   114  - Commands are responsible for implementing specific help text for `-h` and `--help`.
   115    Helm will use `usage` and `description` for `helm help` and `helm help myplugin`,
   116    but will not handle `helm myplugin --help`.
   117  
   118  ## Environment Variables
   119  
   120  When Helm executes a plugin, it passes the outer environment to the plugin, and
   121  also injects some additional environment variables.
   122  
   123  Variables like `KUBECONFIG` are set for the plugin if they are set in the
   124  outer environment.
   125  
   126  The following variables are guaranteed to be set:
   127  
   128  - `HELM_PLUGIN`: The path to the plugins directory
   129  - `HELM_PLUGIN_NAME`: The name of the plugin, as invoked by `helm`. So
   130    `helm myplug` will have the short name `myplug`.
   131  - `HELM_PLUGIN_DIR`: The directory that contains the plugin.
   132  - `HELM_BIN`: The path to the `helm` command (as executed by the user).
   133  - `HELM_HOME`: The path to the Helm home.
   134  - `HELM_PATH_*`: Paths to important Helm files and directories are stored in
   135    environment variables prefixed by `HELM_PATH`.
   136  - `TILLER_HOST`: The `domain:port` to Tiller. If a tunnel is created, this
   137    will point to the local endpoint for the tunnel. Otherwise, it will point
   138    to `$HELM_HOST`, `--host`, or the default host (according to Helm's rules of
   139    precedence).
   140  
   141  While `HELM_HOST` _may_ be set, there is no guarantee that it will point to the
   142  correct Tiller instance. This is done to allow plugin developer to access
   143  `HELM_HOST` in its raw state when the plugin itself needs to manually configure
   144  a connection.
   145  
   146  ## A Note on `useTunnel`
   147  
   148  If a plugin specifies `useTunnel: true`, Helm will do the following (in order):
   149  
   150  1. Parse global flags and the environment
   151  2. Create the tunnel
   152  3. Set `TILLER_HOST`
   153  4. Execute the plugin
   154  5. Close the tunnel
   155  
   156  The tunnel is removed as soon as the `command` returns. So, for example, a
   157  command cannot background a process and assume that that process will be able
   158  to use the tunnel.
   159  
   160  ## A Note on Flag Parsing
   161  
   162  When executing a plugin, Helm will parse global flags for its own use. Some of
   163  these flags are _not_ passed on to the plugin.
   164  
   165  - `--debug`: If this is specified, `$HELM_DEBUG` is set to `1`
   166  - `--home`: This is converted to `$HELM_HOME`
   167  - `--host`: This is converted to `$HELM_HOST`
   168  - `--kube-context`: This is simply dropped. If your plugin uses `useTunnel`, this
   169    is used to set up the tunnel for you.
   170  
   171  Plugins _should_ display help text and then exit for `-h` and `--help`. In all
   172  other cases, plugins may use flags as appropriate.
   173