Customize your Config Sync installation

With Config Sync, you can manage Kubernetes resources with configuration files stored in a source of truth. Config Sync supports Git repositories, OCI images, and Helm charts as a source of truth. This page shows you how to enable and configure Config Sync so that it syncs from your root repository.

When you install Config Sync using the Google Cloud console or the Google Cloud CLI, the RootSync and RepoSync APIs are enabled by default. This provides you with additional features such as syncing from multiple repositories and syncing Kustomize and Helm configurations.

Before you begin

Before you install Config Sync, prepare your source of truth and prepare an appropriate cluster.

Grant access to your source of truth

To synchronize configuration from a source of truth to your clusters, Config Sync requires read-only access to your repository. To authorize Config Sync to read your configurations, complete the following steps:

Create, or have access to, a source of truth that contains the configuration files that you want Config Sync to sync to your clusters. For more information, see the following resources:
- Add configs to a source of truth: conceptual information about configurations.
- GitOps best practices: tips and general best practices for organizing and managing your repository.
- Use an unstructured repo: recommendations for using and organizing an unstructured repository.
If your source of truth is public, no further action is needed. Config Sync doesn't require extra permissions.
If your source of truth is private, complete the instructions in one of the following pages:
- Grant Config Sync access to Git.
- Grant Config Sync access to OCI or Helm.

Review cluster requirements

Before you install Config Sync on your cluster, review cluster requirements.

Install Config Sync

In this section, you configure the settings for your root repository. If you're syncing to a Git repository, you can use the Google Cloud console to guide you through the installation process and automate some steps.

When you install Config Sync using the Google Cloud console or the Google Cloud CLI, Config Sync automatically creates a RootSync object named root-sync. You can use kubectl commands to modify root-sync and add additional Config Sync configurations. To learn more, see Configure Config Sync with kubectl commands.

Console

Install Config Sync

To install Config Sync, all clusters must be registered to a fleet. When you install Config Sync in the Google Cloud console, selecting individual clusters automatically registers those clusters to your fleet.

In the Google Cloud console, go to the Config page under the Features section.

Go to Config

Click Install Config Sync.
Select the Config Sync version that you want to use.
Under Installation options, select one of the following options:
- Install Config Sync on entire fleet (recommended): Config Sync will be installed on all clusters in the fleet.
- Install Config Sync on individual clusters: all selected clusters will be automatically registered to a fleet. Config Sync will be installed on all clusters in the fleet.
If you're installing Config Sync on individual clusters, in the Available clusters table, select the clusters on which you want to install Config Sync.
Click Install Config Sync. In the Settings tab, after a few minutes, you should see Enabled in the Status column for the clusters in your fleet.

Deploy a package

After you have registered your clusters to a fleet and installed Config Sync, you can configure Config Sync to deploy a package to a cluster from a source of truth. You can deploy the same package to multiple clusters or deploy different packages to different clusters. You can edit a package after deploying it, except for some settings like package name and sync type. For more information, see Manage packages.

To deploy a package, complete the following steps:

In the Google Cloud console, go to the Config Sync dashboard.

Go to Config Sync dashboard
Click Deploy Package.
In the Select clusters for package deployment table, select the cluster that you want to deploy a package to and then click Continue.
Select either Package hosted on Git or Package hosted on OCI as your source type and then click Continue.
In the Package details section, enter a Package name, which identifies the RootSync or RepoSync object.
In the Sync type field, choose either Cluster scoped sync or Namespace scoped sync as the sync type.

Cluster scoped sync creates a RootSync object and Namespace scoped sync creates a RepoSync object. For more information about these objects, see Config Sync architecture.
In the Source section, complete the following:
- For sources hosted in a Git repository, enter the following fields:
  1. Enter the URL of the Git repository that you're using as a source of truth as the Repository URL.
  2. Optional: Update the Revision field to check out if you're not using the default HEAD.
  3. Optional: Update the Path field if you don't want to sync from the root repository.
  4. Optional: Update the Branch field if you're not using the default main branch.
