Use a hierarchical repository

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 repository. 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. If you are already using a hierarchical repository, you can convert it to an unstructured repository.

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 repository

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.

namespaces/

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.

cluster/

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.

clusterregistry/

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.

system/

The system/ directory contains configs for the Operator.

Example hierarchical repository

The following directory structure demonstrates how to use a Config Sync hierarchical repository 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 admin sets up a policy in namespaces/limit-range.yaml to constrain resource allocations (to Pods or containers) in both namespaces.
  • The cluster admin also sets up ClusterRoles and ClusterRoleBindings.

A valid Config Sync hierarchical repository 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 Config Management 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
├── README.md
└── system
    └── repo.yaml

What's next