Use a repo with Kustomize configurations and Helm charts

When you use Config Sync, the Kustomize configurations and Helm charts you place in your Git repository are automatically rendered. Automated rendering provides you with the following benefits:

  • You no longer need an external hydration pipeline. Without automated rendering, you have to manually render the configurations using Kustomize and Helm on your workstation, or set up a step to trigger the hydration process in your CI systems. With automated rendering, Config Sync handles the execution.

  • Your maintenance costs are reduced. Without automated rendering, you have to maintain one Git repository with the original Kustomize configurations and Helm charts and another Git repository with the output generated by the external hydration. You then have to configure Config Sync to sync from the Git repository with the rendered output. With automated rendering, you only need to maintain one repository with the original configs.

  • Your development workflow is simplified. Without automated rendering, changes made to your original configs need to be reviewed twice before being merged; once in the original repository and again in the rendered repository. With automated rendering, the rendered configs are generated by Config Sync, and you only need to review the changes to the original configs.

Requirements

To automatically render Kustomize configurations and Helm charts, make sure your environment meets the following requirements:

  • Has a Anthos Config Management version of 1.9.0 or later. If needed, Upgrade Anthos Config Management.
  • Has multi-repo mode enabled. If you used the Google Cloud Console or the gcloud command-line tool to install Config Sync, multi-repo mode is enabled by default in versions of 1.7.0 and later.
  • To trigger the rendering process, your Git repository must have a Kustomization config file (kustomization.yaml, kustomization.yml, or Kustomization) in the root of your Git directory. If the root directory doesn't have a Kustomization config file, Config Sync syncs the configs as-is without any rendering.
  • Include your configs in the kustomization.yaml. If you don't include these config files, the configs aren't synced to the cluster.

Example repository architecture for Kustomize configurations

The following example repository demonstrates how you might set up your repository to use Kustomize configurations with automatic rendering. This repository includes three overlays (team-a, team-b, and team-c) that reference the same base.

The following diagram shows you the directory structure:

├── base
│   ├── kustomization.yaml
│   ├── namespace.yaml
│   ├── networkpolicy.yaml
│   ├── rolebinding.yaml
│   └── role.yaml
├── kustomization.yaml
├── README.md
├── team-a
│   └── kustomization.yaml
├── team-b
│   └── kustomization.yaml
└── team-c
    └── kustomization.yaml

The following kustomization.yaml file is in the root of the repository and it contains references the three overlays:

# ./kustomization.yaml
resources:
- team-a
- team-b
- team-c

The following kustomize.yaml is in the team-a directory and is the overlay for team-a:

# ./team-a/kustomization.yaml
namespace: team-a

resources:
- ../base

patches:
- target:
   kind: RoleBinding
   name: team-admin-rolebinding
 patch: |-
   - op: replace
     path: /subjects/0/name
     value: team-a-admin@mydomain.com
- target:
   kind: Namespace
   name: default
 patch: |-
   - op: replace
     path: /metadata/name
     value: team-a

The following kustomization.yaml is in the base directory and is the Kustomize base:

# ./base/kustomization.yaml
resources:
- namespace.yaml
- rolebinding.yaml
- role.yaml
- networkpolicy.yaml

You can explore this repository in the Configuring namespace specific policies directory of the Anthos Config Management sample repository.

Automatically render Helm charts

You can automatically render Helm charts by using the helmGlobals and helmCharts fields in your kustomization.yaml files.

Helm chart fields

Config Sync supports adding the following fields to your kustomization.yaml files:

Field Description
helmGlobals Parameters applied to all Helm charts
helmGlobals.chartHome Accepts a string. A file path, relative to the Kustomization root, to a directory containing a subdirectory for each chart to be included in the Kustomization. The default value of this field is charts.
helmGlobals.configHome Accepts a string. Defines a value that Kustomize should pass to Helm with the HELM_CONFIG_HOME environment variable. Kustomize doesn't attempt to read or write this directory. If omitted, TMP_DIR/helm is used, where TMP_DIR is a temporary directory created by Kustomize for Helm.
helmCharts An array of Helm chart parameters
helmCharts.name Accepts a string. The name of the chart. This field is required.
helmCharts.version Accepts a string. The version of the chart
helmCharts.repo Accepts a string. The URL used to locate the chart
helmCharts.releaseName Accepts a string. Replaces RELEASE_NAME in the chart template output
helmCharts.namespace Accepts a string. Sets the target namespace for a release (.Release.Namespace in the template)
helmCharts.valuesInline Values to use instead of default values that accompany the chart
helmCharts.valuesFile Accepts a string. ValuesFile is a local file path or a remote URL to a values file to use instead of the default values that accompanied the chart. The default values are in CHART_HOME/NAME/values.yaml.
helmCharts.valuesMerge Accepts merge, override, (default), or replace. ValuesMerge specifies how to treat ValuesInline with respect to Values.
helmCharts.includeCRDs Accepts true or false. Specifies if Helm should also generate CustomResourceDefinitions. The default value is false.

Helm chart examples

The examples in the following sections show you some of the different ways that you can utilize Helm charts.

Render a remote Helm chart

Config Sync supports rendering remote Helm charts on clusters that have public internet access.

The following kustomization.yaml renders a remote cert-manager by setting the following helmCharts fields:

# ./kustomizaiton.yaml
...
helmCharts:
- name: cert-manager
  repo: https://charts.jetstack.io
  version: v1.5.3
  releaseName: my-cert-manager
  namespace: cert-manager
...

Render a local Helm chart

Config Sync supports rendering local Helm charts. To use a customized version of a Helm chart, you can pull the released version from the Helm chart repository (for example, ArtifactHub), make changes locally, and then push the changes to your repository.

The following kustomization.yaml renders a local cert-manager chart. The default directory for Helm charts is charts and since this chart is checked into the charts directory, you don't need to specify .helmCharts.repo or .helmCharts.version.

# ./kustomizaiton.yaml
...
helmCharts:
- name: cert-manager
  releaseName: my-cert-manager
  namespace: cert-manager
...

Render multiple Helm charts

Config Sync supports rendering multiple Helm charts in one kustomiztion.yaml file, regardless of whether the chart is remote or local.

The following kustomization.yaml renders a local Helm chart (cert-manager):

# ./kustomizaiton.yaml
...
helmCharts:
- name: cert-manager
  releaseName: my-cert-manager
  namespace: cert-manager
- name: prometheus
  repo: https://prometheus-community.github.io/helm-charts
  version: 14.3.0
  releaseName: my-prometheus
  namespace: monitoring
...

Example format

The following example shows you

helmGlobals:
  chartHome: string
  configHome: string
helmCharts:
- name: string
  version: string
  repo: string
  releaseName: string
  namespace: string
  valuesInline: map[string]interface{}
  valuesFile: string
  valuesMerge: string
  includeCRDs: bool

What's next