- For sources hosted in an OCI image, enter the following fields:
  1. Enter the URL of the OCI image that you're using as a source of truth as the Image.
  2. Enter the path of the directory to sync from, relative to the root directory, as the Directory.
(Optional): Expand the Advanced settings section to complete the following:
1. Select an Authentication type. Config Sync needs read-only access to your source of truth to read the configuration files in the source and apply them to your clusters. Unless your source requires no authentication, such as a public repository, ensure that you grant Config Sync read-only access to your Git repository, OCI image, or Helm chart (gcloud CLI only). Choose the same authentication type that you configured when you installed Config Sync:
  
  Note: for OCI, you can only select Workload Identity for authentication.
  - None: Use no authentication.
  - SSH: Authenticate by using an SSH key pair.
  - Cookiefile: Authenticate by using a cookiefile.
  - Token: Authenticate by using an access token or password.
  - Google Cloud Repository: Use a Google service account to access a Cloud Source Repositories repository. Only select this option if Workload Identity Federation for GKE is not enabled in your cluster.
  - Workload Identity: Use a Google service account to access a Cloud Source Repositories repository.
2. Enter a number in seconds to set the Sync wait time, which determines how long Config Sync waits between attempts to pull from the source of truth.
3. Enter a Git proxy URL for the HTTPS proxy to be used when communicating with the source of truth.
4. Choose Hierarchy to change the Source format.
  
  The default value Unstructured is recommended in most cases since it lets you organize your source of truth however you want.
Click Deploy Package.

You are redirected to the Config Sync Packages page. After a few minutes, you should see Synced in the Sync status column for the cluster that you configured.

gcloud

Before you continue, make sure you've registered your clusters to a fleet.

Enable the ConfigManagement fleet feature:

gcloud beta container fleet config-management enable

Prepare the configuration by either creating a new apply-spec.yaml manifest or by using an existing manifest. Using an existing manifest lets you configure your cluster with the same settings used by another cluster.
Create new manifest
To configure Config Sync with new settings for your cluster, create a file named apply-spec.yaml and copy the following YAML file into it.

You can set all of the optional spec.configSync fields that you need when you create your manifest, and later use kubectl commands for configuration. You can also only set the spec.configSync.enabled field as true and omit the optional fields. You can then later use kubectl commands to create additional RootSync objects or RepoSyncs that you can fully manage using kubectl commands later.
```
# apply-spec.yaml

applySpecVersion: 1
spec:
  configSync:
    enabled: true
    # If you don't have a source of truth yet, omit the
    # following fields. You can configure them later.
    sourceType: SOURCE_TYPE
    sourceFormat: FORMAT
    syncRepo: REPO
    syncRev: REVISION
    syncBranch: BRANCH
    secretType: SECRET_TYPE
    gcpServiceAccountEmail: EMAIL
    metricsGcpServiceAccountEmail: METRICS_EMAIL
    policyDir: DIRECTORY
    preventDrift: PREVENT_DRIFT
```
Replace the following:
- SOURCE_TYPE: add git to sync from a Git repository, oci to sync from an OCI image, or helm to sync from a Helm chart. If no value is specified, the default is git.
- FORMAT: add unstructured to use an unstructured repository or add hierarchy to use a hierarchical repository. These values are case-sensitive. This field is optional and the default value is hierarchy. We recommend that you add unstructured, because this format lets you organize your configs in the way that is most convenient to you.
- REPO: add the URL of the source of truth. Git and Helm repository URLs use either the HTTPS or SSH protocol. For example, https://github.com/GoogleCloudPlatform/anthos-config-management-samples. If you plan to use SSH as your secretType, enter your URL with the SSH protocol. This field is required and if you don't enter a protocol, the URL is treated as an HTTPS URL.
  
  OCI URLs use the following format: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME. By default, the image is pulled from the latest tag, but you can pull in images by TAG or DIGEST instead. Specify TAG or DIGEST in the PACKAGE_NAME:
  - To pull by TAG: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME:TAG
  - To pull by DIGEST: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME@sha256:DIGEST
  Caution: Config Sync requires that the OCI layer is compressed in the tar or tar+gzip format. Other formats (for example, tar+bz2) won't be recognized by Config Sync. Switching from a valid REPO to an OCI image with an unsupported format will cause managed resources to be pruned without an error.
