Config Sync overview

Config Sync allows cluster operators to manage single clusters, multi-tenant clusters, and multi-cluster Kubernetes deployments using files, called configs, stored in a Git repository.

Some configs are Kubernetes object manifests. Other configs are not object manifests, but instead provide information needed by Config Sync itself. You can write configs in YAML or JSON. Config Sync watches for updates to these files and applies changes to all relevant clusters automatically.

A configuration-as-code approach allows you to manage the configuration of your Google Kubernetes Engine clusters using the same principles you may already be using to manage your applications deployed in Kubernetes. With Config Sync, you can:

  • Require code reviews before changes are pushed to the live environment, and audit exactly which commit caused a configuration change.
  • Reduce the risk of "shadow ops", where unvetted changes are pushed to live clusters and it is difficult to understand the differences between documented configuration and your live environment. You can require that all cluster configuration changes are propagated using Config Sync and lock down direct access to the Kubernetes API.
  • Apply configuration changes to hundreds of clusters with a single Git commit, instead of writing scripts to run thousands of kubectl apply commands manually.
  • Ensure that a change is pushed to each relevant cluster, and only relevant clusters, based on metadata applied to each cluster.
  • Use Continuous Integration / Continuous Deployment (CI/CD) pipelines to test your changes and apply them automatically when tests pass.
  • Use a "revert then investigate" strategy to roll back breaking changes and get your live clusters back into a good working state before fixing the problematic change and applying it as a new commit. This strategy reduces downtime due to configuration-related outages.

Config Sync synchronizes the states of your clusters with your Git repository. The Config Sync Operator custom controller monitors your Git repository and the states of your clusters, keeping them consistent for each Kubernetes object you choose. If Config Sync Operator fails to apply changes to a resource, the resource is left in the last known good state.

Config Sync can configure a single cluster or multiple clusters from a single Git repository.


Config Sync uses namespaces, labels, and annotations as core parts of its implementation, and a good understanding of these concepts is helpful before you get started.

Before you write a config, you need to understand the required and optional fields allowed for that Kubernetes object.

In addition, Config Sync introduces some new terminology and concepts. These are discussed briefly in Config Sync concepts, along with links to more information about each concept.

New concepts

The following new concepts are central to Config Sync.


A config is a Kubernetes configuration declaration, written in YAML or JSON, that Config Sync reads and applies to one or more clusters to create or configure a Kubernetes object or resource in those clusters. Configs are stored in a Git repository (see also the definition for Repo). A config can contain any configuration detail you could apply to a Kubernetes cluster using kubectl edit or kubectl apply. You can even configure custom Resources that already exist on the cluster. Multiple configs can be defined in a single file.

For more information, see Creating configs.


The repo is the Git repository where configs are stored, including the config for Config Sync itself. All configs must be stored in the same repo. When you configure Config Sync, you configure the repo, the branch, and the subdirectory that Config Sync monitors for changes.

The structure of the repo is important, and is discussed further in Using the repo.

Abstract namespace directory

Config Sync provides a mechanism called abstract namespaces, which allow you to apply policies to multiple related namespaces, without duplicating configs, and with the ability to override or extend a config for a given namespace or set of namespaces. Abstract namespaces work using a filesystem-style hierarchy in the repo.

In the repo, the directory structure of the namespaces/ subdirectory determines which policies apply to a namespace, using a mechanism similar to a file system tree. Namespaces can be nested into subdirectories, called abstract namespace directories.

For more information, see Namespace inheritance overview.

Viewing and verifying files

Config Sync provides an API. The nomos and nomos.exe commands consume the API and simplify the process of setting up the repo and validating configs.

For more information, see Using the nomos command.

What's next?