Repo overview

This page describes how Config Sync reads configs from a structured Git repository called the repo and applies the resulting configuration to your clusters automatically.

If you want more structural flexibility (for example, you want to create subfolders of resources) you can create a repo that does not follow this structure. For more information, see Creating an unstructured repo.


  • Be familiar with Git repositories and the git command-line interface.
  • Be familiar with the Kubernetes objects you want to configure and their required and optional fields.

Structure of the repo

Config Sync takes advantage of Git's filesystem-like structure, and uses it to determine which clusters or namespaces a config is relevant to.


The namespaces/ directory contains configs for namespaces and namespace-scoped objects. The structure within namespaces/ is the mechanism that drives namespace inheritance. You can limit which namespaces can inherit a config, by using a NamespaceSelector.


The cluster/ directory contains configs that apply to entire clusters, rather than to namespaces. By default, any config in the cluster/ directory applies to every cluster enrolled in Config Sync. You can limit which clusters a config can affect by using a ClusterSelector.


The clusterregistry/ directory is optional, and contains configs for ClusterSelectors. ClusterSelectors limit which clusters a config applies to, and are referenced in configs found in the cluster/ and namespaces/ directories.


The system/ directory contains configs for the Operator. See Installing Config Sync for more information on configuring Config Sync.

Example repo

The example repo illustrates the structure of a repo.

Notice the nested abstract namespace directories online/ and shipping-app-backend/ within namespaces/. They are abstract namespace directories because they do not directly contain a config for a namespace.

├── cluster
│   ├── namespace-reader-clusterrolebinding.yaml
│   ├── namespace-reader-clusterrole.yaml
│   ├── pod-creator-clusterrole.yaml
│   └── pod-security-policy.yaml
├── clusterregistry
│   ├── cluster-1.yaml
│   ├── cluster-2.yaml
│   ├── clusterselector-1.yaml
│   └── clusterselector-2.yaml
├── namespaces
│   ├── audit
│   │   └── namespace.yaml
│   ├── online
│   │   └── shipping-app-backend
│   │       ├── pod-creator-rolebinding.yaml
│   │       ├── quota.yaml
│   │       ├── shipping-dev
│   │       │   ├── job-creator-rolebinding.yaml
│   │       │   ├── job-creator-role.yaml
│   │       │   ├── namespace.yaml
│   │       │   └── quota.yaml
│   │       ├── shipping-prod
│   │       │   └── namespace.yaml
│   │       └── shipping-staging
│   │           └── namespace.yaml
│   ├── sre-rolebinding.yaml
│   ├── sre-supported-selector.yaml
│   └── viewers-rolebinding.yaml
└── system
    └── hierarchy-config.yaml

What's next