- REVISION: the Git revision (tag or hash) or branch name to sync from. When using a hash, it must be a full hash, and not an abbreviated form.
- SECRET_TYPE: one of the following secretTypes:
  git
  
  none: Use no authentication.
  
  ssh: Use an SSH key pair.
  
  cookiefile: Use a cookiefile.
  
  token: Use a token.
  
  gcpserviceaccount: Use a Google service account to access a Cloud Source Repositories or Secure Source Manager repository. If you select this authentication type, you need to create an IAM policy binding after you finish configuring Config Sync. For details, see the Google service account tab of the Grant Config Sync access to Git with a Google service account section.
  
  gcenode: Use a Google service account to access a Cloud Source Repositories. Only select this option if Workload Identity Federation for GKE is not enabled in your cluster.
  
  githubapp: Use a GitHub App to authenticate to a GitHub repository.
  
  For more information on these authentication types, see Grant Config Sync access to Git.
  
  oci
  
  none: Use no authentication
  
  gcenode: Use the Compute Engine default service account to access an image in Artifact Registry. Only select this option if Workload Identity Federation for GKE is not enabled in your cluster.
  
  gcpserviceaccount: Use a Google service account to access an image.
  
  helm
  
  token: Use a token.
  
  gcenode: Use the Compute Engine default service account to access an image in Artifact Registry. Only select this option if Workload Identity Federation for GKE is not enabled in your cluster.
  
  gcpserviceaccount: Use a Google service account to access an image.
- EMAIL: If you added gcpserviceaccount as your secretType, add your Google service account email address. For example, acm@PROJECT_ID.iam.gserviceaccount.com.
- METRICS_EMAIL: the email of the Google Cloud Service Account (GSA) used for exporting Config Sync metrics to Cloud Monitoring. The GSA should have the Monitoring Metric Writer (roles/monitoring.metricWriter) IAM role. The Kubernetes ServiceAccount default in the namespace config-management-monitoring should be bound to the GSA.
- DIRECTORY: the path of the directory to sync from, relative to the root of the Git repository. All sub-directories of the directory that you specify are included and synced to the cluster. The default value is the root directory of the repository.
- PREVENT_DRIFT: If set to true, enables the Config Sync admission webhook to prevent drifts by rejecting conflicting changes from being pushed to live clusters. The default setting is false. Config Sync always remediates drifts no matter the value of this field.
For a complete list of fields that you can add to the spec field, see gcloud fields.

Note: If you don't have a source of truth prepared yet, you can enable Config Sync without configuring any settings by setting spec.configSync.enabled to true and omitting all other spec.configSync fields. When you have prepared your repository, edit your apply-spec.yaml to add the configuration settings.
Use existing manifest
To configure your cluster with the same settings used by another cluster, fetch the settings from a registered cluster:
```
gcloud alpha container fleet config-management fetch-for-apply \
    --membership=MEMBERSHIP_NAME \
    --project=PROJECT_ID \
    > CONFIG_YAML_PATH
```
Replace the following:
- MEMBERSHIP_NAME: the membership name of the registered cluster that has the Config Sync settings you want to use
- PROJECT_ID: your project ID
- CONFIG_YAML_PATH: the path to the apply-spec.yaml file which contains the settings fetched from the cluster
Apply the apply-spec.yaml file. If you are using an existing manifest, you should apply the file to the cluster that you want to configure with the settings that you fetched in the previous command:
```
gcloud beta container fleet config-management apply \
    --membership=MEMBERSHIP_NAME \
    --config=CONFIG_YAML_PATH \
    --project=PROJECT_ID
```
Replace the following:
- MEMBERSHIP_NAME: the fleet membership name that you chose when you registered your cluster. You can find the name with gcloud container fleet memberships list.
- CONFIG_YAML_PATH: the path to your apply-spec.yaml file.
- PROJECT_ID: your project ID.

