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

     1  # Subcharts and Global Values
     2  
     3  To this point we have been working only with one chart. But charts can have dependencies, called _subcharts_, that also have their own values and templates. In this section we will create a subchart and see the different ways we can access values from within templates.
     4  
     5  Before we dive into the code, there are a few important details to learn about subcharts.
     6  
     7  1. A subchart is considered "stand-alone", which means a subchart can never explicitly depend on its parent chart.
     8  2. For that reason, a subchart cannot access the values of its parent.
     9  3. A parent chart can override values for subcharts.
    10  4. Helm has a concept of _global values_ that can be accessed by all charts.
    11  
    12  As we walk through the examples in this section, many of these concepts will become clearer.
    13  
    14  ## Creating a Subchart
    15  
    16  For these exercises, we'll start with the `mychart/` chart we created at the beginning of this guide, and we'll add a new chart inside of it.
    17  
    18  ```console
    19  $ cd mychart/charts
    20  $ helm create mysubchart
    21  Creating mysubchart
    22  $ rm -rf mysubchart/templates/*.*
    23  ```
    24  
    25  Notice that just as before, we deleted all of the base templates so that we can start from scratch. In this guide, we are focused on how templates work, not on managing dependencies. But the [Charts Guide](../charts.md) has more information on how subcharts work.
    26  
    27  ## Adding Values and a Template to the Subchart
    28  
    29  Next, let's create a simple template and values file for our `mysubchart` chart. There should already be a `values.yaml` in `mychart/charts/mysubchart`. We'll set it up like this:
    30  
    31  ```yaml
    32  dessert: cake
    33  ```
    34  
    35  Next, we'll create a new ConfigMap template in `mychart/charts/mysubchart/templates/configmap.yaml`:
    36  
    37  ```
    38  apiVersion: v1
    39  kind: ConfigMap
    40  metadata:
    41    name: {{ .Release.Name }}-cfgmap2
    42  data:
    43    dessert: {{ .Values.dessert }}
    44  ```
    45  
    46  Because every subchart is a _stand-alone chart_, we can test `mysubchart` on its own:
    47  
    48  ```console
    49  $ helm install --dry-run --debug mychart/charts/mysubchart
    50  SERVER: "localhost:44134"
    51  CHART PATH: /Users/mattbutcher/Code/Go/src/k8s.io/helm/_scratch/mychart/charts/mysubchart
    52  NAME:   newbie-elk
    53  TARGET NAMESPACE:   default
    54  CHART:  mysubchart 0.1.0
    55  MANIFEST:
    56  ---
    57  # Source: mysubchart/templates/configmap.yaml
    58  apiVersion: v1
    59  kind: ConfigMap
    60  metadata:
    61    name: newbie-elk-cfgmap2
    62  data:
    63    dessert: cake
    64  ```
    65  
    66  ## Overriding Values of a Child Chart
    67  
    68  Our original chart, `mychart` is now the _parent_ chart of `mysubchart`. This relationship is based entirely on the fact that `mysubchart` is within `mychart/charts`.
    69  
    70  Because `mychart` is a parent, we can specify configuration in `mychart` and have that configuration pushed into `mysubchart`. For example, we can modify `mychart/values.yaml` like this:
    71  
    72  ```yaml
    73  favorite:
    74    drink: coffee
    75    food: pizza
    76  pizzaToppings:
    77    - mushrooms
    78    - cheese
    79    - peppers
    80    - onions
    81  
    82  mysubchart:
    83    dessert: ice cream
    84  ```
    85  
    86  Note the last two lines. Any directives inside of the `mysubchart` section will be sent to the `mysubchart` chart. So if we run `helm install --dry-run --debug mychart`, one of the things we will see is the `mysubchart` ConfigMap:
    87  
    88  ```yaml
    89  # Source: mychart/charts/mysubchart/templates/configmap.yaml
    90  apiVersion: v1
    91  kind: ConfigMap
    92  metadata:
    93    name: unhinged-bee-cfgmap2
    94  data:
    95    dessert: ice cream
    96  ```
    97  
    98  The value at the top level has now overridden the value of the subchart.
    99  
   100  There's an important detail to notice here. We didn't change the template of `mychart/charts/mysubchart/templates/configmap.yaml` to point to `.Values.mysubchart.dessert`. From that template's perspective, the value is still located at `.Values.dessert`. As the template engine passes values along, it sets the scope. So for the `mysubchart` templates, only values specifically for `mysubchart` will be available in `.Values`.
   101  
   102  Sometimes, though, you do want certain values to be available to all of the templates. This is accomplished using global chart values.
   103  
   104  ## Global Chart Values
   105  
   106  Global values are values that can be accessed from any chart or subchart by exactly the same name. Globals require explicit declaration. You can't use an existing non-global as if it were a global.
   107  
   108  The Values data type has a reserved section called `Values.global` where global values can be set. Let's set one in our `mychart/values.yaml` file.
   109  
   110  ```yaml
   111  favorite:
   112    drink: coffee
   113    food: pizza
   114  pizzaToppings:
   115    - mushrooms
   116    - cheese
   117    - peppers
   118    - onions
   119  
   120  mysubchart:
   121    dessert: ice cream
   122  
   123  global:
   124    salad: caesar
   125  ```
   126  
   127  Because of the way globals work, both `mychart/templates/configmap.yaml` and `mychart/charts/mysubchart/templates/configmap.yaml` should be able to access that value as `{{ .Values.global.salad}}`.
   128  
   129  `mychart/templates/configmap.yaml`:
   130  
   131  ```yaml
   132  apiVersion: v1
   133  kind: ConfigMap
   134  metadata:
   135    name: {{ .Release.Name }}-configmap
   136  data:
   137    salad: {{ .Values.global.salad }}
   138  ```
   139  
   140  `mychart/charts/mysubchart/templates/configmap.yaml`:
   141  
   142  ```yaml
   143  apiVersion: v1
   144  kind: ConfigMap
   145  metadata:
   146    name: {{ .Release.Name }}-cfgmap2
   147  data:
   148    dessert: {{ .Values.dessert }}
   149    salad: {{ .Values.global.salad }}
   150  ```
   151  
   152  Now if we run a dry run install, we'll see the same value in both outputs:
   153  
   154  ```yaml
   155  # Source: mychart/templates/configmap.yaml
   156  apiVersion: v1
   157  kind: ConfigMap
   158  metadata:
   159    name: silly-snake-configmap
   160  data:
   161    salad: caesar
   162  
   163  ---
   164  # Source: mychart/charts/mysubchart/templates/configmap.yaml
   165  apiVersion: v1
   166  kind: ConfigMap
   167  metadata:
   168    name: silly-snake-cfgmap2
   169  data:
   170    dessert: ice cream
   171    salad: caesar
   172  ```
   173  
   174  Globals are useful for passing information like this, though it does take some planning to make sure the right templates are configured to use globals.
   175  
   176  ## Sharing Templates with Subcharts
   177  
   178  Parent charts and subcharts can share templates. Any defined block in any chart is
   179  available to other charts.
   180  
   181  For example, we can define a simple template like this:
   182  
   183  ```yaml
   184  {{- define "labels" }}from: mychart{{ end }}
   185  ```
   186  
   187  Recall how the labels on templates are _globally shared_. Thus, the `labels` chart
   188  can be included from any other chart.
   189  
   190  While chart developers have a choice between `include` and `template`, one advantage
   191  of using `include` is that `include` can dynamically reference templates:
   192  
   193  ```yaml
   194  {{ include $mytemplate }}
   195  ```
   196  
   197  The above will dereference `$mytemplate`. The `template` function, in contrast,
   198  will only accept a string literal.
   199  
   200  ## Avoid Using Blocks
   201  
   202  The Go template language provides a `block` keyword that allows developers to provide
   203  a default implementation which is overridden later. In Helm charts, blocks are not
   204  the best tool for overriding because if multiple implementations of the same block
   205  are provided, the one selected is unpredictable.
   206  
   207  The suggestion is to instead use `include`.