Console

Install Config Sync

To install Config Sync, all clusters must be registered to a fleet.When you install Config Sync in the Google Cloud console, selecting individualclusters automatically registers those clusters to your fleet.

1. In the Google Cloud console, go to theConfig page under theFeatures section.

   Go to Config

2. ClickaddInstall Config Sync.
3. Select the Config Sync version that you want to use.
4. UnderInstallation options, select one of the following options:
   • Install Config Sync on entire fleet (recommended): Config Syncis installed on all clusters in the fleet.
   • Install Config Sync on individual clusters: Config Sync isinstalled on the clusters that you select. Any selected clusters are automatically registered to your fleet.
5. If you're installing Config Sync on individual clusters, in theAvailable clusters table, select the clusters on which you want to install Config Sync.
6. ClickInstall Config Sync. In theSettings tab, after a few minutes,you should seeEnabled in theStatus column for the clusters in your fleet.

Deploy a package

After you have registered your clusters to a fleet and installed Config Sync,you can configure Config Sync to deploy a package to a cluster from asource of truth. You can deploy the same packageto multiple clusters or deploy different packages to different clusters.You can edit a package after deploying it, except for some settings likepackage name and sync type. For more information, seeManage packages.

To deploy a package, complete the following steps:

1. In the Google Cloud console, go to theConfig Sync dashboard.

   Go to Config Sync dashboard

2. ClickDeploy Package.

3. In theSelect clusters for package deployment table, select the clusterthat you want to deploy a package to and then clickContinue.

4. Select eitherPackage hosted on Git orPackage hosted on OCI asyour source type and then clickContinue.

5. In thePackage details section, enter aPackage name, whichidentifies the RootSync or RepoSync object.

6. In theSync type field, choose eitherCluster scoped sync orNamespace scoped sync asthe sync type.

   Cluster scoped sync creates a RootSync object and Namespace scoped sync creates a RepoSync object.For more information about these objects, seeConfig Sync architecture.

7. In theSource section, complete the following:

   • For sources hosted in a Git repository, enter the following fields:

     1. Enter the URL of the Git repository that you're using as a source of truthas theRepository URL.
     2. Optional: Update theRevision field to check out if you're not usingthe defaultHEAD.
     3. Optional: Update thePath field if you don't want to sync from theroot repository.
     4. Optional: Update theBranch field if you're not using the defaultmain branch.

   • For sources hosted in an OCI image, enter the following fields:

     1. Enter the URL of the OCI image that you're using as a source of truthas theImage.
     2. Enter the path of the directory to sync from,relative to the root directory, as theDirectory.

8. (Optional): Expand theAdvanced settings section to complete the following:

   1. Select anAuthentication type. Config Sync needs read-only access toyour source of truth to read the configuration files in the source and apply them to your clusters.Unless your source requires no authentication, such as a public repository,ensure that you grant Config Syncread-only access to yourGit repository,OCI image, orHelm chart (gcloud CLI only).Choose the same authentication type that you configured when you installedConfig Sync:

      Note: for OCI, you can only selectWorkload Identity for authentication.
      • None: Use no authentication.
      • SSH: Authenticate by using an SSH key pair.
      • Cookiefile: Authenticate by using acookiefile.
      • Token: Authenticate by using an access token or password.
      • Google Cloud Repository: Use a Google service account to access aCloud Source Repositories repository. Only select this option ifWorkload Identity Federation for GKE isnot enabled in your cluster.
      • Workload Identity: Use a Google service account to access aCloud Source Repositories repository.

   2. Enter a number in seconds to set theSync wait time, which determineshow long Config Sync waits between attempts to pull from the source of truth.

   3. Enter aGit proxy URL for the HTTPS proxy to be used whencommunicating with the source of truth.

9. ClickDeploy Package.

   You are redirected to the Config SyncPackages page. After a fewminutes, you should seeSynced in theSync statuscolumn for the cluster that you configured.

gcloud

Before you continue, make sure you'veregistered your clustersto afleet.

1. Enable theConfigManagement fleet feature:

   gcloudbetacontainerfleetconfig-managementenable