Terraform

For each cluster that you want to configure Config Sync, apply a google_gkehub_feature_membership resource block that contains a configmanagement and config_sync block, such as in the following example:

git

data "google_project" "default" {}

resource "google_container_cluster" "default" {
  name     = "gke-autopilot-basic"
  location = "us-central1"

  fleet {
    project = data.google_project.default.project_id
  }

  enable_autopilot = true
}

resource "google_gke_hub_feature" "configmanagement_feature" {
  name     = "configmanagement"
  location = "global"
}

resource "google_gke_hub_feature_membership" "configmanagement_feature_member" {
  location = "global"

  feature             = google_gke_hub_feature.configmanagement_feature.name
  membership          = google_container_cluster.default.fleet[0].membership_id
  membership_location = google_container_cluster.default.fleet[0].membership_location

  configmanagement {
    config_sync {
      # The field `enabled` was introduced in Terraform version 5.41.0, and
      # needs to be set to `true` explicitly to install Config Sync.
      enabled = true
      git {
        sync_repo   = "REPO"
        sync_branch = "BRANCH"
        policy_dir  = "DIRECTORY"
        secret_type = "SECRET"
      }
    }
  }
}

Replace the following:

REPO: the URL to the Git repository that contains your configuration files.
BRANCH: the repository branch, for example main.
DIRECTORY: the path within the Git repository that represents the top level of the repository you want to sync.
SECRET: the secret auth type.

oci

data "google_project" "default" {}

resource "google_container_cluster" "default" {
  name     = "gke-autopilot-basic"
  location = "us-central1"

  fleet {
    project = data.google_project.default.project_id
  }

  enable_autopilot = true
}

resource "google_gke_hub_feature" "configmanagement_feature" {
  name     = "configmanagement"
  location = "global"
}

resource "google_gke_hub_feature_membership" "configmanagement_feature_member" {
  location = "global"

  feature             = google_gke_hub_feature.configmanagement_feature.name
  membership          = google_container_cluster.default.fleet[0].membership_id
  membership_location = google_container_cluster.default.fleet[0].membership_location

  configmanagement {
    config_sync {
      # The field `enabled` was introduced in Terraform version 5.41.0, and
      # needs to be set to `true` explicitly to install Config Sync.
      enabled = true
      oci {
        sync_repo   = "REPO"
        policy_dir  = "DIRECTORY"
        secret_type = "SECRET"
      }
    }
  }
}

Replace the following:

REPO: the URL to the OCI image repository that contains your configuration files.
DIRECTORY: the absolute path of the directory containing the resources you want to sync. To use the root directory, leave this field blank.
SECRET: the secret auth type.

Repeat this process for each cluster that you want to sync.

To learn more about using Terraform, see Terraform support for Config Sync.

After you have finished configuring your root repository, you can optionally choose to configure syncing from multiple repositories, including other root repositories and namespace repositories. The namespace repositories are helpful if you want a repository that contains namespace-scoped configs synced to a particular namespace across clusters.

Configure fleet-level defaults

You can enable and configure Config Sync as a fleet-level default for your clusters. This means that every new GKE on Google Cloud cluster created in the fleet will have Config Sync enabled on the cluster with the settings you specify. You can find out more about fleet default configuration in Manage fleet-level features.

If you use only the Google Cloud console, you can enable Config Sync by default on your clusters and set the Config Sync version for your fleet. If you use gcloud CLI or Terraform, you can enable Config Sync by default on your clusters, set the Config Sync version for your fleet, and set up the connection to your Git repository or OCI image repository.

To configure fleet-level defaults for Config Sync, complete the following steps:

gcloud

Run the enable command for the feature, passing the apply-spec.yaml configuration file that you created when you installed Config Sync in the previous section:

gcloud beta container fleet config-management enable \
    --fleet-default-member-config=apply-spec.yaml

You can use this command to update your fleet default settings at any time. If you update your fleet default settings, you must re-sync your existing clusters to the default settings.

Console

In the Google Cloud console, go to the Feature Manager page.

