This page describes configs, the files Config Sync reads from Git and applies to your clusters automatically. You can create a config and commit it to your repo.
Config Sync keeps your enrolled clusters in sync using configs. A
config is a YAML or JSON file that is stored in your
repo and contains the same types of configuration
details that you can manually apply to a cluster using the
command. This topic covers how configs work, how to write them, and how
Config Sync applies them to your enrolled clusters.
Config Sync is designed for cluster operators who manage many clusters. You can ensure that your clusters meet business and compliance standards by allowing Config Sync to manage namespaces, Roles, RoleBindings, ResourceQuotas, and other important Kubernetes objects, across your fleet. You can create a config for any Kubernetes object that can exist in a cluster.
Working with configs over time
The following decision tree illustrates the results of different configuration changes in a hypothetical group of clusters managed by Config Sync over time. Following the diagram, some hypothetical actions by cluster operators and the results of those actions are discussed and used to illustrate how Config Sync works.
This cluster uses the example repo. The cluster is already registered with Operator.
Config Sync applies configs only when at least one of the following is true:
- a relevant config exists in the repo
- the annotation
configmanagement.gke.io/managed: enabledis applied to the Kubernetes object
foo-corpcluster has a ClusterRole named
pod-accountantthat does not have the
configmanagement.gke.io/managed: enabledannotation, and no config for the ClusterRole object exists in the repo. Config Sync does not configure the
Config Sync applies a relevant change automatically when it is committed to the repo.
A cluster administrator commits a config to the
cluster/quota-viewer-clusterrole.yamlfile in the repo. This config defines a ClusterRole called
quota-viewer. Because the config is created in the
cluster/directory, it affects all enrolled clusters. Config Sync detects the newly-committed config and applies it. The
quota-viewerClusterRole now exists in the cluster, has the
configmanagement.gke.io/managed: enabledannotation, and is in sync with the contents of
Some time later, someone deletes the
cluster/quota-viewer-clusterrole.yamlfile from the repo. Config Sync detects this change and removes the
quota-viewerClusterRole from the cluster.
You can start managing an existing object in a cluster by adding the
foo-corpcluster has a namespace directory called
shipping-dev. Within this namespace directory, a config for a Role called
job-creatorexists and has the
configmanagement.gke.io/managed: enabledannotation. Someone updates the file
namespaces/dev/shipping-dev/job-creator-role.yaml. The Operator detects and applies the change.
Config Sync allows you to apply configuration changes to namespaces in a grouped hierarchical way.
foo-corpcluster has a RoleBinding named
pod-creatorand a corresponding
/namespaces/pod-creator/pod-creator.yamlfile in the repo. The diagram shows that
shipping-devare all namespaces (they each have a
namespace.yamlfile that defines a namespace) within the
shipping-dev-backendabstract namespace directory. Each of these namespaces inherits the
Some time later, someone modifies the
pod-creatorRoleBinding in the
shipping-prodnamespace directory. The Operator detects the change and updates
pod-creatorto match the config in the repo.
Eventually, someone removes the
pod-creatorconfig from the repo. Config Sync detects the change and removes the
pod-creatorRoleBinding from each of the three namespaces.
Config Sync allows you to manually apply changes and doesn't manage objects unless they have the
Someone manually creates a new Role called
shipping-prodnamespace. No config exists for the
secret-adminRole in the repo. The
secret-adminRole does not have the
configmanagement.gke.io/managed: enabledannotation. Config Sync takes no action.
Some time later, someone manually adds the
configmanagement.gke.io/managed:enabledannotation to the
secret-adminRole. There is still no corresponding config in the repo, so Config Sync deletes the
secret-adminRole from the namespace.
Config Sync creates missing namespaces if configs exist for them.
Someone commits a new config for the
auditnamespace, which doesn't exist in the cluster. Config Sync creates the
auditnamespace in the cluster and applies the
configmanagement.gke.io/managed: enabledannotation to it.
Config Sync can manage configs for a namespace that doesn't have the
shipping-devnamespace exists in the cluster but does not have the
configmanagement.gke.io/managed: enabledannotation. However, the
shipping-devnamespace directory in the repo has a RoleBinding named
job-creators, which has the
Someone adds a config for the
shipping-devnamespace to the repo, but there is no config for the
job-creatorsRoleBinding. Since no config exists for the RoleBinding, but the RoleBinding has the
configmanagement.gke.io/managed: enabledannotation, Config Sync deletes the RoleBinding.
Later, someone adds a config for the
job-creatorsRoleBinding is re-created with the properties defined in the config.