Quickstart: Sync configs from a repository

In this tutorial, you create a Google Kubernetes Engine (GKE) Enterprise edition cluster and use Config Sync to sync to configs in the multi-repo samples repository.

Imagine that your compliance team is responsible for making sure that everyone in your organization is following internal rules. To enforce these rules, the compliance team has created configs, which they have added to the samples repository. Each cluster in your organization is required to sync to the repository and you are responsible for creating and syncing clusters.

Before you begin

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

6. Make sure that you have the following role or roles on the project: GKE Hub Admin

   Check for the roles

   1. In the Google Cloud console, go to the IAM page.

      Go to IAM
   2. Select the project.

   3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

   4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

   Grant the roles

   1. In the Google Cloud console, go to the IAM page.

      Go to IAM
   2. Select the project.
   3. Click Grant access.

   4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

   5. In the Select a role list, select a role.
   6. To grant additional roles, click Add another role and add each additional role.
   7. Click Save.

Create a cluster

In this section, you create a cluster that you can use in this tutorial. Although in a real-world scenario you would likely manage multiple clusters, to simplify this tutorial you only create and manage one cluster.

To create a cluster, complete the following steps:

1. In the Google Cloud console, go to the Kubernetes Engine page.

   Go to Google Kubernetes Engine

2. If you're using GKE for the first time, click Enable to enable the Kubernetes Engine API.

3. Click Create.

4. In the Autopilot section, select Configure.

5. In the Cluster basics section, enter cs-cluster in the Name field.

6. In the Cluster tier section, select Enterprise tier. This is essential for Config Sync. Leave all other fields with their recommended defaults.

7. Click Create. You are taken to the Kubernetes clusters page. It takes several minutes for your cluster to be created. When you see a green check mark in the Status column next to your cluster, it's ready.

Configure your cluster

Now that you've created a cluster, you can configure Config Sync to sync to the configs in the config-sync-quickstart directory of the samples repository.

To configure Config Sync on the Google Cloud console, complete the following steps:

1. In the Google Cloud console, enable the GKE Hub API.

   Go to GKE Hub API

2. In the Google Cloud console, go to the Config page under the Features section.

   Go to Config

3. Click Install Config Sync.

4. Select Auto-upgrades to enable Config Sync to upgrade versions automatically.

5. Under Installation options, select Install Config Sync on individual clusters.

6. In the Available clusters table, select cs-cluster and click Install Config Sync. In the Settings tab, you should see the status for the cs-cluster as Enabled after a few minutes.

7. On the Config Sync dashboard, click Deploy Package.

8. In the Select clusters for package deployment table, select cs-cluster and then click Continue.

9. Leave Package hosted on Git selected and then click Continue.

10. In the Package name field, enter sample-repository.

11. In the Repository URL field, enter https://github.com/GoogleCloudPlatform/anthos-config-management-samples.

12. In the Path field, enter config-sync-quickstart/multirepo/root.

13. Leave all other fields with their default values.

14. Click Deploy Package.

    After a few minutes, you should see Synced in the Sync status column for cs-cluster.

Now that Config Sync is synced to a repository, it continuously reconciles the state of your clusters with the configs in the repository.

Explore the Config Sync installation

In the following sections, you use Cloud Shell to explore the repository that cs-cluster is syncing from and confirm that the configs in the repository are being deployed.

Open Cloud Shell

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. To use the commands in the following sections, configure kubectl command-line access:

   gcloud container clusters get-credentials cs-cluster \
       --zone ZONE \
       --project PROJECT_ID
   

   Replace the following:

   • ZONE: the zone that you created your cluster in
   • PROJECT_ID: your project ID

   The output is the following:

   Fetching cluster endpoint and auth data.
   kubeconfig entry generated for cs-cluster.
   

   If you're asked for authorization, click Authorize.

Examine your cluster and repository

The config-sync-quickstart directory includes ClusterRole, CustomResourceDefinition, Rolebinding, Namespace, and RepoSync configs. It also includes configurations for the Prometheus Operator for monitoring. These configs are applied as soon as the Config Sync is configured to read from the repository.

All objects managed by Config Sync have the app.kubernetes.io/managed-by label set to configmanagement.gke.io. You can use this label to view managed objects.

To list namespaces managed by Config Sync, run the following command:

kubectl get ns -l app.kubernetes.io/managed-by=configmanagement.gke.io

The output is similar to the following:

NAME         STATUS   AGE
gamestore    Active   58s
monitoring   Active   58s

You can navigate to the /config-sync-quickstart/multirepo/ folder of the repository in GitHub to explore the configs that caused these namespaces to be created.

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

