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