Go to Feature Manager
In the Config Sync pane, click Configure.
Review your fleet-level settings. All new clusters you create in the fleet inherit these settings.
Optional: To change the default settings, click Customize fleet settings. In the dialog that appears, do the following:
1. Select the Config Sync version that you want to use.
2. Click Save changes.
Click Configure.
In the Configuring fleet settings confirmation dialog, click Confirm. If you haven't previously enabled Config Sync, clicking Confirm also enables the anthosconfigmanagement.googleapis.com API.

Terraform

To enable Config Sync across a fleet, refer to the following example:

git

resource "google_gke_hub_feature" "default" {
  name     = "configmanagement"
  location = "global"

  fleet_default_member_config {
    configmanagement {
      config_sync {
        # The field `enabled` was introduced in Terraform version 5.41.0, and
        # needs to be set to `true` explicitly to install Config Sync.
        enabled = true
        git {
          sync_repo   = "REPO"
          sync_branch = "BRANCH"
          policy_dir  = "DIRECTORY"
          secret_type = "SECRET"
        }
      }
    }
  }
}

Replace the following:

REPO: the URL to the Git repository that contains your configuration files.
BRANCH: the repository branch, for example main.
DIRECTORY: the path within the Git repository that represents the top level of the repository you want to sync.
SECRET: the secret auth type.

oci

resource "google_gke_hub_feature" "configmanagement_feature_member" {
  name     = "configmanagement"
  location = "global"

  fleet_default_member_config {
    configmanagement {
      config_sync {
        # The field `enabled` was introduced in Terraform version 5.41.0, and
        # needs to be set to `true` explicitly to install Config Sync.
        enabled = true
        oci {
          sync_repo   = "REPO"
          policy_dir  = "DIRECTORY"
          secret_type = "SECRET"
        }
      }
    }
  }
}

Replace the following:

REPO: the URL to the OCI image repository that contains your configuration files.
DIRECTORY: the absolute path of the directory containing the resources you want to sync. To use the root directory, leave this field blank.
SECRET: the secret auth type.

To learn more about using Terraform, see Terraform support for Config Sync.

To update existing clusters to use your default Config Sync settings, you can use the Google Cloud console or gcloud CLI to sync selected fleet clusters to your fleet defaults. Alternatively, you can manually configure each cluster with the same settings using Terraform by following the instructions for installing Config Sync in the previous section. If you previously used Terraform to specify fleet defaults, use the same configmanagement and config_sync block that you used to set the defaults to configure your chosen clusters.

To sync Config Sync default settings across your fleet, follow these steps:

gcloud

Sync an existing membership to the fleet default configuration:
```
gcloud beta container fleet config-management apply \
    --origin=FLEET \
    --membership=MEMBERSHIP_NAME
```
Replace MEMBERSHIP_NAME with the fleet membership name of the cluster that you want to sync with the fleet default configuration.
Confirm that your membership configurations are synced with the fleet default:
```
gcloud beta container fleet config-management status
```
The output of this command should display as Yes for the Synced_to_Fleet_Default status for the membership that you synced.

console

Go to Feature Manager:

Go to Feature Manager: Config Sync
In the cluster table, select the clusters that you want to sync to fleet settings.
Click Sync to fleet settings.

To disable Config Sync default settings across your fleet, follow these steps:

To disable the fleet default configuration, run the following command:

gcloud beta container fleet config-management disable --fleet-default-member-config

Confirm that the fleet default configuration is disabled:

gcloud beta container fleet config-management status

The Config Sync default settings are applied to any clusters that you select. Although the Google Cloud console shows only a subset of settings, like the Config Sync version, all fleet-level settings are synced to the clusters. For example, if you configure Config Sync to sync to a a Git repository by using Terraform or the gcloud CLI, that setting is synced to your clusters, but is not shown in the Google Cloud console.

Verify the installation

After you have installed and configured Config Sync, you can verify that the installation completed successfully.

Console

Complete the following steps:

In the Google Cloud console, go to the Config page under the Features section.

Go to Config

