From 73dc31b248ff7c49ffcc4daf94d1f6ed1344d872 Mon Sep 17 00:00:00 2001 From: Geoff Baskwill Date: Sun, 11 Nov 2018 19:03:49 -0500 Subject: [PATCH] docs: markdown prettyprinting Signed-off-by: Geoff Baskwill --- docs/chart_template_guide/accessing_files.md | 11 +++--- docs/chart_template_guide/named_templates.md | 8 ++--- docs/charts_tips_and_tricks.md | 35 ++++++++++++-------- 3 files changed, 30 insertions(+), 24 deletions(-) diff --git a/docs/chart_template_guide/accessing_files.md b/docs/chart_template_guide/accessing_files.md index c959002b7..6fb63ffc1 100644 --- a/docs/chart_template_guide/accessing_files.md +++ b/docs/chart_template_guide/accessing_files.md @@ -6,8 +6,8 @@ Helm provides access to files through the `.Files` object. Before we get going w - It is okay to add extra files to your Helm chart. These files will be bundled and sent to Tiller. Be careful, though. Charts must be smaller than 1M because of the storage limitations of Kubernetes objects. - Some files cannot be accessed through the `.Files` object, usually for security reasons. - - Files in `templates/` cannot be accessed. - - Files excluded using `.helmignore` cannot be accessed. + - Files in `templates/` cannot be accessed. + - Files excluded using `.helmignore` cannot be accessed. - Charts do not preserve UNIX mode information, so file-level permissions will have no impact on the availability of a file when it comes to the `.Files` object. @@ -90,6 +90,7 @@ use. They are all accessible with the same names as in the Go package, but with a lowercase first letter. For example, `Base` becomes `base`, etc. The imported functions are: + - Base - Dir - Ext @@ -107,8 +108,8 @@ the returned object. For example, imagine the directory structure: -``` -foo/: +```txt +foo/: foo.txt foo.yaml bar/: @@ -117,7 +118,6 @@ bar/: You have multiple options with Globs: - ```yaml {{ $root := . }} {{ range $path, $bytes := .Files.Glob "**.yaml" }} @@ -207,4 +207,3 @@ data: Currently, there is no way to pass files external to the chart during `helm install`. So if you are asking users to supply data, it must be loaded using `helm install -f` or `helm install --set`. This discussion wraps up our dive into the tools and techniques for writing Helm templates. In the next section we will see how you can use one special file, `templates/NOTES.txt`, to send post-installation instructions to the users of your chart. - diff --git a/docs/chart_template_guide/named_templates.md b/docs/chart_template_guide/named_templates.md index 33425d102..4f8f9f59c 100644 --- a/docs/chart_template_guide/named_templates.md +++ b/docs/chart_template_guide/named_templates.md @@ -14,9 +14,9 @@ So far, we've used one file, and that one file has contained a single template. Before we get to the nuts-and-bolts of writing those templates, there is file naming convention that deserves mention: -* Most files in `templates/` are treated as if they contain Kubernetes manifests -* The `NOTES.txt` is one exception -* But files whose name begins with an underscore (`_`) are assumed to _not_ have a manifest inside. These files are not rendered to Kubernetes object definitions, but are available everywhere within other chart templates for use. +- Most files in `templates/` are treated as if they contain Kubernetes manifests +- The `NOTES.txt` is one exception +- But files whose name begins with an underscore (`_`) are assumed to _not_ have a manifest inside. These files are not rendered to Kubernetes object definitions, but are available everywhere within other chart templates for use. These files are used to store partials and helpers. In fact, when we first created `mychart`, we saw a file called `_helpers.tpl`. That file is the default location for template partials. @@ -139,7 +139,7 @@ metadata: What happened to the name and version? They weren't in the scope for our defined template. When a named template (created with `define`) is rendered, it will receive the scope passed in by the `template` call. In our example, we included the template like this: -```yaml +```gotpl {{- template "mychart.labels" }} ``` diff --git a/docs/charts_tips_and_tricks.md b/docs/charts_tips_and_tricks.md index f1751b1b5..6cab5c423 100644 --- a/docs/charts_tips_and_tricks.md +++ b/docs/charts_tips_and_tricks.md @@ -22,18 +22,18 @@ For example, this template snippet includes a template called `mytpl`, then lowercases the result, then wraps that in double quotes. ```yaml -value: {{include "mytpl" . | lower | quote}} +value: {{ include "mytpl" . | lower | quote }} ``` The `required` function allows you to declare a particular -values entry as required for template rendering. If the value is empty, the template +values entry as required for template rendering. If the value is empty, the template rendering will fail with a user submitted error message. The following example of the `required` function declares an entry for .Values.who is required, and will print an error message when that entry is missing: ```yaml -value: {{required "A valid .Values.who entry required!" .Values.who }} +value: {{ required "A valid .Values.who entry required!" .Values.who }} ``` ## Quote Strings, Don't Quote Integers @@ -41,20 +41,20 @@ value: {{required "A valid .Values.who entry required!" .Values.who }} When you are working with string data, you are always safer quoting the strings than leaving them as bare words: -``` -name: {{.Values.MyName | quote }} +```yaml +name: {{ .Values.MyName | quote }} ``` But when working with integers _do not quote the values._ That can, in many cases, cause parsing errors inside of Kubernetes. -``` +```yaml port: {{ .Values.Port }} ``` This remark does not apply to env variables values which are expected to be string, even if they represent integers: -``` +```yaml env: -name: HOST value: "http://host" @@ -99,7 +99,7 @@ developer. For example: -``` +```gotpl {{ required "A valid foo is required!" .Values.foo }} ``` @@ -113,7 +113,8 @@ This is useful to pass a template string as a value to a chart or render externa Syntax: `{{ tpl TEMPLATE_STRING VALUES }}` Examples: -``` + +```yaml # values template: "{{ .Values.name }}" name: "Tom" @@ -126,7 +127,8 @@ Tom ``` Rendering a external configuration file: -``` + +```yaml # external configuration file conf/app.conf firstName={{ .Values.firstName }} lastName={{ .Values.lastName }} @@ -144,10 +146,12 @@ lastName=Parker ``` ## Creating Image Pull Secrets -Image pull secrets are essentially a combination of _registry_, _username_, and _password_. You may need them in an application you are deploying, but to create them requires running _base64_ a couple of times. We can write a helper template to compose the Docker configuration file for use as the Secret's payload. Here is an example: + +Image pull secrets are essentially a combination of _registry_, _username_, and _password_. You may need them in an application you are deploying, but to create them requires running _base64_ a couple of times. We can write a helper template to compose the Docker configuration file for use as the Secret's payload. Here is an example: First, assume that the credentials are defined in the `values.yaml` file like so: -``` + +```yaml imageCredentials: registry: quay.io username: someone @@ -155,14 +159,16 @@ imageCredentials: ``` We then define our helper template as follows: -``` + +```gotpl {{- define "imagePullSecret" }} {{- printf "{\"auths\": {\"%s\": {\"auth\": \"%s\"}}}" .Values.imageCredentials.registry (printf "%s:%s" .Values.imageCredentials.username .Values.imageCredentials.password | b64enc) | b64enc }} {{- end }} ``` Finally, we use the helper template in a larger template to create the Secret manifest: -``` + +```yaml apiVersion: v1 kind: Secret metadata: @@ -282,6 +288,7 @@ update of that resource. ## Upgrade a release idempotently In order to use the same command when installing and upgrading a release, use the following command: + ```shell helm upgrade --install --values ```