Configuring clusters and cluster-scoped objects

This page explains how to configure clusters and cluster-scoped objects. You can also read about configuring namespaces and namespace-scoped objects.

In unstructured repositories, you can organize configs for clusters and cluster-scoped objects in your repository in whatever way is most convenient. If you do not include a ClusterSelector in your repo, all configs for cluster-scoped objects apply to every cluster enrolled in Config Sync.

In hierarchical repositories, all configs for clusters and cluster-scoped objects are located within the cluster/ directory of a hierarchical repo. If you do not include a ClusterSelector in your repo, a config in cluster/ applies to every cluster enrolled in Config Sync.

Limiting which clusters a config affects

Normally, Config Sync applies a config to each enrolled cluster. If the config is within the namespaces/ subdirectory of a hierarchical repo, Config Sync first creates the namespace within each cluster and then applies all inherited configs to that namespace.

However, if you need to apply a config to a subset of clusters, you can add an annotation or ClusterSelector to your configs. To learn how to use these features, see Configuring only a subset of clusters.

Configuring the cluster's labels

You can use a Cluster config to configure a cluster's labels and annotations. If you use ClusterSelectors, each cluster needs a set of labels that the ClusterSelector can select. While you can label clusters manually, we recommend you configure labels using a Cluster config.

Configuring CustomResourceDefinitions

Config Sync lets you sync CustomResourceDefinitions (CRDs) the same way you would sync any other resource. There are a few things to keep in mind when syncing CRDs:

  • CRDs in hierarchical repositories, even when declaring a namespaced Custom Resource, must be placed in the cluster/ directory.

  • Updates to CRDs and their corresponding CustomResources do not occur in any predictable order. If you modify CRDs and the corresponding CustomResources in the same commit, there is no expectation that CRD updates occur before Custom Resource updates. This might cause the nomos status to report a transient error for a brief period of time, until both the CustomResource and the CRD are present in the cluster.

  • Config Sync does not allow removal of a CRD if any CustomResource in the repo depends on it. To remove a CRD, you also need to remove its CustomResource. We recommend that you remove them both in the same commit to the repo.

  • You can sync a CustomResource without syncing its CRD, as long as you can guarantee that the CRD already exists in the cluster.

What's next