github.com/Beeketing/helm@v2.12.1+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 ```console 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 ```console 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 ```console 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 ```console 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 NAME: 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 ```console 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` (and its variants `--set-string` and `--set-file`): 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 Helm will cast certain values specified with `--set` to integers. 308 For example, `--set foo=true` results Helm to cast `true` into an int64 value. 309 In case you want a string, use a `--set`'s variant named `--set-string`. `--set-string foo=true` results in a string value of `"true"`. 310 311 `--set-file key=filepath` is another variant of `--set`. 312 It reads the file and use its content as a value. 313 An example use case of it is to inject a multi-line text into values without dealing with indentation in YAML. 314 Say you want to create a [brigade](https://github.com/Azure/brigade) project with certain value containing 5 lines JavaScript code, you might write a `values.yaml` like: 315 316 ```yaml 317 defaultScript: | 318 const { events, Job } = require("brigadier") 319 function run(e, project) { 320 console.log("hello default script") 321 } 322 events.on("run", run) 323 ``` 324 325 Being embedded in a YAML, this makes it harder for you to use IDE features and testing framework and so on that supports writing code. 326 Instead, you can use `--set-file defaultScript=brigade.js` with `brigade.js` containing: 327 328 ```javascript 329 const { events, Job } = require("brigadier") 330 function run(e, project) { 331 console.log("hello default script") 332 } 333 events.on("run", run) 334 ``` 335 336 ### More Installation Methods 337 338 The `helm install` command can install from several sources: 339 340 - A chart repository (as we've seen above) 341 - A local chart archive (`helm install foo-0.1.1.tgz`) 342 - An unpacked chart directory (`helm install path/to/foo`) 343 - A full URL (`helm install https://example.com/charts/foo-1.2.3.tgz`) 344 345 ## 'helm upgrade' and 'helm rollback': Upgrading a Release, and Recovering on Failure 346 347 When a new version of a chart is released, or when you want to change 348 the configuration of your release, you can use the `helm upgrade` 349 command. 350 351 An upgrade takes an existing release and upgrades it according to the 352 information you provide. Because Kubernetes charts can be large and 353 complex, Helm tries to perform the least invasive upgrade. It will only 354 update things that have changed since the last release. 355 356 ```console 357 $ helm upgrade -f panda.yaml happy-panda stable/mariadb 358 Fetched stable/mariadb-0.3.0.tgz to /Users/mattbutcher/Code/Go/src/k8s.io/helm/mariadb-0.3.0.tgz 359 happy-panda has been upgraded. Happy Helming! 360 Last Deployed: Wed Sep 28 12:47:54 2016 361 Namespace: default 362 Status: DEPLOYED 363 ... 364 ``` 365 366 In the above case, the `happy-panda` release is upgraded with the same 367 chart, but with a new YAML file: 368 369 ```yaml 370 mariadbUser: user1 371 ``` 372 373 We can use `helm get values` to see whether that new setting took 374 effect. 375 376 ```console 377 $ helm get values happy-panda 378 mariadbUser: user1 379 ``` 380 381 The `helm get` command is a useful tool for looking at a release in the 382 cluster. And as we can see above, it shows that our new values from 383 `panda.yaml` were deployed to the cluster. 384 385 Now, if something does not go as planned during a release, it is easy to 386 roll back to a previous release using `helm rollback [RELEASE] [REVISION]`. 387 388 ```console 389 $ helm rollback happy-panda 1 390 ``` 391 392 The above rolls back our happy-panda to its very first release version. 393 A release version is an incremental revision. Every time an install, 394 upgrade, or rollback happens, the revision number is incremented by 1. 395 The first revision number is always 1. And we can use `helm history [RELEASE]` 396 to see revision numbers for a certain release. 397 398 ## Helpful Options for Install/Upgrade/Rollback 399 There are several other helpful options you can specify for customizing the 400 behavior of Helm during an install/upgrade/rollback. Please note that this 401 is not a full list of cli flags. To see a description of all flags, just run 402 `helm <command> --help`. 403 404 - `--timeout`: A value in seconds to wait for Kubernetes commands to complete 405 This defaults to 300 (5 minutes) 406 - `--wait`: Waits until all Pods are in a ready state, PVCs are bound, Deployments 407 have minimum (`Desired` minus `maxUnavailable`) Pods in ready state and 408 Services have an IP address (and Ingress if a `LoadBalancer`) before 409 marking the release as successful. It will wait for as long as the 410 `--timeout` value. If timeout is reached, the release will be marked as 411 `FAILED`. Note: In scenario where Deployment has `replicas` set to 1 and 412 `maxUnavailable` is not set to 0 as part of rolling update strategy, 413 `--wait` will return as ready as it has satisfied the minimum Pod in ready condition. 414 - `--no-hooks`: This skips running hooks for the command 415 - `--recreate-pods` (only available for `upgrade` and `rollback`): This flag 416 will cause all pods to be recreated (with the exception of pods belonging to 417 deployments) 418 419 ## 'helm delete': Deleting a Release 420 421 When it is time to uninstall or delete a release from the cluster, use 422 the `helm delete` command: 423 424 ```console 425 $ helm delete happy-panda 426 ``` 427 428 This will remove the release from the cluster. You can see all of your 429 currently deployed releases with the `helm list` command: 430 431 ```console 432 $ helm list 433 NAME VERSION UPDATED STATUS CHART 434 inky-cat 1 Wed Sep 28 12:59:46 2016 DEPLOYED alpine-0.1.0 435 ``` 436 437 From the output above, we can see that the `happy-panda` release was 438 deleted. 439 440 However, Helm always keeps records of what releases happened. Need to 441 see the deleted releases? `helm list --deleted` shows those, and `helm 442 list --all` shows all of the releases (deleted and currently deployed, 443 as well as releases that failed): 444 445 ```console 446 ⇒ helm list --all 447 NAME VERSION UPDATED STATUS CHART 448 happy-panda 2 Wed Sep 28 12:47:54 2016 DELETED mariadb-0.3.0 449 inky-cat 1 Wed Sep 28 12:59:46 2016 DEPLOYED alpine-0.1.0 450 kindred-angelf 2 Tue Sep 27 16:16:10 2016 DELETED alpine-0.1.0 451 ``` 452 453 Because Helm keeps records of deleted releases, a release name cannot be 454 re-used. (If you _really_ need to re-use a release name, you can use the 455 `--replace` flag, but it will simply re-use the existing release and 456 replace its resources.) 457 458 Note that because releases are preserved in this way, you can rollback a 459 deleted resource, and have it re-activate. 460 461 ## 'helm repo': Working with Repositories 462 463 So far, we've been installing charts only from the `stable` repository. 464 But you can configure `helm` to use other repositories. Helm provides 465 several repository tools under the `helm repo` command. 466 467 You can see which repositories are configured using `helm repo list`: 468 469 ```console 470 $ helm repo list 471 NAME URL 472 stable https://kubernetes-charts.storage.googleapis.com 473 local http://localhost:8879/charts 474 mumoshu https://mumoshu.github.io/charts 475 ``` 476 477 And new repositories can be added with `helm repo add`: 478 479 ```console 480 $ helm repo add dev https://example.com/dev-charts 481 ``` 482 483 Because chart repositories change frequently, at any point you can make 484 sure your Helm client is up to date by running `helm repo update`. 485 486 ## Creating Your Own Charts 487 488 The [Chart Development Guide](charts.md) explains how to develop your own 489 charts. But you can get started quickly by using the `helm create` 490 command: 491 492 ```console 493 $ helm create deis-workflow 494 Creating deis-workflow 495 ``` 496 497 Now there is a chart in `./deis-workflow`. You can edit it and create 498 your own templates. 499 500 As you edit your chart, you can validate that it is well-formatted by 501 running `helm lint`. 502 503 When it's time to package the chart up for distribution, you can run the 504 `helm package` command: 505 506 ```console 507 $ helm package deis-workflow 508 deis-workflow-0.1.0.tgz 509 ``` 510 511 And that chart can now easily be installed by `helm install`: 512 513 ```console 514 $ helm install ./deis-workflow-0.1.0.tgz 515 ... 516 ``` 517 518 Charts that are archived can be loaded into chart repositories. See the 519 documentation for your chart repository server to learn how to upload. 520 521 Note: The `stable` repository is managed on the [Helm Charts 522 GitHub repository](https://github.com/helm/charts). That project 523 accepts chart source code, and (after audit) packages those for you. 524 525 ## Tiller, Namespaces and RBAC 526 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. 527 528 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. 529 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). 530 3. Release names are unique PER TILLER INSTANCE. 531 4. Charts should only contain resources that exist in a single namespace. 532 5. It is not recommended to have multiple Tillers configured to manage resources in the same namespace. 533 534 ## Conclusion 535 536 This chapter has covered the basic usage patterns of the `helm` client, 537 including searching, installation, upgrading, and deleting. It has also 538 covered useful utility commands like `helm status`, `helm get`, and 539 `helm repo`. 540 541 For more information on these commands, take a look at Helm's built-in 542 help: `helm help`. 543 544 In the next chapter, we look at the process of developing charts.