[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-07-31。"],[],[],null,["# Use a hierarchical repository\n\nThis page describes how Config Sync reads [configs](/kubernetes-engine/enterprise/config-sync/docs/concepts/configs)\nfrom a hierarchical and applies the resulting configuration to your\nclusters automatically.\n\nWe recommend that you [use an unstructured source of truth](/kubernetes-engine/enterprise/config-sync/docs/how-to/unstructured-repo)\ninstead of hierarchical because it provides the same core\ncapabilities, but gives you more flexibility in organizing your resources.\nIf you already use a hierarchical source of truth, you can\n[convert it to an unstructured source of truth](/kubernetes-engine/enterprise/config-sync/docs/how-to/unstructured-repo#convert).\n\nTo understand how Config Sync uses a hierarchical repository, it's helpful\nif you're familiar with Git repositories and the `git` command-line\ninterface.\n\nYou can\n[view an example of how to organize and configure a hierarchical source of truth](https://github.com/GoogleCloudPlatform/anthos-config-management-samples/tree/main/hierarchical-format)\nin the Config Sync samples repository.\n\nStructure of the directory\n--------------------------\n\nFor hierarchical sources, Config Sync takes advantage of\nfilesystem-like structures, and uses the directory to determine which clusters or namespaces\na config is relevant to.\n\n### `namespaces/`\n\nThe `namespaces/` directory contains configs for namespaces and namespace-scoped\nobjects. The structure within `namespaces/` is the mechanism that drives\n[namespace inheritance](/kubernetes-engine/enterprise/config-sync/docs/how-to/namespace-scoped-objects#abstract-namespace-config).\nYou can limit which namespaces can inherit a config, by using a\n[NamespaceSelector](/kubernetes-engine/enterprise/config-sync/docs/how-to/namespace-scoped-objects#namespaceselectors).\n\n### `cluster/`\n\nThe `cluster/` directory contains configs that apply to entire clusters, rather\nthan to namespaces. By default, any config in the `cluster/` directory applies\nto every cluster enrolled in Config Sync. You can limit which\nclusters a config can affect by using a\n[ClusterSelector](/kubernetes-engine/enterprise/config-sync/docs/how-to/cluster-scoped-objects#configure_a_subset_of_clusters).\n| **Note:** Namespaces are configured within `namespaces/`, even though they are cluster-scoped.\n\n### `clusterregistry/`\n\nThe `clusterregistry/` directory is optional, and contains configs for\n[ClusterSelectors](/kubernetes-engine/enterprise/config-sync/docs/how-to/cluster-scoped-objects#configure_a_subset_of_clusters).\nClusterSelectors limit which clusters a config applies to, and are referenced in\nconfigs found in the `cluster/` and `namespaces/` directories.\n\n### `system/`\n\nThe `system/` directory contains configs for the Operator.\n\nExample hierarchical source of truth\n------------------------------------\n\nThe following directory structure demonstrates how to use a Config Sync\nhierarchical source of truth to configure a Kubernetes cluster shared by two\ndifferent teams, `team-1` and `team-2`.\n\n- Each team has its own Kubernetes namespace, Kubernetes service account, resource quotas, network policies, rolebindings.\n- The cluster administrator sets up a policy in `namespaces/limit-range.yaml` to constrain resource allocations (to Pods or containers) in both namespaces.\n- The cluster administrator also sets up ClusterRoles and ClusterRoleBindings.\n\nA valid Config Sync hierarchical source must include\nthree subdirectories: `cluster/`, `namespaces/`, and `system/`.\n\nThe `cluster/` directory contains configs that apply to entire clusters\n(such as ClusterRole, ClusterRoleBinding), rather than to namespaces.\n\nThe `namespaces/` directory contains configs for the namespace objects and the\nnamespace-scoped objects. Each subdirectory under `namespaces/` includes the\nconfigs for a namespace object and all the namespace-scoped objects under the\nnamespace. The name of a subdirectory should be the same as the name of the\nnamespace object. Namespace-scoped objects which need to be created in each\nnamespace, can be put directly under `namespaces/` (for example,\n`namespaces/limit-range.yaml`).\n\nThe `system/` directory contains configs for the ConfigManagement Operator. \n\n ├── cluster\n │ ├── clusterrolebinding-namespace-reader.yaml\n │ ├── clusterrole-namespace-reader.yaml\n │ ├── clusterrole-secret-admin.yaml\n │ └── clusterrole-secret-reader.yaml\n ├── namespaces\n │ ├── limit-range.yaml\n │ ├── team-1\n │ │ ├── namespace.yaml\n │ │ ├── network-policy-default-deny-egress.yaml\n │ │ ├── resource-quota-pvc.yaml\n │ │ ├── rolebinding-secret-reader.yaml\n │ │ └── sa.yaml\n │ └── team-2\n │ ├── namespace.yaml\n │ ├── network-policy-default-deny-all.yaml\n │ ├── resource-quota-pvc.yaml\n │ ├── rolebinding-secret-admin.yaml\n │ └── sa.yaml\n ├── README.md\n └── system\n └── repo.yaml\n\nUse namespace inheritance and abstract namespaces\n-------------------------------------------------\n\nWith a hierarchical source of truth, you can use the concept of namespace\ninheritance to automatically apply configs to groups of namespaces in all the\nclusters where those namespaces\nexist (or should exist).\n\nNamespace inheritance applies to the `namespaces/`\ndirectory of the hierarchical repository and all its subdirectories. Configs in\nother directories in the repository, such as `cluster/`, are not subject to\ninheritance.\n\nIn a hierarchical source of truth, the\n`namespaces/` directory can contain two different types of subdirectories:\n\n- A *namespace directory* contains a config for a namespace. The name of the\n file containing the config is not important, but the config must have\n `kind: Namespace`. A namespace directory can also contain configs for\n other kinds of Kubernetes objects. A namespace directory cannot contain\n subdirectories. A namespace config represents an actual namespace in a\n cluster.\n\n- An *abstract namespace directory* contains namespace directories. It can\n also contain configs for other Kubernetes objects, but it cannot directly\n contain a config for a namespace. An abstract namespace directory does not\n represent an object in a Kubernetes cluster, but its descendant namespace\n directories do.\n\nTo help ensure that your namespace and abstract namespace sources have the\ncorrect type of configs and structure, error [KNV1003: IllegalNamespaceSubdirectoryError](/kubernetes-engine/enterprise/config-sync/docs/reference/errors#knv1003)\nreports when there is a problem.\n\nConfigs in a namespace directory only apply to that namespace. However, configs in\nan abstract namespace directory are applied to all of that abstract namespace's\ndescendant namespace directories (or those descendant namespaces that match a\nconfig's\n[NamespaceSelector](/kubernetes-engine/enterprise/config-sync/docs/how-to/namespace-scoped-objects#namespaceselectors), if one is present).\n\nInheritance of a config in the `namespaces/` directory is based largely\non its location within the directory tree in the source of truth. To understand which\nconfigs are being applied to a given namespace in a given cluster, you can\nbrowse the\n[namespace inheritance example repository](https://github.com/GoogleCloudPlatform/anthos-config-management-samples/tree/main/namespace-inheritance).\n\nRestricted namespaces\n---------------------\n\n`config-management-system` is a restricted namespace. You cannot use it as\nan abstract namespace directory. You can define a\n`config-management-system` namespace, but the only permitted resource type\nfor the `config-management-system` namespace is `RootSync`.\n\nMaking changes in your source of truth\n--------------------------------------\n\nWhen you make a change in your source of truth that creates or deletes namespace directories from within the\n`namespaces/` directory, you might get unexpected results depending on the action:\n| **Caution:** By default, Git repositories don't provide fine-grained access control. If the set of people with commit rights to your repository is not exactly the same as the set of users allowed to create, modify, or delete Kubernetes objects in your clusters, consider using an access control mechanism such as `OWNERS` or `CODEOWNERS` files in your repository.\n\n- **Creating a directory** : when a valid `namespaces/` hierarchy is committed to the source of truth, Config Sync creates namespaces, and then creates Kubernetes objects in those namespaces for each config that the namespace directory contains or inherits.\n- **Deleting a directory**: deleting a namespace directory is a destructive operation. The namespace, and its contents, is deleted, on every cluster managed by Config Sync where the namespace exists. If you delete an abstract namespace directory containing descendant namespace directories, all of those namespaces and their contents are deleted from every cluster managed by Config Sync.\n- **Renaming a directory**: Renaming a namespace directory is a deletion, followed by a\n creation and is considered a destructive operation. Renaming an abstract namespace\n directory has no externally visible effect.\n\n | **Note:** If you rename a namespace directory, remember to also update its name in the config for the namespace.\n- **Moving a directory** : moving a namespace or an abstract namespace directory within `namespaces/`\n does not delete the namespace or objects within it, except where the namespace\n starts or stops inheriting a config from an abstract namespace directory, due\n to a change in its hierarchy.\n\nWhat's next\n-----------\n\n- Learn how to [manage namespaces and namespace-scoped objects](/kubernetes-engine/enterprise/config-sync/docs/how-to/namespace-scoped-objects)"]]