On the Packages tab, check the Sync status column in the cluster table. A successful installation of Config Sync has a status of Installed. A successfully configured source of truth has a status of Synced.

gcloud

Run the following command:

gcloud beta container fleet config-management status \
    --project=PROJECT_ID

Replace PROJECT_ID with your project's ID.

A successful installation has a status of SYNCED with the Config Sync version installed.

If you see an error after running the preceding command, make sure that you created the git-creds Secret. If you have created the Secret, try rerunning the following command:

gcloud beta container fleet config-management apply

You can also use the nomos status command to check if the Config Sync is installed successfully. A valid installation with no problems has a status of PENDING or SYNCED. An invalid or incomplete installation has a status of NOT INSTALLED OR NOT CONFIGURED. The output also includes any reported errors.

Resource requests

The following section lists the resource requests for Config Sync.

The following table lists Kubernetes resource requirements for Config Sync components. For more information, see Managing Resources for Containers in the Kubernetes documentation.

Not all components listed are created. The following conditions cause each component to be scheduled:

config-management-operator is installed when Config Sync is enabled.
reconciler-manager is installed when Config Sync is enabled.
admission-webhook is installed when drift prevention is enabled.
a reconciler is installed for each RootSync and RepoSync.
otel-collector is installed when Config Sync is enabled.

To learn more about these components, see Config Sync architecture.

The resource requests are the same for all supported versions of Config Sync.

Deployment name	CPU request (m) per replica	Memory request (Mi) per replica
`config-management-operator`	100	200
`resource-group-controller-manager`	110	300
`admission-webhook¹`	10	100
`otel-collector`	200	400
`reconciler-manager`	20	150
`reconciler` (one per RootSync and RepoSync)	See reconciler deployment for details.

¹ The admission webhook has two replicas, so when calculating the total resource requests, you need to double the value if you are using the admission webhook. The admission webhook is disabled by default.

Reconciler deployment

For each RootSync and RepoSync object, Config Sync creates an independent reconciler deployment to handle syncing. The reconciler deployment consists of multiple containers. To learn more about these containers, see Reconciler containers.

Standard clusters

The resource requests are the same for all supported versions of Config Sync.

Container name	CPU request (m)	Memory request (Mi)
`reconciler`	50	200
`otel-agent`	10	100
`hydration-controller` (Optional)	10	100
`git-sync`	10	16
`gcenode-askpass-sidecar` (Optional)	10	20
`helm-sync`	75	128
`oci-sync`	25	32

Autopilot clusters

The resource requests are the same for all supported versions of Config Sync.

Container name	CPU request and limit (m)	Memory request and limit (Mi)
`reconciler`	700	512
`otel-agent`	10	64
`hydration-controller` (Optional)	200	256
`git-sync`	20	32
`gcenode-askpass-sidecar` (Optional)	50	64
`helm-sync`	250	384
`oci-sync`	50	64

To learn how to override the defaults resource requests and limits, see resource overrides.

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.22.0	v3.15.3	v5.3.0
1.21.0	v3.15.3	v5.3.0
1.20.0	v3.15.3	v5.3.0

For information about rendering Helm through Kustomize, see Configure Kubernetes with Kustomize. For information about using the Helm API, see Syncing Helm charts from Artifact Registry.

What's next

Learn how to upgrade Config Sync.
Learn more about the gcloud commands for configuring Config Sync.
Discover how to configure syncing from multiple repositories.
Use the nomos command.
Read the Introduction to troubleshooting Config Sync.
Learn how to uninstall Config Sync.
Review the Default Config Sync permissions.

Customize your Config Sync installation Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Grant access to your source of truth

Review cluster requirements

Install Config Sync

Console

Install Config Sync

Deploy a package

gcloud

Create new manifest

git

oci

helm

Use existing manifest

Terraform

git

oci

Configure fleet-level defaults

gcloud

Console

Terraform

git

oci

gcloud

console

Verify the installation

Console

gcloud

Resource requests

Reconciler deployment

Standard clusters

Autopilot clusters

Bundled Helm and Kustomize versions

What's next

Customize your Config Sync installation