github.com/umeshredd/helm@v3.0.0-alpha.1+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 `$(helm home)/plugins` directory. You can also install tarball plugins directly from url by issuing `helm plugin install http://domain/path/to/plugin.tar.gz`
    41  
    42  Alternatively, a set of plugins can be installed during the `helm init` process by using the `--plugins <file.yaml>` flag, where `file.yaml` looks like this:
    43  
    44  ```
    45  plugins:
    46  - name: helm-template
    47    url: https://github.com/technosophos/helm-template
    48  - name: helm-diff
    49    url: https://github.com/databus23/helm-diff
    50    version: 2.11.0+3
    51  ```
    52  
    53  The `name` field only exists to allow you to easily identify plugins, and does not serve a functional purpose. If a plugin specified in the file is already installed, it maintains its current version.
    54  
    55  ## Building Plugins
    56  
    57  In many ways, a plugin is similar to a chart. Each plugin has a top-level
    58  directory, and then a `plugin.yaml` file.
    59  
    60  ```
    61  $(helm home)/plugins/
    62    |- keybase/
    63        |
    64        |- plugin.yaml
    65        |- keybase.sh
    66  
    67  ```
    68  
    69  In the example above, the `keybase` plugin is contained inside of a directory
    70  named `keybase`. It has two files: `plugin.yaml` (required) and an executable
    71  script, `keybase.sh` (optional).
    72  
    73  The core of a plugin is a simple YAML file named `plugin.yaml`.
    74  Here is a plugin YAML for a plugin that adds support for Keybase operations:
    75  
    76  ```
    77  name: "last"
    78  version: "0.1.0"
    79  usage: "get the last release name"
    80  description: "get the last release name""
    81  ignoreFlags: false
    82  command: "$HELM_BIN --host $TILLER_HOST list --short --max 1 --date -r"
    83  platformCommand:
    84    - os: linux
    85      arch: i386
    86      command: "$HELM_BIN list --short --max 1 --date -r"
    87    - os: linux
    88      arch: amd64
    89      command: "$HELM_BIN list --short --max 1 --date -r"
    90    - os: windows
    91      arch: amd64
    92      command: "$HELM_BIN list --short --max 1 --date -r"
    93  ```
    94  
    95  The `name` is the name of the plugin. When Helm executes it plugin, this is the
    96  name it will use (e.g. `helm NAME` will invoke this plugin).
    97  
    98  _`name` should match the directory name._ In our example above, that means the
    99  plugin with `name: keybase` should be contained in a directory named `keybase`.
   100  
   101  Restrictions on `name`:
   102  
   103  - `name` cannot duplicate one of the existing `helm` top-level commands.
   104  - `name` must be restricted to the characters ASCII a-z, A-Z, 0-9, `_` and `-`.
   105  
   106  `version` is the SemVer 2 version of the plugin.
   107  `usage` and `description` are both used to generate the help text of a command.
   108  
   109  The `ignoreFlags` switch tells Helm to _not_ pass flags to the plugin. So if a
   110  plugin is called with `helm myplugin --foo` and `ignoreFlags: true`, then `--foo`
   111  is silently discarded.
   112  
   113  Finally, and most importantly, `platformCommand` or `command` is the command
   114  that this plugin will execute when it is called. The `platformCommand` section
   115  defines the OS/Architecture specific variations of a command. The following
   116  rules will apply in deciding which command to use:
   117  
   118  - If `platformCommand` is present, it will be searched first.
   119  - If both `os` and `arch` match the current platform, search will stop and the
   120  command will be used.
   121  - If `os` matches and there is no more specific `arch` match, the command
   122  will be used.
   123  - If no `platformCommand` match is found, the default `command` will be used.
   124  - If no matches are found in `platformCommand` and no `command` is present,
   125  Helm will exit with an error.
   126  
   127  Environment variables are interpolated before the plugin is executed. The
   128  pattern above illustrates the preferred way to indicate where the plugin
   129  program lives.
   130  
   131  There are some strategies for working with plugin commands:
   132  
   133  - If a plugin includes an executable, the executable for a
   134  `platformCommand:` or a `command:` should be packaged in the plugin directory.
   135  - The `platformCommand:` or `command:` line will have any environment
   136  variables expanded before execution. `$HELM_PLUGIN_DIR` will point to the
   137  plugin directory.
   138  - The command itself is not executed in a shell. So you can't oneline a shell script.
   139  - Helm injects lots of configuration into environment variables. Take a look at
   140    the environment to see what information is available.
   141  - Helm makes no assumptions about the language of the plugin. You can write it
   142    in whatever you prefer.
   143  - Commands are responsible for implementing specific help text for `-h` and `--help`.
   144    Helm will use `usage` and `description` for `helm help` and `helm help myplugin`,
   145    but will not handle `helm myplugin --help`.
   146  
   147  ## Downloader Plugins
   148  By default, Helm is able to pull Charts using HTTP/S. As of Helm 2.4.0, plugins
   149  can have a special capability to download Charts from arbitrary sources.
   150  
   151  Plugins shall declare this special capability in the `plugin.yaml` file (top level):
   152  
   153  ```
   154  downloaders:
   155  - command: "bin/mydownloader"
   156    protocols:
   157    - "myprotocol"
   158    - "myprotocols"
   159  ```
   160  
   161  If such plugin is installed, Helm can interact with the repository using the specified
   162  protocol scheme by invoking the `command`. The special repository shall be added
   163  similarly to the regular ones: `helm repo add favorite myprotocol://example.com/`
   164  The rules for the special repos are the same to the regular ones: Helm must be able
   165  to download the `index.yaml` file in order to discover and cache the list of
   166  available Charts.
   167  
   168  The defined command will be invoked with the following scheme:
   169  `command certFile keyFile caFile full-URL`. The SSL credentials are coming from the
   170  repo definition, stored in `$HELM_HOME/repository/repositories.yaml`. Downloader
   171  plugin is expected to dump the raw content to stdout and report errors on stderr.
   172  
   173  ## Environment Variables
   174  
   175  When Helm executes a plugin, it passes the outer environment to the plugin, and
   176  also injects some additional environment variables.
   177  
   178  Variables like `KUBECONFIG` are set for the plugin if they are set in the
   179  outer environment.
   180  
   181  The following variables are guaranteed to be set:
   182  
   183  - `HELM_PLUGIN`: The path to the plugins directory
   184  - `HELM_PLUGIN_NAME`: The name of the plugin, as invoked by `helm`. So
   185    `helm myplug` will have the short name `myplug`.
   186  - `HELM_PLUGIN_DIR`: The directory that contains the plugin.
   187  - `HELM_BIN`: The path to the `helm` command (as executed by the user).
   188  - `HELM_HOME`: The path to the Helm home.
   189  - `HELM_PATH_*`: Paths to important Helm files and directories are stored in
   190    environment variables prefixed by `HELM_PATH`.
   191  
   192  ## A Note on Flag Parsing
   193  
   194  When executing a plugin, Helm will parse global flags for its own use. Some of
   195  these flags are _not_ passed on to the plugin.
   196  
   197  - `--debug`: If this is specified, `$HELM_DEBUG` is set to `1`
   198  - `--home`: This is converted to `$HELM_HOME`
   199  - `--kube-context`: This is simply dropped.
   200  
   201  Plugins _should_ display help text and then exit for `-h` and `--help`. In all
   202  other cases, plugins may use flags as appropriate.