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.


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

  • Uses an unstructured repository. Automatic rendering isn't supported for hierarchical repositories.
  • RootSync and RepoSync APIs need to be enabled. If you installed Config Sync manually using kubectl, and don't have RootSync and RepoSync APIs enabled, you need to migrate your ConfigManagement object.
  • 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.
  • Ensure spec.override.enableShellInRendering is to true to let Config Sync support pulling remote bases from public repositories in the rendering process.
  • Include your configs in the kustomization.yaml. If you don't include these config files, the configs aren't synced to the cluster.

Bundled Helm and Kustomize versions

Config Sync leverages the Helm and Kustomize executables to render the configurations under the hood. The following table provides a list of Config Sync versions that support the rendering feature, alongside the bundled Helm and Kustomize versions.

Config Sync versions Helm version Kustomize version
1.15.0 and later v3.11.3 v5.0.1
1.11.0 to 1.14.3 v3.6.3 v4.5.2
From 1.9.0 to 1.10.2 v3.6.3 v4.3.0

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
├── 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
- 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

- ../base

- target:
   kind: RoleBinding
   name: team-admin-rolebinding
 patch: |-
   - op: replace
     path: /subjects/0/name
- 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
- 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 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:

# ./kustomization.yaml
- name: cert-manager
  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.

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

Render multiple Helm charts

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

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

# ./kustomization.yaml
- name: cert-manager
  releaseName: my-cert-manager
  namespace: cert-manager
- name: prometheus
  version: 14.3.0
  releaseName: my-prometheus
  namespace: monitoring

Supported fields

The following example shows you which fields are supported in your kustomization.yaml file:

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

What's next