github.com/amundsenjunior/helm@v2.8.0-rc.1.0.20180119233529-2b92431476e1+incompatible/docs/using_helm.md (about) 1 # Using Helm 2 3 This guide explains the basics of using Helm (and Tiller) to manage 4 packages on your Kubernetes cluster. It assumes that you have already 5 [installed](install.md) the Helm client and the Tiller server (typically by `helm 6 init`). 7 8 If you are simply interested in running a few quick commands, you may 9 wish to begin with the [Quickstart Guide](quickstart.md). This chapter 10 covers the particulars of Helm commands, and explains how to use Helm. 11 12 ## Three Big Concepts 13 14 A *Chart* is a Helm package. It contains all of the resource definitions 15 necessary to run an application, tool, or service inside of a Kubernetes 16 cluster. Think of it like the Kubernetes equivalent of a Homebrew formula, 17 an Apt dpkg, or a Yum RPM file. 18 19 A *Repository* is the place where charts can be collected and shared. 20 It's like Perl's [CPAN archive](http://www.cpan.org) or the 21 [Fedora Package Database](https://admin.fedoraproject.org/pkgdb/), but for 22 Kubernetes packages. 23 24 A *Release* is an instance of a chart running in a Kubernetes cluster. 25 One chart can often be installed many times into the same cluster. And 26 each time it is installed, a new _release_ is created. Consider a MySQL 27 chart. If you want two databases running in your cluster, you can 28 install that chart twice. Each one will have its own _release_, which 29 will in turn have its own _release name_. 30 31 With these concepts in mind, we can now explain Helm like this: 32 33 Helm installs _charts_ into Kubernetes, creating a new _release_ for 34 each installation. And to find new charts, you can search Helm chart 35 _repositories_. 36 37 ## 'helm search': Finding Charts 38 39 When you first install Helm, it is preconfigured to talk to the official 40 Kubernetes charts repository. This repository contains a number of 41 carefully curated and maintained charts. This chart repository is named 42 `stable` by default. 43 44 You can see which charts are available by running `helm search`: 45 46 ``` 47 $ helm search 48 NAME VERSION DESCRIPTION 49 stable/drupal 0.3.2 One of the most versatile open source content m... 50 stable/jenkins 0.1.0 A Jenkins Helm chart for Kubernetes. 51 stable/mariadb 0.5.1 Chart for MariaDB 52 stable/mysql 0.1.0 Chart for MySQL 53 ... 54 ``` 55 56 With no filter, `helm search` shows you all of the available charts. You 57 can narrow down your results by searching with a filter: 58 59 ``` 60 $ helm search mysql 61 NAME VERSION DESCRIPTION 62 stable/mysql 0.1.0 Chart for MySQL 63 stable/mariadb 0.5.1 Chart for MariaDB 64 ``` 65 66 Now you will only see the results that match your filter. 67 68 Why is 69 `mariadb` in the list? Because its package description relates it to 70 MySQL. We can use `helm inspect chart` to see this: 71 72 ``` 73 $ helm inspect stable/mariadb 74 Fetched stable/mariadb to mariadb-0.5.1.tgz 75 description: Chart for MariaDB 76 engine: gotpl 77 home: https://mariadb.org 78 keywords: 79 - mariadb 80 - mysql 81 - database 82 - sql 83 ... 84 ``` 85 86 Search is a good way to find available packages. Once you have found a 87 package you want to install, you can use `helm install` to install it. 88 89 ## 'helm install': Installing a Package 90 91 To install a new package, use the `helm install` command. At its 92 simplest, it takes only one argument: The name of the chart. 93 94 ``` 95 $ helm install stable/mariadb 96 Fetched stable/mariadb-0.3.0 to /Users/mattbutcher/Code/Go/src/k8s.io/helm/mariadb-0.3.0.tgz 97 happy-panda 98 Last Deployed: Wed Sep 28 12:32:28 2016 99 Namespace: default 100 Status: DEPLOYED 101 102 Resources: 103 ==> extensions/Deployment 104 NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE 105 happy-panda-mariadb 1 0 0 0 1s 106 107 ==> v1/Secret 108 NAME TYPE DATA AGE 109 happy-panda-mariadb Opaque 2 1s 110 111 ==> v1/Service 112 NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE 113 happy-panda-mariadb 10.0.0.70 <none> 3306/TCP 1s 114 115 116 Notes: 117 MariaDB can be accessed via port 3306 on the following DNS name from within your cluster: 118 happy-panda-mariadb.default.svc.cluster.local 119 120 To connect to your database run the following command: 121 122 kubectl run happy-panda-mariadb-client --rm --tty -i --image bitnami/mariadb --command -- mysql -h happy-panda-mariadb 123 ``` 124 125 Now the `mariadb` chart is installed. Note that installing a chart 126 creates a new _release_ object. The release above is named 127 `happy-panda`. (If you want to use your own release name, simply use the 128 `--name` flag on `helm install`.) 129 130 During installation, the `helm` client will print useful information 131 about which resources were created, what the state of the release is, 132 and also whether there are additional configuration steps you can or 133 should take. 134 135 Helm does not wait until all of the resources are running before it 136 exits. Many charts require Docker images that are over 600M in size, and 137 may take a long time to install into the cluster. 138 139 To keep track of a release's state, or to re-read configuration 140 information, you can use `helm status`: 141 142 ``` 143 $ helm status happy-panda 144 Last Deployed: Wed Sep 28 12:32:28 2016 145 Namespace: default 146 Status: DEPLOYED 147 148 Resources: 149 ==> v1/Service 150 NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE 151 happy-panda-mariadb 10.0.0.70 <none> 3306/TCP 4m 152 153 ==> extensions/Deployment 154 NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE 155 happy-panda-mariadb 1 1 1 1 4m 156 157 ==> v1/Secret 158 NAME TYPE DATA AGE 159 happy-panda-mariadb Opaque 2 4m 160 161 162 Notes: 163 MariaDB can be accessed via port 3306 on the following DNS name from within your cluster: 164 happy-panda-mariadb.default.svc.cluster.local 165 166 To connect to your database run the following command: 167 168 kubectl run happy-panda-mariadb-client --rm --tty -i --image bitnami/mariadb --command -- mysql -h happy-panda-mariadb 169 ``` 170 171 The above shows the current state of your release. 172 173 ### Customizing the Chart Before Installing 174 175 Installing the way we have here will only use the default configuration 176 options for this chart. Many times, you will want to customize the chart 177 to use your preferred configuration. 178 179 To see what options are configurable on a chart, use `helm inspect 180 values`: 181 182 ```console 183 helm inspect values stable/mariadb 184 Fetched stable/mariadb-0.3.0.tgz to /Users/mattbutcher/Code/Go/src/k8s.io/helm/mariadb-0.3.0.tgz 185 ## Bitnami MariaDB image version 186 ## ref: https://hub.docker.com/r/bitnami/mariadb/tags/ 187 ## 188 ## Default: none 189 imageTag: 10.1.14-r3 190 191 ## Specify a imagePullPolicy 192 ## Default to 'Always' if imageTag is 'latest', else set to 'IfNotPresent' 193 ## ref: http://kubernetes.io/docs/user-guide/images/#pre-pulling-images 194 ## 195 # imagePullPolicy: 196 197 ## Specify password for root user 198 ## ref: https://github.com/bitnami/bitnami-docker-mariadb/blob/master/README.md#setting-the-root-password-on-first-run 199 ## 200 # mariadbRootPassword: 201 202 ## Create a database user 203 ## ref: https://github.com/bitnami/bitnami-docker-mariadb/blob/master/README.md#creating-a-database-user-on-first-run 204 ## 205 # mariadbUser: 206 # mariadbPassword: 207 208 ## Create a database 209 ## ref: https://github.com/bitnami/bitnami-docker-mariadb/blob/master/README.md#creating-a-database-on-first-run 210 ## 211 # mariadbDatabase: 212 ``` 213 214 You can then override any of these settings in a YAML formatted file, 215 and then pass that file during installation. 216 217 ```console 218 $ echo '{mariadbUser: user0, mariadbDatabase: user0db}' > config.yaml 219 $ helm install -f config.yaml stable/mariadb 220 ``` 221 222 The above will create a default MariaDB user with the name `user0`, and 223 grant this user access to a newly created `user0db` database, but will 224 accept all the rest of the defaults for that chart. 225 226 There are two ways to pass configuration data during install: 227 228 - `--values` (or `-f`): Specify a YAML file with overrides. This can be specified multiple times 229 and the rightmost file will take precedence 230 - `--set`: Specify overrides on the command line. 231 232 If both are used, `--set` values are merged into `--values` with higher precedence. 233 Overrides specified with `--set` are persisted in a configmap. Values that have been 234 `--set` can be viewed for a given release with `helm get values <release-name>`. 235 Values that have been `--set` can be cleared by running `helm upgrade` with `--reset-values` 236 specified. 237 238 #### The Format and Limitations of `--set` 239 240 The `--set` option takes zero or more name/value pairs. At its simplest, it is 241 used like this: `--set name=value`. The YAML equivalent of that is: 242 243 ```yaml 244 name: value 245 ``` 246 247 Multiple values are separated by `,` characters. So `--set a=b,c=d` becomes: 248 249 ```yaml 250 a: b 251 c: d 252 ``` 253 254 More complex expressions are supported. For example, `--set outer.inner=value` is 255 translated into this: 256 ```yaml 257 outer: 258 inner: value 259 ``` 260 261 Lists can be expressed by enclosing values in `{` and `}`. For example, 262 `--set name={a, b, c}` translates to: 263 264 ```yaml 265 name: 266 - a 267 - b 268 - c 269 ``` 270 271 As of Helm 2.5.0, it is possible to access list items using an array index syntax. 272 For example, `--set servers[0].port=80` becomes: 273 274 ```yaml 275 servers: 276 - port: 80 277 ``` 278 279 Multiple values can be set this way. The line `--set servers[0].port=80,servers[0].host=example` becomes: 280 281 ```yaml 282 servers: 283 - port: 80 284 host: example 285 ``` 286 287 Sometimes you need to use special characters in your `--set` lines. You can use 288 a backslash to escape the characters; `--set name=value1\,value2` will become: 289 290 ```yaml 291 name: "value1,value2" 292 ``` 293 294 Similarly, you can escape dot sequences as well, which may come in handy when charts use the 295 `toYaml` function to parse annotations, labels and node selectors. The syntax for 296 `--set nodeSelector."kubernetes\.io/role"=master` becomes: 297 298 ```yaml 299 nodeSelector: 300 kubernetes.io/role: master 301 ``` 302 303 Deeply nested data structures can be difficult to express using `--set`. Chart 304 designers are encouraged to consider the `--set` usage when designing the format 305 of a `values.yaml` file. 306 307 ### More Installation Methods 308 309 The `helm install` command can install from several sources: 310 311 - A chart repository (as we've seen above) 312 - A local chart archive (`helm install foo-0.1.1.tgz`) 313 - An unpacked chart directory (`helm install path/to/foo`) 314 - A full URL (`helm install https://example.com/charts/foo-1.2.3.tgz`) 315 316 ## 'helm upgrade' and 'helm rollback': Upgrading a Release, and Recovering on Failure 317 318 When a new version of a chart is released, or when you want to change 319 the configuration of your release, you can use the `helm upgrade` 320 command. 321 322 An upgrade takes an existing release and upgrades it according to the 323 information you provide. Because Kubernetes charts can be large and 324 complex, Helm tries to perform the least invasive upgrade. It will only 325 update things that have changed since the last release. 326 327 ```console 328 $ helm upgrade -f panda.yaml happy-panda stable/mariadb 329 Fetched stable/mariadb-0.3.0.tgz to /Users/mattbutcher/Code/Go/src/k8s.io/helm/mariadb-0.3.0.tgz 330 happy-panda has been upgraded. Happy Helming! 331 Last Deployed: Wed Sep 28 12:47:54 2016 332 Namespace: default 333 Status: DEPLOYED 334 ... 335 ``` 336 337 In the above case, the `happy-panda` release is upgraded with the same 338 chart, but with a new YAML file: 339 340 ```yaml 341 mariadbUser: user1 342 ``` 343 344 We can use `helm get values` to see whether that new setting took 345 effect. 346 347 ```console 348 $ helm get values happy-panda 349 mariadbUser: user1 350 ``` 351 352 The `helm get` command is a useful tool for looking at a release in the 353 cluster. And as we can see above, it shows that our new values from 354 `panda.yaml` were deployed to the cluster. 355 356 Now, if something does not go as planned during a release, it is easy to 357 roll back to a previous release using `helm rollback [RELEASE] [REVISION]`. 358 359 ```console 360 $ helm rollback happy-panda 1 361 ``` 362 363 The above rolls back our happy-panda to its very first release version. 364 A release version is an incremental revision. Every time an install, 365 upgrade, or rollback happens, the revision number is incremented by 1. 366 The first revision number is always 1. And we can use `helm history [RELEASE]` 367 to see revision numbers for a certain release. 368 369 ## Helpful Options for Install/Upgrade/Rollback 370 There are several other helpful options you can specify for customizing the 371 behavior of Helm during an install/upgrade/rollback. Please note that this 372 is not a full list of cli flags. To see a description of all flags, just run 373 `helm <command> --help`. 374 375 - `--timeout`: A value in seconds to wait for Kubernetes commands to complete 376 This defaults to 300 (5 minutes) 377 - `--wait`: Waits until all Pods are in a ready state, PVCs are bound, Deployments 378 have minimum (`Desired` minus `maxUnavailable`) Pods in ready state and 379 Services have an IP address (and Ingress if a `LoadBalancer`) before 380 marking the release as successful. It will wait for as long as the 381 `--timeout` value. If timeout is reached, the release will be marked as 382 `FAILED`. Note: In scenario where Deployment has `replicas` set to 1 and 383 `maxUnavailable` is not set to 0 as part of rolling update strategy, 384 `--wait` will return as ready as it has satisfied the minimum Pod in ready condition. 385 - `--no-hooks`: This skips running hooks for the command 386 - `--recreate-pods` (only available for `upgrade` and `rollback`): This flag 387 will cause all pods to be recreated (with the exception of pods belonging to 388 deployments) 389 390 ## 'helm delete': Deleting a Release 391 392 When it is time to uninstall or delete a release from the cluster, use 393 the `helm delete` command: 394 395 ``` 396 $ helm delete happy-panda 397 ``` 398 399 This will remove the release from the cluster. You can see all of your 400 currently deployed releases with the `helm list` command: 401 402 ``` 403 $ helm list 404 NAME VERSION UPDATED STATUS CHART 405 inky-cat 1 Wed Sep 28 12:59:46 2016 DEPLOYED alpine-0.1.0 406 ``` 407 408 From the output above, we can see that the `happy-panda` release was 409 deleted. 410 411 However, Helm always keeps records of what releases happened. Need to 412 see the deleted releases? `helm list --deleted` shows those, and `helm 413 list --all` shows all of the releases (deleted and currently deployed, 414 as well as releases that failed): 415 416 ```console 417 ⇒ helm list --all 418 NAME VERSION UPDATED STATUS CHART 419 happy-panda 2 Wed Sep 28 12:47:54 2016 DELETED mariadb-0.3.0 420 inky-cat 1 Wed Sep 28 12:59:46 2016 DEPLOYED alpine-0.1.0 421 kindred-angelf 2 Tue Sep 27 16:16:10 2016 DELETED alpine-0.1.0 422 ``` 423 424 Because Helm keeps records of deleted releases, a release name cannot be 425 re-used. (If you _really_ need to re-use a release name, you can use the 426 `--replace` flag, but it will simply re-use the existing release and 427 replace its resources.) 428 429 Note that because releases are preserved in this way, you can rollback a 430 deleted resource, and have it re-activate. 431 432 ## 'helm repo': Working with Repositories 433 434 So far, we've been installing charts only from the `stable` repository. 435 But you can configure `helm` to use other repositories. Helm provides 436 several repository tools under the `helm repo` command. 437 438 You can see which repositories are configured using `helm repo list`: 439 440 ```console 441 $ helm repo list 442 NAME URL 443 stable https://kubernetes-charts.storage.googleapis.com 444 local http://localhost:8879/charts 445 mumoshu https://mumoshu.github.io/charts 446 ``` 447 448 And new repositories can be added with `helm repo add`: 449 450 ```console 451 $ helm repo add dev https://example.com/dev-charts 452 ``` 453 454 Because chart repositories change frequently, at any point you can make 455 sure your Helm client is up to date by running `helm repo update`. 456 457 ## Creating Your Own Charts 458 459 The [Chart Development Guide](charts.md) explains how to develop your own 460 charts. But you can get started quickly by using the `helm create` 461 command: 462 463 ```console 464 $ helm create deis-workflow 465 Creating deis-workflow 466 ``` 467 468 Now there is a chart in `./deis-workflow`. You can edit it and create 469 your own templates. 470 471 As you edit your chart, you can validate that it is well-formatted by 472 running `helm lint`. 473 474 When it's time to package the chart up for distribution, you can run the 475 `helm package` command: 476 477 ```console 478 $ helm package deis-workflow 479 deis-workflow-0.1.0.tgz 480 ``` 481 482 And that chart can now easily be installed by `helm install`: 483 484 ```console 485 $ helm install ./deis-workflow-0.1.0.tgz 486 ... 487 ``` 488 489 Charts that are archived can be loaded into chart repositories. See the 490 documentation for your chart repository server to learn how to upload. 491 492 Note: The `stable` repository is managed on the [Kubernetes Charts 493 GitHub repository](https://github.com/kubernetes/charts). That project 494 accepts chart source code, and (after audit) packages those for you. 495 496 ## Tiller, Namespaces and RBAC 497 In some cases you may wish to scope Tiller or deploy multiple Tillers to a single cluster. Here are some best practices when operating in those circumstances. 498 499 1. Tiller can be [installed](install.md) into any namespace. By default, it is installed into kube-system. You can run multiple Tillers provided they each run in their own namespace. 500 2. Limiting Tiller to only be able to install into specific namespaces and/or resource types is controlled by Kubernetes [RBAC](https://kubernetes.io/docs/admin/authorization/rbac/) roles and rolebindings. You can add a service account to Tiller when configuring Helm via `helm init --service-account <NAME>`. You can find more information about that [here](rbac.md). 501 3. Release names are unique PER TILLER INSTANCE. 502 4. Charts should only contain resources that exist in a single namespace. 503 5. It is not recommended to have multiple Tillers configured to manage resources in the same namespace. 504 505 ## Conclusion 506 507 This chapter has covered the basic usage patterns of the `helm` client, 508 including searching, installation, upgrading, and deleting. It has also 509 covered useful utility commands like `helm status`, `helm get`, and 510 `helm repo`. 511 512 For more information on these commands, take a look at Helm's built-in 513 help: `helm help`. 514 515 In the next chapter, we look at the process of developing charts.