2. Prepare the configuration by creating a file namedapply-spec.yaml andcopying the following YAML file into it.

   You can set all of the optionalspec.configSync fields that you needwhen you create your manifest, and later usekubectl commands for configuration.You can also only set thespec.configSync.enabled field astrue andomit the optional fields. You can then later usekubectl commands tocreate additional RootSync objectsor RepoSyncs that you can fully manage usingkubectl commands later.

   # apply-spec.yamlapplySpecVersion:1spec:configSync:enabled:true# If you don't have a source of truth yet, omit the# following fields. You can configure them later.sourceType:SOURCE_TYPEsourceFormat:FORMATsyncRepo:REPOsyncRev:REVISIONsecretType:SECRET_TYPEgcpServiceAccountEmail:EMAILmetricsGcpServiceAccountEmail:METRICS_EMAILpolicyDir:DIRECTORYpreventDrift:false

   Replace the following:

   • SOURCE_TYPE: addgit to sync from a Git repository,oci to sync from an OCI image, orhelm to sync from a Helm chart.If no value is specified, the default isgit.
   • FORMAT: addunstructured to use anunstructured repository or addhierarchy to use ahierarchical repository.These values are case-sensitive.This field is optional and the default value ishierarchy. We recommend that you addunstructured, because this formatlets you organize your configs in the way that is most convenient toyou.

   • REPO: add the URL of the source of truth.Git and Helm repository URLs use either the HTTPS or SSH protocol. Forexample,https://github.com/GoogleCloudPlatform/anthos-config-management-samples. If you plan to use SSH as yoursecretType,enter your URL with the SSH protocol. This field is required and if youdon't enter a protocol, the URL is treated as an HTTPS URL.

     OCI URLs use the following format:LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME.By default, the image is pulled from thelatest tag, but you canpull in images byTAG orDIGEST instead. SpecifyTAG orDIGESTin thePACKAGE_NAME:

     • To pull byTAG:LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME:TAG
     • To pull byDIGEST:LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME@sha256:DIGEST
     Caution: Config Sync requires that the OCI layer is compressed inthetar ortar+gzip format.Other formats (for example,tar+bz2) won't be recognized byConfig Sync. Switching from a valid REPO to an OCI image with anunsupported format will cause managed resources to be pruned withoutan error.

   • REVISION: the Git revision (tag or hash)or branch name to sync from. When using a hash, it must be a fullhash, and not an abbreviated form.

   • SECRET_TYPE: one of the followingsecretTypes:

     git

     • none: Use no authentication.
     • ssh: Use an SSH key pair.
     • cookiefile: Use acookiefile.
     • token: Use a token.
     • gcpserviceaccount: Use a Google service account to access aCloud Source Repositories or Secure Source Manager repository. If you select thisauthentication type, you need to create an IAM policy binding afteryou finish configuring Config Sync. For details, see the Googleservice account tab of theGrant Config Sync access to Git with a Google service accountsection.
     • gcenode: Use a Google service account to access aCloud Source Repositories. Only select this option if Workload Identity Federation for GKEis not enabled in your cluster.
     • githubapp: Use a GitHub App to authenticate to a GitHub repository.

     For more information on these authentication types, seeGrant Config Sync access to Git.

     oci

     • none: Use no authentication
     • gcenode: Use the Compute Engine default service account toaccess an image in Artifact Registry. Only selectthis option if Workload Identity Federation for GKE is not enabled in your cluster.
     • gcpserviceaccount: Use a Google service account to access animage.

     helm

     • token: Use a token.
     • gcenode: Use the Compute Engine default service account toaccess an image in Artifact Registry. Only selectthis option if Workload Identity Federation for GKE is not enabled in your cluster.
     • gcpserviceaccount: Use a Google service account to access animage.

     • EMAIL: If you addedgcpserviceaccount as yoursecretType, add your Google serviceaccount email address. For example,acm@PROJECT_ID.iam.gserviceaccount.com.

     • METRICS_EMAIL: the email of the Google CloudService Account (GSA) used for exporting Config Sync metrics toCloud Monitoring. The GSA should have the Monitoring Metric Writer(roles/monitoring.metricWriter) IAM role.The Kubernetes ServiceAccountdefault in the namespaceconfig-management-monitoring should bebound to the GSA.

     • DIRECTORY: the path of the directory to sync from,relative to the root of the Git repository. All sub-directories of thedirectory that you specify are included and synced to the cluster. Thedefault value is the root directory of the repository.

   For a complete list of fields that you can add to thespec field,seegcloud fields.

   Note: If you don't have a source of truth prepared yet, you can enableConfig Sync without configuring any settings by settingspec.configSync.enabled totrue and omitting all otherspec.configSync fields. When you have prepared your repository, edityourapply-spec.yaml to add the configuration settings.

