Use a hierarchical repository

This page describes how Config Sync reads configs from a hierarchical source of truth 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 an unstructured source of truth. Unstructured sources of truth are recommended for most use cases. If you are already using a hierarchical source of truth, you can convert it to an unstructured source of truth.

To understand how Config Sync uses a hierarchical repository, it's helpful if you're familiar with Git repositories and the git command-line interface.

Structure of the directory

For hierarchical sources, Config Sync takes advantage of filesystem-like structures, and uses the directory 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.

Example hierarchical source of truth

The following directory structure demonstrates how to use a Config Sync hierarchical source of truth to configure a Kubernetes cluster shared by two different teams, team-1 and team-2.

  • Each team has its own Kubernetes namespace, Kubernetes service account, resource quotas, network policies, rolebindings.
  • The cluster administrator sets up a policy in namespaces/limit-range.yaml to constrain resource allocations (to Pods or containers) in both namespaces.
  • The cluster administrator also sets up ClusterRoles and ClusterRoleBindings.

A valid Config Sync hierarchical source must include three subdirectories: cluster/, namespaces/, and system/.

The cluster/ directory contains configs that apply to entire clusters (such as ClusterRole, ClusterRoleBinding), rather than to namespaces.

The namespaces/ directory contains configs for the namespace objects and the namespace-scoped objects. Each subdirectory under namespaces/ includes the configs for a namespace object and all the namespace-scoped objects under the namespace. The name of a subdirectory should be the same as the name of the namespace object. Namespace-scoped objects which need to be created in each namespace, can be put directly under namespaces/ (for example, namespaces/limit-range.yaml).

The system/ directory contains configs for the ConfigManagement Operator.

├── cluster
│   ├── clusterrolebinding-namespace-reader.yaml
│   ├── clusterrole-namespace-reader.yaml
│   ├── clusterrole-secret-admin.yaml
│   └── clusterrole-secret-reader.yaml
├── namespaces
│   ├── limit-range.yaml
│   ├── team-1
│   │   ├── namespace.yaml
│   │   ├── network-policy-default-deny-egress.yaml
│   │   ├── resource-quota-pvc.yaml
│   │   ├── rolebinding-secret-reader.yaml
│   │   └── sa.yaml
│   └── team-2
│       ├── namespace.yaml
│       ├── network-policy-default-deny-all.yaml
│       ├── resource-quota-pvc.yaml
│       ├── rolebinding-secret-admin.yaml
│       └── sa.yaml
└── system
    └── repo.yaml

What's next