github.com/appscode/helm@v3.0.0-alpha.1+incompatible/docs/charts.md (about) 1 # Charts 2 3 Helm uses a packaging format called _charts_. A chart is a collection of files 4 that describe a related set of Kubernetes resources. A single chart 5 might be used to deploy something simple, like a memcached pod, or 6 something complex, like a full web app stack with HTTP servers, 7 databases, caches, and so on. 8 9 Charts are created as files laid out in a particular directory tree, 10 then they can be packaged into versioned archives to be deployed. 11 12 This document explains the chart format, and provides basic guidance for 13 building charts with Helm. 14 15 ## The Chart File Structure 16 17 A chart is organized as a collection of files inside of a directory. The 18 directory name is the name of the chart (without versioning information). Thus, 19 a chart describing WordPress would be stored in the `wordpress/` directory. 20 21 Inside of this directory, Helm will expect a structure that matches this: 22 23 ``` 24 wordpress/ 25 Chart.yaml # A YAML file containing information about the chart 26 LICENSE # OPTIONAL: A plain text file containing the license for the chart 27 README.md # OPTIONAL: A human-readable README file 28 values.yaml # The default configuration values for this chart 29 values.schema.json # OPTIONAL: A JSON Schema for imposing a structure on the values.yaml file 30 charts/ # A directory containing any charts upon which this chart depends. 31 templates/ # A directory of templates that, when combined with values, 32 # will generate valid Kubernetes manifest files. 33 templates/NOTES.txt # OPTIONAL: A plain text file containing short usage notes 34 ``` 35 36 Helm reserves use of the `charts/` and `templates/` directories, and of 37 the listed file names. Other files will be left as they are. 38 39 ## The Chart.yaml File 40 41 The `Chart.yaml` file is required for a chart. It contains the following fields: 42 43 ```yaml 44 name: The name of the chart (required) 45 version: A SemVer 2 version (required) 46 kubeVersion: A SemVer range of compatible Kubernetes versions (optional) 47 description: A single-sentence description of this project (optional) 48 type: It is the type of chart (optional) 49 keywords: 50 - A list of keywords about this project (optional) 51 home: The URL of this project's home page (optional) 52 sources: 53 - A list of URLs to source code for this project (optional) 54 dependencies: # A list of the chart requirements (optional) 55 - name: The name of the chart (nginx) 56 version: The version of the chart ("1.2.3") 57 repository: The repository URL ("https://example.com/charts") 58 maintainers: # (optional) 59 - name: The maintainer's name (required for each maintainer) 60 email: The maintainer's email (optional for each maintainer) 61 url: A URL for the maintainer (optional for each maintainer) 62 icon: A URL to an SVG or PNG image to be used as an icon (optional). 63 appVersion: The version of the app that this contains (optional). This needn't be SemVer. 64 deprecated: Whether this chart is deprecated (optional, boolean) 65 ``` 66 67 Other fields will be silently ignored. 68 69 ### Charts and Versioning 70 71 Every chart must have a version number. A version must follow the 72 [SemVer 2](http://semver.org/) standard. Unlike Helm Classic, Kubernetes 73 Helm uses version numbers as release markers. Packages in repositories 74 are identified by name plus version. 75 76 For example, an `nginx` chart whose version field is set to `version: 77 1.2.3` will be named: 78 79 ``` 80 nginx-1.2.3.tgz 81 ``` 82 83 More complex SemVer 2 names are also supported, such as 84 `version: 1.2.3-alpha.1+ef365`. But non-SemVer names are explicitly 85 disallowed by the system. 86 87 **NOTE:** Whereas Helm Classic and Deployment Manager were both 88 very GitHub oriented when it came to charts, Kubernetes Helm does not 89 rely upon or require GitHub or even Git. Consequently, it does not use 90 Git SHAs for versioning at all. 91 92 The `version` field inside of the `Chart.yaml` is used by many of the 93 Helm tools, including the CLI. When generating a 94 package, the `helm package` command will use the version that it finds 95 in the `Chart.yaml` as a token in the package name. The system assumes 96 that the version number in the chart package name matches the version number in 97 the `Chart.yaml`. Failure to meet this assumption will cause an error. 98 99 ### The appVersion field 100 101 Note that the `appVersion` field is not related to the `version` field. It is 102 a way of specifying the version of the application. For example, the `drupal` 103 chart may have an `appVersion: 8.2.1`, indicating that the version of Drupal 104 included in the chart (by default) is `8.2.1`. This field is informational, and 105 has no impact on chart version calculations. 106 107 ### Deprecating Charts 108 109 When managing charts in a Chart Repository, it is sometimes necessary to 110 deprecate a chart. The optional `deprecated` field in `Chart.yaml` can be used 111 to mark a chart as deprecated. If the **latest** version of a chart in the 112 repository is marked as deprecated, then the chart as a whole is considered to 113 be deprecated. The chart name can later be reused by publishing a newer version 114 that is not marked as deprecated. The workflow for deprecating charts, as 115 followed by the [kubernetes/charts](https://github.com/helm/charts) 116 project is: 117 - Update chart's `Chart.yaml` to mark the chart as deprecated, bumping the 118 version 119 - Release the new chart version in the Chart Repository 120 - Remove the chart from the source repository (e.g. git) 121 122 ### Chart Types 123 124 The `type` field defines the type of chart. There are 2 types: `application` 125 and `library`. Application is the default type and it is the standard chart 126 which can be operated on fully. The [library or helper chart](https://github.com/helm/charts/tree/master/incubator/common) 127 provides utilities or functions for the chart builder. A library chart differs 128 from an application chart because it has no resource object and is therefore not 129 installable. 130 131 **Note:** An application chart can be used as a library chart. This is enabled by setting the 132 type to `library`. The chart will then be rendered as a library chart where all utilities and 133 functions can be leveraged. All resource objects of the chart will not be rendered. 134 135 ## Chart LICENSE, README and NOTES 136 137 Charts can also contain files that describe the installation, configuration, usage and license of a 138 chart. A README for a chart should be formatted in Markdown (README.md), and should generally 139 contain: 140 141 - A description of the application or service the chart provides 142 - Any prerequisites or requirements to run the chart 143 - Descriptions of options in `values.yaml` and default values 144 - Any other information that may be relevant to the installation or configuration of the chart 145 146 The chart can also contain a short plain text `templates/NOTES.txt` file that will be printed out 147 after installation, and when viewing the status of a release. This file is evaluated as a 148 [template](#templates-and-values), and can be used to display usage notes, next steps, or any other 149 information relevant to a release of the chart. For example, instructions could be provided for 150 connecting to a database, or accessing a web UI. Since this file is printed to STDOUT when running 151 `helm install` or `helm status`, it is recommended to keep the content brief and point to the README 152 for greater detail. 153 154 ## Chart Dependencies 155 156 In Helm, one chart may depend on any number of other charts. 157 These dependencies can be dynamically linked using the `dependencies` field in `Chart.yaml` or brought in to the `charts/` directory and managed manually. 158 159 ### Managing Dependencies with the `dependencies` field 160 161 The charts required by the current chart are defined as a list in the `dependencies` field. 162 163 ```yaml 164 dependencies: 165 - name: apache 166 version: 1.2.3 167 repository: http://example.com/charts 168 - name: mysql 169 version: 3.2.1 170 repository: http://another.example.com/charts 171 ``` 172 173 - The `name` field is the name of the chart you want. 174 - The `version` field is the version of the chart you want. 175 - The `repository` field is the full URL to the chart repository. Note 176 that you must also use `helm repo add` to add that repo locally. 177 178 Once you have defined dependencies, you can run `helm dependency update` 179 and it will use your dependency file to download all the specified 180 charts into your `charts/` directory for you. 181 182 ```console 183 $ helm dep up foochart 184 Hang tight while we grab the latest from your chart repositories... 185 ...Successfully got an update from the "local" chart repository 186 ...Successfully got an update from the "stable" chart repository 187 ...Successfully got an update from the "example" chart repository 188 ...Successfully got an update from the "another" chart repository 189 Update Complete. Happy Helming! 190 Saving 2 charts 191 Downloading apache from repo http://example.com/charts 192 Downloading mysql from repo http://another.example.com/charts 193 ``` 194 195 When `helm dependency update` retrieves charts, it will store them as 196 chart archives in the `charts/` directory. So for the example above, one 197 would expect to see the following files in the charts directory: 198 199 ``` 200 charts/ 201 apache-1.2.3.tgz 202 mysql-3.2.1.tgz 203 ``` 204 205 #### Alias field in dependencies 206 207 In addition to the other fields above, each requirements entry may contain 208 the optional field `alias`. 209 210 Adding an alias for a dependency chart would put 211 a chart in dependencies using alias as name of new dependency. 212 213 One can use `alias` in cases where they need to access a chart 214 with other name(s). 215 216 ```yaml 217 # parentchart/Chart.yaml 218 dependencies: 219 - name: subchart 220 repository: http://localhost:10191 221 version: 0.1.0 222 alias: new-subchart-1 223 - name: subchart 224 repository: http://localhost:10191 225 version: 0.1.0 226 alias: new-subchart-2 227 - name: subchart 228 repository: http://localhost:10191 229 version: 0.1.0 230 ``` 231 232 In the above example we will get 3 dependencies in all for `parentchart` 233 ``` 234 subchart 235 new-subchart-1 236 new-subchart-2 237 ``` 238 239 The manual way of achieving this is by copy/pasting the same chart in the 240 `charts/` directory multiple times with different names. 241 242 #### Tags and Condition fields in dependencies 243 244 In addition to the other fields above, each requirements entry may contain 245 the optional fields `tags` and `condition`. 246 247 All charts are loaded by default. If `tags` or `condition` fields are present, 248 they will be evaluated and used to control loading for the chart(s) they are applied to. 249 250 Condition - The condition field holds one or more YAML paths (delimited by commas). 251 If this path exists in the top parent's values and resolves to a boolean value, 252 the chart will be enabled or disabled based on that boolean value. Only the first 253 valid path found in the list is evaluated and if no paths exist then the condition has no effect. 254 255 Tags - The tags field is a YAML list of labels to associate with this chart. 256 In the top parent's values, all charts with tags can be enabled or disabled by 257 specifying the tag and a boolean value. 258 259 ```` 260 # parentchart/Chart.yaml 261 dependencies: 262 - name: subchart1 263 repository: http://localhost:10191 264 version: 0.1.0 265 condition: subchart1.enabled, global.subchart1.enabled 266 tags: 267 - front-end 268 - subchart1 269 270 - name: subchart2 271 repository: http://localhost:10191 272 version: 0.1.0 273 condition: subchart2.enabled,global.subchart2.enabled 274 tags: 275 - back-end 276 - subchart2 277 278 ```` 279 ```` 280 # parentchart/values.yaml 281 282 subchart1: 283 enabled: true 284 tags: 285 front-end: false 286 back-end: true 287 ```` 288 289 In the above example all charts with the tag `front-end` would be disabled but since the 290 `subchart1.enabled` path evaluates to 'true' in the parent's values, the condition will override the 291 `front-end` tag and `subchart1` will be enabled. 292 293 Since `subchart2` is tagged with `back-end` and that tag evaluates to `true`, `subchart2` will be 294 enabled. Also notes that although `subchart2` has a condition specified, there 295 is no corresponding path and value in the parent's values so that condition has no effect. 296 297 ##### Using the CLI with Tags and Conditions 298 299 The `--set` parameter can be used as usual to alter tag and condition values. 300 301 ```` 302 helm install --set tags.front-end=true --set subchart2.enabled=false 303 304 ```` 305 306 ##### Tags and Condition Resolution 307 308 309 * **Conditions (when set in values) always override tags.** The first condition 310 path that exists wins and subsequent ones for that chart are ignored. 311 * Tags are evaluated as 'if any of the chart's tags are true then enable the chart'. 312 * Tags and conditions values must be set in the top parent's values. 313 * The `tags:` key in values must be a top level key. Globals and nested `tags:` tables 314 are not currently supported. 315 316 #### Importing Child Values via dependencies 317 318 In some cases it is desirable to allow a child chart's values to propagate to the parent chart and be 319 shared as common defaults. An additional benefit of using the `exports` format is that it will enable future 320 tooling to introspect user-settable values. 321 322 The keys containing the values to be imported can be specified in the parent chart's `dependencies` in the field `input-values` 323 using a YAML list. Each item in the list is a key which is imported from the child chart's `exports` field. 324 325 To import values not contained in the `exports` key, use the [child-parent](#using-the-child-parent-format) format. 326 Examples of both formats are described below. 327 328 ##### Using the exports format 329 330 If a child chart's `values.yaml` file contains an `exports` field at the root, its contents may be imported 331 directly into the parent's values by specifying the keys to import as in the example below: 332 333 ```yaml 334 # parent's Chart.yaml file 335 336 dependencies: 337 - name: subchart 338 repository: http://localhost:10191 339 version: 0.1.0 340 import-values: 341 - data 342 ``` 343 ```yaml 344 # child's values.yaml file 345 ... 346 exports: 347 data: 348 myint: 99 349 ``` 350 351 Since we are specifying the key `data` in our import list, Helm looks in the `exports` field of the child 352 chart for `data` key and imports its contents. 353 354 The final parent values would contain our exported field: 355 356 ```yaml 357 # parent's values file 358 ... 359 myint: 99 360 361 ``` 362 363 Please note the parent key `data` is not contained in the parent's final values. If you need to specify the 364 parent key, use the 'child-parent' format. 365 366 ##### Using the child-parent format 367 368 To access values that are not contained in the `exports` key of the child chart's values, you will need to 369 specify the source key of the values to be imported (`child`) and the destination path in the parent chart's 370 values (`parent`). 371 372 The `import-values` in the example below instructs Helm to take any values found at `child:` path and copy them 373 to the parent's values at the path specified in `parent:` 374 375 ```yaml 376 # parent's Chart.yaml file 377 dependencies: 378 - name: subchart1 379 repository: http://localhost:10191 380 version: 0.1.0 381 ... 382 import-values: 383 - child: default.data 384 parent: myimports 385 ``` 386 In the above example, values found at `default.data` in the subchart1's values will be imported 387 to the `myimports` key in the parent chart's values as detailed below: 388 389 ```yaml 390 # parent's values.yaml file 391 392 myimports: 393 myint: 0 394 mybool: false 395 mystring: "helm rocks!" 396 397 ``` 398 ```yaml 399 # subchart1's values.yaml file 400 401 default: 402 data: 403 myint: 999 404 mybool: true 405 406 ``` 407 The parent chart's resulting values would be: 408 409 ```yaml 410 # parent's final values 411 412 myimports: 413 myint: 999 414 mybool: true 415 mystring: "helm rocks!" 416 417 ``` 418 419 The parent's final values now contains the `myint` and `mybool` fields imported from subchart1. 420 421 ### Managing Dependencies manually via the `charts/` directory 422 423 If more control over dependencies is desired, these dependencies can 424 be expressed explicitly by copying the dependency charts into the 425 `charts/` directory. 426 427 A dependency can be either a chart archive (`foo-1.2.3.tgz`) or an 428 unpacked chart directory. But its name cannot start with `_` or `.`. 429 Such files are ignored by the chart loader. 430 431 For example, if the WordPress chart depends on the Apache chart, the 432 Apache chart (of the correct version) is supplied in the WordPress 433 chart's `charts/` directory: 434 435 ``` 436 wordpress: 437 Chart.yaml 438 # ... 439 charts/ 440 apache/ 441 Chart.yaml 442 # ... 443 mysql/ 444 Chart.yaml 445 # ... 446 ``` 447 448 The example above shows how the WordPress chart expresses its dependency 449 on Apache and MySQL by including those charts inside of its `charts/` 450 directory. 451 452 **TIP:** _To drop a dependency into your `charts/` directory, use the 453 `helm pull` command_ 454 455 ### Operational aspects of using dependencies 456 457 The above sections explain how to specify chart dependencies, but how does this affect 458 chart installation using `helm install` and `helm upgrade`? 459 460 Suppose that a chart named "A" creates the following Kubernetes objects 461 462 - namespace "A-Namespace" 463 - statefulset "A-StatefulSet" 464 - service "A-Service" 465 466 Furthermore, A is dependent on chart B that creates objects 467 468 - namespace "B-Namespace" 469 - replicaset "B-ReplicaSet" 470 - service "B-Service" 471 472 After installation/upgrade of chart A a single Helm release is created/modified. The release will 473 create/update all of the above Kubernetes objects in the following order: 474 475 - A-Namespace 476 - B-Namespace 477 - A-StatefulSet 478 - B-ReplicaSet 479 - A-Service 480 - B-Service 481 482 This is because when Helm installs/upgrades charts, 483 the Kubernetes objects from the charts and all its dependencies are 484 485 - aggregrated into a single set; then 486 - sorted by type followed by name; and then 487 - created/updated in that order. 488 489 Hence a single release is created with all the objects for the chart and its dependencies. 490 491 The install order of Kubernetes types is given by the enumeration InstallOrder in kind_sorter.go 492 (see [the Helm source file](https://github.com/helm/helm/blob/dev-v3/pkg/tiller/kind_sorter.go#L26)). 493 494 ## Templates and Values 495 496 Helm Chart templates are written in the 497 [Go template language](https://golang.org/pkg/text/template/), with the 498 addition of 50 or so add-on template 499 functions [from the Sprig library](https://github.com/Masterminds/sprig) and a 500 few other [specialized functions](charts_tips_and_tricks.md). 501 502 All template files are stored in a chart's `templates/` folder. When 503 Helm renders the charts, it will pass every file in that directory 504 through the template engine. 505 506 Values for the templates are supplied two ways: 507 508 - Chart developers may supply a file called `values.yaml` inside of a 509 chart. This file can contain default values. 510 - Chart users may supply a YAML file that contains values. This can be 511 provided on the command line with `helm install`. 512 513 When a user supplies custom values, these values will override the 514 values in the chart's `values.yaml` file. 515 516 ### Template Files 517 518 Template files follow the standard conventions for writing Go templates 519 (see [the text/template Go package documentation](https://golang.org/pkg/text/template/) 520 for details). 521 An example template file might look something like this: 522 523 ```yaml 524 apiVersion: v1 525 kind: ReplicationController 526 metadata: 527 name: deis-database 528 namespace: deis 529 labels: 530 app.kubernetes.io/managed-by: deis 531 spec: 532 replicas: 1 533 selector: 534 app.kubernetes.io/name: deis-database 535 template: 536 metadata: 537 labels: 538 app.kubernetes.io/name: deis-database 539 spec: 540 serviceAccount: deis-database 541 containers: 542 - name: deis-database 543 image: {{.Values.imageRegistry}}/postgres:{{.Values.dockerTag}} 544 imagePullPolicy: {{.Values.pullPolicy}} 545 ports: 546 - containerPort: 5432 547 env: 548 - name: DATABASE_STORAGE 549 value: {{default "minio" .Values.storage}} 550 ``` 551 552 The above example, based loosely on [https://github.com/deis/charts](https://github.com/deis/charts), is a template for a Kubernetes replication controller. 553 It can use the following four template values (usually defined in a 554 `values.yaml` file): 555 556 - `imageRegistry`: The source registry for the Docker image. 557 - `dockerTag`: The tag for the docker image. 558 - `pullPolicy`: The Kubernetes pull policy. 559 - `storage`: The storage backend, whose default is set to `"minio"` 560 561 All of these values are defined by the template author. Helm does not 562 require or dictate parameters. 563 564 To see many working charts, check out the [Kubernetes Charts 565 project](https://github.com/helm/charts) 566 567 ### Predefined Values 568 569 Values that are supplied via a `values.yaml` file (or via the `--set` 570 flag) are accessible from the `.Values` object in a template. But there 571 are other pre-defined pieces of data you can access in your templates. 572 573 The following values are pre-defined, are available to every template, and 574 cannot be overridden. As with all values, the names are _case 575 sensitive_. 576 577 - `Release.Name`: The name of the release (not the chart) 578 - `Release.Service`: The service that conducted the release. 579 - `Release.IsUpgrade`: This is set to true if the current operation is an upgrade or rollback. 580 - `Release.IsInstall`: This is set to true if the current operation is an 581 install. 582 - `Chart`: The contents of the `Chart.yaml`. Thus, the chart version is 583 obtainable as `Chart.Version` and the maintainers are in 584 `Chart.Maintainers`. 585 - `Files`: A map-like object containing all non-special files in the chart. This 586 will not give you access to templates, but will give you access to additional 587 files that are present (unless they are excluded using `.helmignore`). Files can be 588 accessed using `{{index .Files "file.name"}}` or using the `{{.Files.Get name}}` or 589 `{{.Files.GetString name}}` functions. You can also access the contents of the file 590 as `[]byte` using `{{.Files.GetBytes}}` 591 - `Capabilities`: A map-like object that contains information about the versions 592 of Kubernetes (`{{.Capabilities.KubeVersion}}` and the supported Kubernetes 593 API versions (`{{.Capabilities.APIVersions.Has "batch/v1"`) 594 595 **NOTE:** Any unknown Chart.yaml fields will be dropped. They will not 596 be accessible inside of the `Chart` object. Thus, Chart.yaml cannot be 597 used to pass arbitrarily structured data into the template. The values 598 file can be used for that, though. 599 600 ### Values files 601 602 Considering the template in the previous section, a `values.yaml` file 603 that supplies the necessary values would look like this: 604 605 ```yaml 606 imageRegistry: "quay.io/deis" 607 dockerTag: "latest" 608 pullPolicy: "Always" 609 storage: "s3" 610 ``` 611 612 A values file is formatted in YAML. A chart may include a default 613 `values.yaml` file. The Helm install command allows a user to override 614 values by supplying additional YAML values: 615 616 ```console 617 $ helm install --values=myvals.yaml wordpress 618 ``` 619 620 When values are passed in this way, they will be merged into the default 621 values file. For example, consider a `myvals.yaml` file that looks like 622 this: 623 624 ```yaml 625 storage: "gcs" 626 ``` 627 628 When this is merged with the `values.yaml` in the chart, the resulting 629 generated content will be: 630 631 ```yaml 632 imageRegistry: "quay.io/deis" 633 dockerTag: "latest" 634 pullPolicy: "Always" 635 storage: "gcs" 636 ``` 637 638 Note that only the last field was overridden. 639 640 **NOTE:** The default values file included inside of a chart _must_ be named 641 `values.yaml`. But files specified on the command line can be named 642 anything. 643 644 **NOTE:** If the `--set` flag is used on `helm install` or `helm upgrade`, those 645 values are simply converted to YAML on the client side. 646 647 **NOTE:** If any required entries in the values file exist, they can be declared 648 as required in the chart template by using the ['required' function](charts_tips_and_tricks.md) 649 650 Any of these values are then accessible inside of templates using the 651 `.Values` object: 652 653 ```yaml 654 apiVersion: v1 655 kind: ReplicationController 656 metadata: 657 name: deis-database 658 namespace: deis 659 labels: 660 app.kubernetes.io/managed-by: deis 661 spec: 662 replicas: 1 663 selector: 664 app.kubernetes.io/name: deis-database 665 template: 666 metadata: 667 labels: 668 app.kubernetes.io/name: deis-database 669 spec: 670 serviceAccount: deis-database 671 containers: 672 - name: deis-database 673 image: {{.Values.imageRegistry}}/postgres:{{.Values.dockerTag}} 674 imagePullPolicy: {{.Values.pullPolicy}} 675 ports: 676 - containerPort: 5432 677 env: 678 - name: DATABASE_STORAGE 679 value: {{default "minio" .Values.storage}} 680 681 ``` 682 683 ### Scope, Dependencies, and Values 684 685 Values files can declare values for the top-level chart, as well as for 686 any of the charts that are included in that chart's `charts/` directory. 687 Or, to phrase it differently, a values file can supply values to the 688 chart as well as to any of its dependencies. For example, the 689 demonstration WordPress chart above has both `mysql` and `apache` as 690 dependencies. The values file could supply values to all of these 691 components: 692 693 ```yaml 694 title: "My WordPress Site" # Sent to the WordPress template 695 696 mysql: 697 max_connections: 100 # Sent to MySQL 698 password: "secret" 699 700 apache: 701 port: 8080 # Passed to Apache 702 ``` 703 704 Charts at a higher level have access to all of the variables defined 705 beneath. So the WordPress chart can access the MySQL password as 706 `.Values.mysql.password`. But lower level charts cannot access things in 707 parent charts, so MySQL will not be able to access the `title` property. Nor, 708 for that matter, can it access `apache.port`. 709 710 Values are namespaced, but namespaces are pruned. So for the WordPress 711 chart, it can access the MySQL password field as `.Values.mysql.password`. But 712 for the MySQL chart, the scope of the values has been reduced and the 713 namespace prefix removed, so it will see the password field simply as 714 `.Values.password`. 715 716 #### Global Values 717 718 As of 2.0.0-Alpha.2, Helm supports special "global" value. Consider 719 this modified version of the previous example: 720 721 ```yaml 722 title: "My WordPress Site" # Sent to the WordPress template 723 724 global: 725 app: MyWordPress 726 727 mysql: 728 max_connections: 100 # Sent to MySQL 729 password: "secret" 730 731 apache: 732 port: 8080 # Passed to Apache 733 ``` 734 735 The above adds a `global` section with the value `app: MyWordPress`. 736 This value is available to _all_ charts as `.Values.global.app`. 737 738 For example, the `mysql` templates may access `app` as `{{.Values.global.app}}`, and 739 so can the `apache` chart. Effectively, the values file above is 740 regenerated like this: 741 742 ```yaml 743 title: "My WordPress Site" # Sent to the WordPress template 744 745 global: 746 app: MyWordPress 747 748 mysql: 749 global: 750 app: MyWordPress 751 max_connections: 100 # Sent to MySQL 752 password: "secret" 753 754 apache: 755 global: 756 app: MyWordPress 757 port: 8080 # Passed to Apache 758 ``` 759 760 This provides a way of sharing one top-level variable with all 761 subcharts, which is useful for things like setting `metadata` properties 762 like labels. 763 764 If a subchart declares a global variable, that global will be passed 765 _downward_ (to the subchart's subcharts), but not _upward_ to the parent 766 chart. There is no way for a subchart to influence the values of the 767 parent chart. 768 769 Also, global variables of parent charts take precedence over the global variables from subcharts. 770 771 ### Schema Files 772 773 Sometimes, a chart maintainer might want to define a structure on their values. 774 This can be done by defining a schema in the `values.schema.json` file. A 775 schema is represented as a [JSON Schema](https://json-schema.org/). 776 It might look something like this: 777 778 ```json 779 { 780 "$schema": "http://json-schema.org/draft-07/schema#", 781 "properties": { 782 "image": { 783 "description": "Container Image", 784 "properties": { 785 "repo": { 786 "type": "string" 787 }, 788 "tag": { 789 "type": "string" 790 } 791 }, 792 "type": "object" 793 }, 794 "name": { 795 "description": "Service name", 796 "type": "string" 797 }, 798 "port": { 799 "description": "Port", 800 "minimum": 0, 801 "type": "integer" 802 }, 803 "protocol": { 804 "type": "string" 805 } 806 }, 807 "required": [ 808 "protocol", 809 "port" 810 ], 811 "title": "Values", 812 "type": "object" 813 } 814 ``` 815 816 This schema will be applied to the values to validate it. Validation occurs 817 when any of the following commands are invoked: 818 819 * `helm install` 820 * `helm upgrade` 821 * `helm lint` 822 * `helm template` 823 824 An example of a 825 `values.yaml` file that meets the requirements of this schema might look 826 something like this: 827 828 ```yaml 829 name: frontend 830 protocol: https 831 port: 443 832 ``` 833 834 Note that the schema is applied to the final `.Values` object, and not just to 835 the `values.yaml` file. This means that the following `yaml` file is valid, 836 given that the chart is installed with the appropriate `--set` option shown 837 below. 838 839 ```yaml 840 name: frontend 841 protocol: https 842 ``` 843 844 ```` 845 helm install --set port=443 846 ```` 847 848 Furthermore, the final `.Values` object is checked against *all* subchart 849 schemas. This means that restrictions on a subchart can't be circumvented by a 850 parent chart. This also works backwards - if a subchart has a requirement that 851 is not met in the subchart's `values.yaml` file, the parent chart *must* 852 satisfy those restrictions in order to be valid. 853 854 ### References 855 856 When it comes to writing templates, values, and schema files, there are several 857 standard references that will help you out. 858 859 - [Go templates](https://godoc.org/text/template) 860 - [Extra template functions](https://godoc.org/github.com/Masterminds/sprig) 861 - [The YAML format](http://yaml.org/spec/) 862 - [JSON Schema](https://json-schema.org/) 863 864 ## Using Helm to Manage Charts 865 866 The `helm` tool has several commands for working with charts. 867 868 It can create a new chart for you: 869 870 ```console 871 $ helm create mychart 872 Created mychart/ 873 ``` 874 875 Once you have edited a chart, `helm` can package it into a chart archive 876 for you: 877 878 ```console 879 $ helm package mychart 880 Archived mychart-0.1.-.tgz 881 ``` 882 883 You can also use `helm` to help you find issues with your chart's 884 formatting or information: 885 886 ```console 887 $ helm lint mychart 888 No issues found 889 ``` 890 891 ## Chart Repositories 892 893 A _chart repository_ is an HTTP server that houses one or more packaged 894 charts. While `helm` can be used to manage local chart directories, when 895 it comes to sharing charts, the preferred mechanism is a chart 896 repository. 897 898 Any HTTP server that can serve YAML files and tar files and can answer 899 GET requests can be used as a repository server. 900 901 Helm comes with built-in package server for developer testing (`helm 902 serve`). The Helm team has tested other servers, including Google Cloud 903 Storage with website mode enabled, and S3 with website mode enabled. 904 905 A repository is characterized primarily by the presence of a special 906 file called `index.yaml` that has a list of all of the packages supplied 907 by the repository, together with metadata that allows retrieving and 908 verifying those packages. 909 910 On the client side, repositories are managed with the `helm repo` 911 commands. However, Helm does not provide tools for uploading charts to 912 remote repository servers. This is because doing so would add 913 substantial requirements to an implementing server, and thus raise the 914 barrier for setting up a repository. 915 916 ## Chart Starter Packs 917 918 The `helm create` command takes an optional `--starter` option that lets you 919 specify a "starter chart". 920 921 Starters are just regular charts, but are located in `$HELM_HOME/starters`. 922 As a chart developer, you may author charts that are specifically designed 923 to be used as starters. Such charts should be designed with the following 924 considerations in mind: 925 926 - The `Chart.yaml` will be overwritten by the generator. 927 - Users will expect to modify such a chart's contents, so documentation 928 should indicate how users can do so. 929 - All occurrences of `<CHARTNAME>` will be replaced with the specified chart 930 name so that starter charts can be used as templates. 931 932 Currently the only way to add a chart to `$HELM_HOME/starters` is to manually 933 copy it there. In your chart's documentation, you may want to explain that 934 process.