Configs overview

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 kubectl apply 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.

Example decision tree illustrating actions and results for Config Sync over time

  • 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: enabled is applied to the Kubernetes object

    The foo-corp cluster has a ClusterRole named pod-accountant that does not have the configmanagement.gke.io/managed: enabled annotation, and no config for the ClusterRole object exists in the repo. Config Sync does not configure the pod-accountant ClusterRole.

  • 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.yaml file 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-viewer ClusterRole now exists in the cluster, has the configmanagement.gke.io/managed: enabled annotation, and is in sync with the contents of quota-viewer-clusterrole.yaml.

    Some time later, someone deletes the cluster/quota-viewer-clusterrole.yaml file from the repo. Config Sync detects this change and removes the quota-viewer ClusterRole from the cluster.

  • You can start managing an existing object in a cluster by adding the configmanagement.gke.io/managed: enabled annotation.

    The foo-corp cluster has a namespace directory called shipping-dev. Within this namespace directory, a config for a Role called job-creator exists and has the configmanagement.gke.io/managed: enabled annotation. 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.

    The foo-corp cluster has a RoleBinding named pod-creator and a corresponding /namespaces/pod-creator/pod-creator.yaml file in the repo. The diagram shows that shipping-prod, shipping-staging, and shipping-dev are all namespaces (they each have a namespace.yaml file that defines a namespace) within the shipping-dev-backend abstract namespace directory. Each of these namespaces inherits the pod-creator RoleBinding.

    Some time later, someone modifies the pod-creator RoleBinding in the shipping-prod namespace directory. The Operator detects the change and updates pod-creator to match the config in the repo.

    Eventually, someone removes the pod-creator config from the repo. Config Sync detects the change and removes the pod-creator RoleBinding from each of the three namespaces.

  • Config Sync allows you to manually apply changes and doesn't manage objects unless they have the configmanagement.gke.io/managed: enabled annotation.

    Someone manually creates a new Role called secret-admin in the shipping-prod namespace. No config exists for the secret-admin Role in the repo. The secret-admin Role does not have the configmanagement.gke.io/managed: enabled annotation. Config Sync takes no action.

    Some time later, someone manually adds the configmanagement.gke.io/managed:enabled annotation to the secret-admin Role. There is still no corresponding config in the repo, so Config Sync deletes the secret-admin Role from the namespace.

  • Config Sync creates missing namespaces if configs exist for them.

    Someone commits a new config for the audit namespace, which doesn't exist in the cluster. Config Sync creates the audit namespace in the cluster and applies the configmanagement.gke.io/managed: enabled annotation to it.

  • Config Sync can manage configs for a namespace that doesn't have the configmanagement.gke.io/managed: enabled annotation.

    The shipping-dev namespace exists in the cluster but does not have the configmanagement.gke.io/managed: enabled annotation. However, the shipping-dev namespace directory in the repo has a RoleBinding named job-creators, which has the configmanagement.gke.io/managed: enabled annotation.

    Someone adds a config for the shipping-dev namespace to the repo, but there is no config for the job-creators RoleBinding. Since no config exists for the RoleBinding, but the RoleBinding has the configmanagement.gke.io/managed: enabled annotation, Config Sync deletes the RoleBinding.

    Later, someone adds a config for the job-creators RoleBinding. The job-creators RoleBinding is re-created with the properties defined in the config.

What's next