github.com/Beeketing/helm@v2.12.1+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 tuple "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 `tuple` 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  {{ range $path, $bytes := .Files.Glob "foo/*" }}
   133  {{ base $path }}: '{{ $root.Files.Get $path | b64enc }}'
   134  {{ end }}
   135  ```
   136  
   137  ## ConfigMap and Secrets utility functions
   138  
   139  (Not present in version 2.0.2 or prior)
   140  
   141  It is very common to want to place file content into both configmaps and
   142  secrets, for mounting into your pods at run time. To help with this, we provide a
   143  couple utility methods on the `Files` type.
   144  
   145  For further organization, it is especially useful to use these methods in
   146  conjunction with the `Glob` method.
   147  
   148  Given the directory structure from the [Glob](#glob-patterns) example above:
   149  
   150  ```yaml
   151  apiVersion: v1
   152  kind: ConfigMap
   153  metadata:
   154    name: conf
   155  data:
   156    {{- (.Files.Glob "foo/*").AsConfig | nindent 2 }}
   157  ---
   158  apiVersion: v1
   159  kind: Secret
   160  metadata:
   161    name: very-secret
   162  type: Opaque
   163  data:
   164    {{- (.Files.Glob "bar/*").AsSecrets | nindent 2 }}
   165  ```
   166  
   167  ## Encoding
   168  
   169  You can import a file and have the template base-64 encode it to ensure successful transmission:
   170  
   171  ```yaml
   172  apiVersion: v1
   173  kind: Secret
   174  metadata:
   175    name: {{ .Release.Name }}-secret
   176  type: Opaque
   177  data:
   178    token: |-
   179      {{ .Files.Get "config1.toml" | b64enc }}
   180  ```
   181  
   182  The above will take the same `config1.toml` file we used before and encode it:
   183  
   184  ```yaml
   185  # Source: mychart/templates/secret.yaml
   186  apiVersion: v1
   187  kind: Secret
   188  metadata:
   189    name: lucky-turkey-secret
   190  type: Opaque
   191  data:
   192    token: |-
   193      bWVzc2FnZSA9IEhlbGxvIGZyb20gY29uZmlnIDEK
   194  ```
   195  
   196  ## Lines
   197  
   198  Sometimes it is desirable to access each line of a file in your template. We
   199  provide a convenient `Lines` method for this.
   200  
   201  ```yaml
   202  data:
   203    some-file.txt: {{ range .Files.Lines "foo/bar.txt" }}
   204      {{ . }}{{ end }}
   205  ```
   206  
   207  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`.
   208  
   209  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.