Check the sync status

When you're using Config Sync, you can use the nomos command-line tool. This tool provides you with additional functionality for Config Sync.

In this section, you check if Config Sync successfully synced all configs to your cluster by using the nomos status command:

nomos status

The output is similar to the following:

*gke_PROJECT_ID_ZONE_cs-cluster
  --------------------
  <root>:root-sync                         https://github.com/GoogleCloudPlatform/anthos-config-management-samples/config-sync-quickstart/multirepo/root@main
  SYNCED @ 2023-02-03 16:58:42 +0000 UTC   1fbab5c90af9029b26451fec92e9900d8db23aee
  Managed resources:
     NAMESPACE    NAME                                                                                      STATUS    SOURCEHASH
                  clusterrole.rbac.authorization.k8s.io/namespace-reader                                    Current   1fbab5c
                  clusterrole.rbac.authorization.k8s.io/prometheus-acm                                      Current   1fbab5c
                  clusterrole.rbac.authorization.k8s.io/prometheus-operator                                 Current   1fbab5c
                  clusterrole.rbac.authorization.k8s.io/webstore-admin                                      Current   1fbab5c
                  clusterrolebinding.rbac.authorization.k8s.io/prometheus-acm                               Current   1fbab5c
                  clusterrolebinding.rbac.authorization.k8s.io/prometheus-operator                          Current   1fbab5c
                  customresourcedefinition.apiextensions.k8s.io/alertmanagerconfigs.monitoring.coreos.com   Current   1fbab5c
                  customresourcedefinition.apiextensions.k8s.io/alertmanagers.monitoring.coreos.com         Current   1fbab5c
                  customresourcedefinition.apiextensions.k8s.io/anvils.acme.com                             Current   1fbab5c
                  customresourcedefinition.apiextensions.k8s.io/podmonitors.monitoring.coreos.com           Current   1fbab5c
                  customresourcedefinition.apiextensions.k8s.io/probes.monitoring.coreos.com                Current   1fbab5c
                  customresourcedefinition.apiextensions.k8s.io/prometheuses.monitoring.coreos.com          Current   1fbab5c
                  customresourcedefinition.apiextensions.k8s.io/prometheusrules.monitoring.coreos.com       Current   1fbab5c
                  customresourcedefinition.apiextensions.k8s.io/servicemonitors.monitoring.coreos.com       Current   1fbab5c
                  customresourcedefinition.apiextensions.k8s.io/thanosrulers.monitoring.coreos.com          Current   1fbab5c
                  customresourcedefinition.apiextensions.k8s.io/webstores.marketplace.com                   Current   1fbab5c
                  namespace/gamestore                                                                       Current   1fbab5c
                  namespace/monitoring                                                                      Current   1fbab5c
     gamestore    reposync.configsync.gke.io/repo-sync                                                      Current   1fbab5c
     gamestore    rolebinding.rbac.authorization.k8s.io/gamestore-admin                                     Current   1fbab5c
     gamestore    rolebinding.rbac.authorization.k8s.io/gamestore-webstore-admin                            Current   1fbab5c
     monitoring   deployment.apps/prometheus-operator                                                       Current   1fbab5c
     monitoring   prometheus.monitoring.coreos.com/acm                                                      Current   1fbab5c
     monitoring   service/prometheus-acm                                                                    Current   1fbab5c
     monitoring   service/prometheus-operator                                                               Current   1fbab5c
     monitoring   serviceaccount/prometheus-acm                                                             Current   1fbab5c
     monitoring   serviceaccount/prometheus-operator                                                        Current   1fbab5c
     monitoring   servicemonitor.monitoring.coreos.com/acm-service                                          Current   1fbab5c
  --------------------
  gamestore:repo-sync                      https://github.com/GoogleCloudPlatform/anthos-config-management-samples/config-sync-quickstart/multirepo/namespaces/gamestore@main
  SYNCED @ 2023-02-03 16:58:51 +0000 UTC   1fbab5c90af9029b26451fec92e9900d8db23aee
  Managed resources:
     NAMESPACE   NAME                                 STATUS    SOURCEHASH
     gamestore   configmap/store-inventory            Current   1fbab5c
     gamestore   webstore.marketplace.com/gameplace   Current   1fbab5c

In this output, you can see that cs-cluster is successfully syncing from two repositories. In addition, because all resources have a status of Current, the state of the resource matches the state that you want.

Clean up

1. Go to the GKE menu in Google Cloud console.

   Go to GKE

2. Next to the cs-cluster, click Actions, then click Delete.

3. When prompted to confirm, click Delete again.

What's next

• Learn about validating configs.