github.com/koderover/helm@v2.17.0+incompatible/docs/chart_template_guide/accessing_files.md (about)

     1  # Accessing Files Inside Templates
     2  
     3  In the previous section we looked at several ways to create and access named templates. This makes it easy to import one template from within another template. But sometimes it is desirable to import a _file that is not a template_ and inject its contents without sending the contents through the template renderer.
     4  
     5  Helm provides access to files through the `.Files` object. Before we get going with the template examples, though, there are a few things to note about how this works:
     6  
     7  - 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.
     8  - Some files cannot be accessed through the `.Files` object, usually for security reasons.
     9    - Files in `templates/` cannot be accessed.
    10    - Files excluded using `.helmignore` cannot be accessed.
    11  - 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.
    12  
    13  <!-- (see https://github.com/jonschlinkert/markdown-toc) -->
    14  
    15  <!-- toc -->
    16  
    17  - [Basic example](#basic-example)
    18  - [Path helpers](#path-helpers)
    19  - [Glob patterns](#glob-patterns)
    20  - [ConfigMap and Secrets utility functions](#configmap-and-secrets-utility-functions)
    21  - [Encoding](#encoding)
    22  - [Lines](#lines)
    23  
    24  <!-- tocstop -->
    25  
    26  ## Basic example
    27  
    28  With those caveats behind, let's write a template that reads three files into our ConfigMap. To get started, we will add three files to the chart, putting all three directly inside of the `mychart/` directory.
    29  
    30  `config1.toml`:
    31  
    32  ```toml
    33  message = "Hello from config 1"
    34  ```
    35  
    36  `config2.toml`:
    37  
    38  ```toml
    39  message = "This is config 2"
    40  ```
    41  
    42  `config3.toml`:
    43  
    44  ```toml
    45  message = "Goodbye from config 3"
    46  ```
    47  
    48  Each of these is a simple TOML file (think old-school Windows INI files). We know the names of these files, so we can use a `range` function to loop through them and inject their contents into our ConfigMap.
    49  
    50  ```yaml
    51  apiVersion: v1
    52  kind: ConfigMap
    53  metadata:
    54    name: {{ .Release.Name }}-configmap
    55  data:
    56    {{- $files := .Files }}
    57    {{- range list "config1.toml" "config2.toml" "config3.toml" }}
    58    {{ . }}: |-
    59      {{ $files.Get . }}
    60    {{- end }}
    61  ```
    62  
    63  This config map uses several of the techniques discussed in previous sections. For example, we create a `$files` variable to hold a reference to the `.Files` object. We also use the `list` function to create a list of files that we loop through. Then we print each file name (`{{.}}: |-`) followed by the contents of the file `{{ $files.Get . }}`.
    64  
    65  Running this template will produce a single ConfigMap with the contents of all three files:
    66  
    67  ```yaml
    68  # Source: mychart/templates/configmap.yaml
    69  apiVersion: v1
    70  kind: ConfigMap
    71  metadata:
    72    name: quieting-giraf-configmap
    73  data:
    74    config1.toml: |-
    75      message = "Hello from config 1"
    76  
    77    config2.toml: |-
    78      message = "This is config 2"
    79  
    80    config3.toml: |-
    81      message = "Goodbye from config 3"
    82  ```
    83  
    84  ## Path helpers
    85  
    86  When working with files, it can be very useful to perform some standard
    87  operations on the file paths themselves. To help with this, Helm imports many of
    88  the functions from Go's [path](https://golang.org/pkg/path/) package for your
    89  use. They are all accessible with the same names as in the Go package, but
    90  with a lowercase first letter. For example, `Base` becomes `base`, etc.
    91  
    92  The imported functions are:
    93  
    94  - Base
    95  - Dir
    96  - Ext
    97  - IsAbs
    98  - Clean
    99  
   100  ## Glob patterns
   101  
   102  As your chart grows, you may find you have a greater need to organize your
   103  files more, and so we provide a `Files.Glob(pattern string)` method to assist
   104  in extracting certain files with all the flexibility of [glob patterns](https://godoc.org/github.com/gobwas/glob).
   105  
   106  `.Glob` returns a `Files` type, so you may call any of the `Files` methods on
   107  the returned object.
   108  
   109  For example, imagine the directory structure:
   110  
   111  ```txt
   112  foo/:
   113    foo.txt foo.yaml
   114  
   115  bar/:
   116    bar.go bar.conf baz.yaml
   117  ```
   118  
   119  You have multiple options with Globs:
   120  
   121  ```yaml
   122  {{ $root := . }}
   123  {{ range $path, $bytes := .Files.Glob "**.yaml" }}
   124  {{ $path }}: |-
   125  {{ $root.Files.Get $path }}
   126  {{ end }}
   127  ```
   128  
   129  Or
   130  
   131  ```yaml
   132  {{ $root := . }}
   133  {{ range $path, $bytes := .Files.Glob "foo/*" }}
   134  {{ base $path }}: '{{ $root.Files.Get $path | b64enc }}'
   135  {{ end }}
   136  ```
   137  
   138  ## ConfigMap and Secrets utility functions
   139  
   140  (Not present in version 2.0.2 or prior)
   141  
   142  It is very common to want to place file content into both configmaps and
   143  secrets, for mounting into your pods at run time. To help with this, we provide a
   144  couple utility methods on the `Files` type.
   145  
   146  For further organization, it is especially useful to use these methods in
   147  conjunction with the `Glob` method.
   148  
   149  Given the directory structure from the [Glob](#glob-patterns) example above:
   150  
   151  ```yaml
   152  apiVersion: v1
   153  kind: ConfigMap
   154  metadata:
   155    name: conf
   156  data:
   157    {{- (.Files.Glob "foo/*").AsConfig | nindent 2 }}
   158  ---
   159  apiVersion: v1
   160  kind: Secret
   161  metadata:
   162    name: very-secret
   163  type: Opaque
   164  data:
   165    {{- (.Files.Glob "bar/*").AsSecrets | nindent 2 }}
   166  ```
   167  
   168  ## Encoding
   169  
   170  You can import a file and have the template base-64 encode it to ensure successful transmission:
   171  
   172  ```yaml
   173  apiVersion: v1
   174  kind: Secret
   175  metadata:
   176    name: {{ .Release.Name }}-secret
   177  type: Opaque
   178  data:
   179    token: |-
   180      {{ .Files.Get "config1.toml" | b64enc }}
   181  ```
   182  
   183  The above will take the same `config1.toml` file we used before and encode it:
   184  
   185  ```yaml
   186  # Source: mychart/templates/secret.yaml
   187  apiVersion: v1
   188  kind: Secret
   189  metadata:
   190    name: lucky-turkey-secret
   191  type: Opaque
   192  data:
   193    token: |-
   194      bWVzc2FnZSA9IEhlbGxvIGZyb20gY29uZmlnIDEK
   195  ```
   196  
   197  ## Lines
   198  
   199  Sometimes it is desirable to access each line of a file in your template. We
   200  provide a convenient `Lines` method for this.
   201  
   202  ```yaml
   203  data:
   204    some-file.txt: {{ range .Files.Lines "foo/bar.txt" }}
   205      {{ . }}{{ end }}
   206  ```
   207  
   208  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`.
   209  
   210  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.