Hierarchical repo overview

This page describes how Config Sync reads configs from a hierarchical repository 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 repo. Unstructured repositories are recommended for most users, and can be combined with Hierarchy Controller to provide namespace inheritance similar to that offered by hierarchical repositories.

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 hierarchical repo

For hierarchical repos, 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 hierarchical repo

The example hierarchical repo, illustrates the structure of a repo.

Notice the nested abstract namespace directories eng/ and rnd/ within namespaces/. They are abstract namespace directories because they do not directly contain a config for a namespace.

├── cluster
│   ├── admin-clusterrole.yaml
│   ├── namespace-reader-clusterrolebinding.yaml
│   ├── namespace-reader-clusterrole.yaml
│   ├── rbac-viewer-clusterrole.yaml
│   └── rbac-viewers.yaml
├── namespaces
│   ├── eng
│   │   ├── analytics
│   │   │   └── namespace.yaml
│   │   ├── eng-roleinding.yaml
│   │   ├── eng-role.yaml
│   │   ├── gamestore
│   │   │   ├── bob-rolebinding.yaml
│   │   │   ├── inventory-configmap.yaml
│   │   │   └── namespace.yaml
│   │   ├── network-policy-allow-gamestore-ingress.yaml
│   │   ├── quota.yaml
│   │   └── selectors.yaml
│   ├── network-policy-default-deny-all.yaml
│   ├── rnd
│   │   ├── incubator-1
│   │   │   ├── incubator-1-admin-role.yaml
│   │   │   └── namespace.yaml
│   │   └── incubator-2
│   │       └── namespace.yaml
│   └── viewers-rolebinding.yaml
└── system
    ├── README.md
    └── repo.yaml

What's next