Syncing from a Git repository

This quickstart shows you how to get started with Config Sync on a new cluster, using the Anthos Config Management samples repository to bootstrap a cluster with a set of configs. In this quickstart, you do not need write access to the repository. Imagine that a compliance team in your organization is responsible for creating the configs, and that each cluster is required to sync to the repository.

After you complete this quickstart, you can follow an advanced quickstart about writing, testing, and syncing configs.

Before you begin

  1. Create a cluster.

  2. Set up the kubectl command to authenticate to the cluster and create a RoleBinding to make yourself a cluster administrator, using the following commands. Use your cluster name where you see [MY-CLUSTER], and use your Cloud Billing account's email address where you see [USER-ACCOUNT]. Depending on how you configured the gcloud command on your local system, you may need to add the --project and --zone fields.

    gcloud container clusters get-credentials [MY-CLUSTER]
    kubectl create clusterrolebinding cluster-admin-binding \
      --clusterrole cluster-admin --user [USER_ACCOUNT]
  3. Install the nomos command onto your local system.

  4. Install the Config Sync Operator onto the cluster you just created.

Configure your cluster

Create a file config-management.yaml and copy the below YAML file into it. We recommend that you enable the ability to sync from multiple repositories for additional functionality. To learn more, see Syncing from multiple repositories.

# config-management.yaml
kind: ConfigManagement
  name: config-management
  # clusterName is required and must be unique among all managed clusters
  clusterName: my-cluster
  # Enable multi-repo mode to use new features
  enableMultiRepo: true

Apply the configuration to your cluster:

kubectl apply -f config-management.yaml

If the command succeeds, Kubernetes updates Config Sync on your cluster to create controllers and CustomResourceDefinitions (CRDs). To verify that Config Sync is running, wait for the RootSync and RepoSync CRDs to be available:

until kubectl get customresourcedefinitions; \
do date; sleep 1; echo ""; done


NAME                          CREATED AT   YYYY-MM-DDThh:mm:ssZ   YYYY-MM-DDThh:mm:ssZ

Then create a file with a RootSync custom resource. We recommend that you use unstructured format as it lets you organize your configs in the way that is most convenient to you. Because the repo is world-readable, auth is set to none. For an explanation of the fields, see Configuration for the Git repository.

# root-sync.yaml
# If you are using a Config Sync version earlier than 1.7,
# use: apiVersion:
kind: RootSync
  name: root-sync
  namespace: config-management-system
  sourceFormat: unstructured
    branch: init
    dir: quickstart/multirepo/root
    auth: none

Apply the RootSync to your cluster:

kubectl apply -f root-sync.yaml

If the command succeeds, Kubernetes updates Config Sync on your cluster to create the reconcilers and to begin syncing your cluster's configuration from the repository. To verify that Config Sync is running, list all Pods running in the config-management-system namespace:

kubectl get pods -n config-management-system


NAME                                       READY   STATUS    RESTARTS   AGE
admission-webhook-7dbc55cbf5-thlnl         1/1     Running   1          89m
admission-webhook-7dbc55cbf5-x54n9         1/1     Running   0          89m
ns-reconciler-gamestore-7478cb7b87-hf6zn   3/3     Running   0          2m37s
reconciler-manager-7cdb699bf8-fns5r        2/2     Running   0          5m29s
root-reconciler-6c7c87b7b7-txptf           3/3     Running   0          4m51s

Check the sync status

You can check if Config Sync successfully syncs all configs to your cluster using the nomos status command.

 nomos status


  SYNCED   282a2023
  SYNCED      282a2023

Examine your cluster and repo

The quickstart/multirepo/root directory includes ClusterRole, CustomResourceDefinition, configurations for Prometheus Operator for monitoring, Rolebinding, Namespace, and RepoSync. These configs are applied as soon as the Config Sync is configured to read from the repo.

All objects managed by Config Sync have the label set to

  • List namespaces managed by Config Sync:

    kubectl get ns -l


    NAME         STATUS   AGE
    gamestore    Active   58s
    monitoring   Active   58s

    Examine the configs that caused these namespaces to be created, such as namespace-gamestore.yaml and acm-monitor/namespace-monitoring.yaml.

  • List ClusterRoles managed by Config Sync:

    kubectl get clusterroles -l


    NAME                  CREATED AT
    namespace-reader      YYYY-MM-DDThh:mm:ssZ
    prometheus-acm        YYYY-MM-DDThh:mm:ssZ
    prometheus-operator   YYYY-MM-DDThh:mm:ssZ
    webstore-admin        YYYY-MM-DDThh:mm:ssZ

    Examine the ClusterRole configs declaring:

    • clusterrole-namespace-reader.yaml
    • clusterrole-webstore-admin.yaml
  • List RepoSyncs managed by Config Sync:

    kubectl get -A -l


    NAMESPACE   NAME        SOURCECOMMIT                               SYNCCOMMIT
    gamestore   repo-sync   282a2023cf73ac94e8a85b464ac9f76d209067b0   282a2023cf73ac94e8a85b464ac9f76d209067b0

    Examine the RepoSync configs declaring:

    • reposync-gamestore.yaml

You can examine other objects, such as CRDs and Rolebindings, in the same way.

Attempt to manually modify a managed object

Config Sync prevents mutation of managed objects through the admission webhook.

If you attempt to make a conflicting change by manually modifying a Config Sync managed Kubernetes object, you will get pushed back with an error. To test this, try to delete the gamestore namespace.

kubectl delete namespace gamestore


error: admission webhook "" denied the request: requester is not authorized to delete managed resources

Cleaning up

After you finish the exercises in this topic, you can clean up by deleting the cluster you used for testing.

What's next