3. Apply theapply-spec.yaml file. If you are using an existing manifest,you should apply the file to the cluster that you want toconfigure with the settings that you fetched in the previous command:

   gcloudbetacontainerfleetconfig-managementapply\--membership=MEMBERSHIP_NAME\--config=CONFIG_YAML_PATH\--project=PROJECT_ID

   Replace the following:

   • MEMBERSHIP_NAME: the fleet membership name that you chosewhen you registered your cluster. You can find the name withgcloud container fleet memberships list.
   • CONFIG_YAML_PATH: the path to yourapply-spec.yaml file.
   • PROJECT_ID: your project ID.

Terraform

For each cluster that you want to configure Config Sync,apply agoogle_gkehub_feature_membership resource block that containsaconfigmanagement andconfig_sync block, such as in the following example:

data "google_project" "default" {}resource "google_container_cluster" "default" {  name     = "gke-autopilot-basic"  location = "us-central1"  fleet {    project = data.google_project.default.project_id  }  enable_autopilot = true}resource "google_gke_hub_feature" "configmanagement_feature" {  name     = "configmanagement"  location = "global"}resource "google_gke_hub_feature_membership" "configmanagement_feature_member" {  location = "global"  feature             = google_gke_hub_feature.configmanagement_feature.name  membership          = google_container_cluster.default.fleet[0].membership_id  membership_location = google_container_cluster.default.fleet[0].membership_location  configmanagement {    config_sync {      # The field `enabled` was introduced in Terraform version 5.41.0, and      # needs to be set to `true` explicitly to install Config Sync.      enabled = true      git {        sync_repo   = "REPO"        sync_branch = "BRANCH"        policy_dir  = "DIRECTORY"        secret_type = "SECRET"      }    }  }}

data "google_project" "default" {}resource "google_container_cluster" "default" {  name     = "gke-autopilot-basic"  location = "us-central1"  fleet {    project = data.google_project.default.project_id  }  enable_autopilot = true}resource "google_gke_hub_feature" "configmanagement_feature" {  name     = "configmanagement"  location = "global"}resource "google_gke_hub_feature_membership" "configmanagement_feature_member" {  location = "global"  feature             = google_gke_hub_feature.configmanagement_feature.name  membership          = google_container_cluster.default.fleet[0].membership_id  membership_location = google_container_cluster.default.fleet[0].membership_location  configmanagement {    config_sync {      # The field `enabled` was introduced in Terraform version 5.41.0, and      # needs to be set to `true` explicitly to install Config Sync.      enabled = true      oci {        sync_repo   = "REPO"        policy_dir  = "DIRECTORY"        secret_type = "SECRET"      }    }  }}

Repeat this process for each cluster that you want to sync.

For more information about using Terraform, seeTerraform support forConfig Sync.

gcloud

Run the following command:

nomosstatus

A successful installation shows a status ofSYNCED orPENDING.

For more details about the information supplied bynomos status, includingreported errors, seeCheck Config Sync statusin thenomos command-line tool documentation.

console

Complete the following steps:

1. In the Google Cloud console, go to theConfig page under theFeatures section.

   Go to Config

2. On thePackages tab, check theSync status column in the cluster table.A successful installation of Config Sync has a status ofInstalled.A successfully configured source of truth has a status ofSynced.