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.

Note: Config Sync supports all of the native Kustomize configurations with the exception of custom Kustomize plugins. Kustomize plugins are not supported due to security concerns.

Requirements

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.

Note: Config Sync does not support remote bases from private repositories.

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
├── 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: [e-mail]
- 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:

# ./kustomization.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.

# ./kustomization.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 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
...
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
...

Supported fields

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

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

• Take a tutorial showing you how to use Config Sync with Kustomize and Helm.