Install Config Sync

SSH key pair

An SSH key pair consists of two files, a public key and a private key. The public key typically has a .pub extension.

To use an SSH key pair, complete the following steps:

1. Create an SSH key pair to allow Config Sync to authenticate to your Git repository. This step is necessary if you need to authenticate to the repository to clone it or read from it. Skip this step if a security administrator provides you with a key pair. You can use a single key pair for all clusters, or a key pair per cluster, depending on your security and compliance requirements.

   The following command creates a 4096-bit RSA key. Lower values are not recommended:

   ssh-keygen -t rsa -b 4096 \
   -C "GIT_REPOSITORY_USERNAME" \
   -N '' \
   -f /path/to/KEYPAIR_FILENAME
   

   Replace the following:

   • GIT_REPOSITORY_USERNAME: the username that you want Config Sync to use to authenticate to the repository
   • /path/to/KEYPAIR_FILENAME: a path to the key pair

   If you are using a third-party Git repository host such as GitHub, or you want to use a service account with Cloud Source Repositories, we recommend that you use a separate account.

2. Configure your repository to recognize the newly created public key. Refer to the documentation for your Git hosting provider. Instructions for some popular Git hosting providers are included for convenience:

   • Cloud Source Repositories
   • Bitbucket
   • GitHub We recommend that you create separate deploy keys to provide read-only access to a single GitHub repository.
   • GitLab

3. Add the private key to a new Secret in the cluster:

   kubectl create ns config-management-system && \
   kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-file=ssh=/path/to/KEYPAIR_PRIVATE_KEY_FILENAME
   

   Replace /path/to/KEYPAIR_PRIVATE_KEY_FILENAME with the name of the private key (the one without the .pub suffix).

4. (Recommended) To configure known hosts checking using SSH authentication, you can add the known hosts key to the data.known_hosts field in the git_creds secret. To disable known_hosts checking, you can remove the known_hosts field from the secret. To add the known hosts key, run:

   kubectl edit secret git-creds \
    --namespace=config-management-system
   

   Then, under data, add the known hosts entry:

   known_hosts: KNOWN_HOSTS_KEY
   

5. Delete the private key from the local disk or otherwise protect it.

6. When you configure Config Sync and add the URL for your Git repository, use the SSH protocol. If you are using a repository in Cloud Source Repositories, you must use the following format when you enter your URL:

   ssh://EMAIL@source.developers.google.com:2022/p/PROJECT_ID/r/REPO_NAME
   

   Replace the following:

   • EMAIL: your Google Cloud username
   • PROJECT_ID: the ID of the Google Cloud project where the repository is located
   • REPO_NAME: the name of the repository

Cookiefile

The process for acquiring a cookiefile depends on the configuration of your repository. For an example, see Generate static credentials in the Cloud Source Repositories documentation. The credentials are usually stored in the .gitcookies file in your home directory, or they might be provided to you by a security administrator.

To use a cookiefile, complete the following steps:

1. After you create and obtain the cookiefile, add it to a new Secret in the cluster.

   If you don't use an HTTPS proxy, create the Secret with the following command:

   kubectl create ns config-management-system && \
   kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-file=cookie_file=/path/to/COOKIEFILE
   

   If you need to use an HTTPS proxy, add it to the Secret together with cookiefile by running the following command:

   kubectl create ns config-management-system && \
   kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-file=cookie_file=/path/to/COOKIEFILE \
    --from-literal=https_proxy=HTTPS_PROXY_URL
   

   Replace the following:

   • /path/to/COOKIEFILE: the appropriate path and filename
   • HTTPS_PROXY_URL: the URL for the HTTPS proxy that you use when communicating with the Git repository

2. Protect the contents of the cookiefile if you still need it locally. Otherwise, delete it.

Token

If your organization does not permit the use of SSH keys, you might prefer to use a token. With Config Sync, you can use GitHub's personal access tokens (PATs), GiLab's PATs or deploy keys, or Bitbucket's app password as your token.

To create a Secret using your token, complete the following steps:

1. Create a token using GitHub, GitLab, or Bitbucket:

   • GitHub: Create a PAT. Grant the token the repo scope so that it can read from private repositories. Because you bind a PAT to a GitHub account, we also recommend that you create a machine user and bind your PAT to the machine user.
   • GitLab: Create a PAT or create a deploy token
   • Bitbucket: Create an app password.

2. After you create and obtain the token, add it to a new Secret in the cluster.

   If you don't use an HTTPS proxy, create the Secret with the following command:

   kubectl create ns config-management-system && \
   kubectl create secret generic git-creds \
     --namespace="config-management-system" \
     --from-literal=username=USERNAME \
     --from-literal=token=TOKEN
   

   Replace the following:

   • USERNAME: the username that you want to use.
   • TOKEN: the token that you created in the previous step.

   If you need to use an HTTPS proxy, add it to the Secret together with username and token by running the following command:

   kubectl create ns config-management-system && \
   kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-literal=username=USERNAME \
     --from-literal=token=TOKEN \
    --from-literal=https_proxy=HTTPS_PROXY_URL
   

   Replace the following:

   • USERNAME: the username that you want to use.
   • TOKEN: the token that you created in the previous step.
   • HTTPS_PROXY_URL: the URL for the HTTPS proxy that you use when communicating with the Git repository.

3. Protect the token if you still need it locally. Otherwise, delete it.

Google service account

If your repository is in Cloud Source Repositories, and your cluster uses GKE Workload Identity Federation for GKE or fleet Workload Identity Federation for GKE, you can give Config Sync access to a repository in the same project as your managed cluster by using a Google service account.

1. If you don't already have a service account, create a service account.

2. Grant the Cloud Source Repositories Reader (roles/source.reader) IAM role to the Google service account. For more information about Cloud Source Repositories roles and permissions, see Grant permissions to view repositories.

   • Grant project-wide permission if the same permissions apply to all repositories in the project.

     gcloud projects add-iam-policy-binding PROJECT_ID \
       --role=roles/source.reader \
       --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"
     

   • Grant repository-specific permission when you want service accounts to have different levels of access for each repository in your project.

     gcloud source repos set-iam-policy REPOSITORY POLICY_FILE --project=PROJECT_ID
     

3. If you configure Config Sync using the Google Cloud console, select Workload Identity Federation for GKE as the Authentication Type and then add your service account email.

   If you configure Config Sync using the Google Cloud CLI, add gcpserviceaccount as the secretType and then add your service account email to gcpServiceAccountEmail.

4. After configuring Config Sync, create an IAM policy binding between the Kubernetes service account and the Google service account. The Kubernetes service account is not created until you configure Config Sync for the first time.

   If you are using clusters that are registered to a fleet, you only have to create the policy binding once per fleet. All clusters registered in a fleet share the same Workload Identity Federation for GKEpool. With fleet's concept of sameness, if you add the IAM policy to your Kubernetes service account in one cluster, then the Kubernetes service account from the same namespace on other clusters in the same fleet also get the same IAM policy.

   This binding lets the Config Sync Kubernetes service account act as the Google service account:

   gcloud iam service-accounts add-iam-policy-binding \
       GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --role=roles/iam.workloadIdentityUser \
       --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
       --project=PROJECT_ID
   

Replace the following:

• PROJECT_ID: the organization's project ID.
• FLEET_HOST_PROJECT_ID: if you're using GKE Workload Identity Federation for GKE, this is the same as PROJECT_ID. If you're using fleet Workload Identity Federation for GKE, this is the project ID of the fleet that your cluster is registered to.
• GSA_NAME: the custom Google service account that you want to use to connect to Artifact Registry. The service account must have the Artifact Registry Reader (roles/artifactregistry.reader) IAM role.
• KSA_NAME: the Kubernetes service account for the reconciler.
  • For root repositories, if the RootSync name is root-sync, use root-reconciler. Otherwise, use root-reconciler-ROOT_SYNC_NAME. If you install Config Sync using the Google Cloud console or the Google Cloud CLI, Config Sync automatically creates a RootSync object named root-sync.
• REPOSITORY: the name of the repository.
• POLICY_FILE: the JSON or YAML file with the Identity and Access Management policy.

Compute Engine default service account

If your repository is in Cloud Source Repositories, and your cluster is GKE with Workload Identity Federation for GKE disabled, you can use gcenode as your authentication type.

If you configure Config Sync using the Google Cloud console, select Google Cloud Repository as the Authentication Type.

If you configure Config Sync using the Google Cloud CLI, add gcenode as the secretType.

Selecting either Google Cloud Repository or gcenode lets you use the Compute Engine default service account. You must grant the Cloud Source Repositories Reader (roles/source.reader) IAM role to the Compute Engine default service account. For more information about Cloud Source Repositories roles and permissions, see Grant permissions to view repositories.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com"

Replace PROJECT_ID with your organization's project ID, and replace PROJECT_NUMBER with your organization's project number.

GitHub App

If your repository is in GitHub, you can use githubapp as your authentication type.

To use a GitHub App, complete the following steps:

1. Follow the instructions on GitHub to provision a GitHub App and give it permission to read from your repository.

2. Add the GitHub App configuration to a new Secret in the cluster:

   Using Client ID

   kubectl create ns config-management-system && \
   kubectl create secret generic git-creds \
     --namespace=config-management-system \
     --from-literal=github-app-client-id=CLIENT_ID \
     --from-literal=github-app-installation-id=INSTALLATION_ID \
     --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
     --from-literal=github-app-base-url=BASE_URL
   

   • Replace CLIENT_ID with the client ID for the GitHub App.
   • Replace INSTALLATION_ID with the installation ID for the GitHub App.
   • Replace /path/to/GITHUB_PRIVATE_KEY with the name of the file containing the private key.
   • Replace BASE_URL with the base URL for the GitHub API endpoint. This is only needed when the repository is not hosted at www.github.com. The argument can otherwise be omitted and will default to https://api.github.com/.

   Using Application ID

   kubectl create ns config-management-system && \
   kubectl create secret generic git-creds \
     --namespace=config-management-system \
     --from-literal=github-app-application-id=APPLICATION_ID \
     --from-literal=github-app-installation-id=INSTALLATION_ID \
     --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
     --from-literal=github-app-base-url=BASE_URL
   

   • Replace APPLICATION_ID with the application ID for the GitHub App.
   • Replace INSTALLATION_ID with the installation ID for the GitHub App.
   • Replace /path/to/GITHUB_PRIVATE_KEY with the name of the file containing the private key.
   • Replace BASE_URL with the base URL for the GitHub API endpoint. This is only needed when the repository is not hosted at www.github.com. The argument can otherwise be omitted and will default to https://api.github.com/.

3. Delete the private key from the local disk or otherwise protect it.

4. When you configure Config Sync and add the URL for your Git repository, use the githubapp auth type.

Kubernetes service account

If you store your OCI image in Artifact Registry and your cluster uses GKE Workload Identity Federation for GKE or fleet Workload Identity Federation for GKE, you can use k8sserviceaccount as your authentication type in version 1.17.2 and later. This option is recommended over gcpserviceaccount due to its simplified configuration process.

1. Grant the Artifact Registry Reader (roles/artifactregistry.reader) IAM role to the Kubernetes service account with the Workload Identity Federation for GKE pool. For more information about Artifact Registry roles and permissions, see Configure roles and permissions for Artifact Registry.

   • Grant project-wide permission if the same permissions apply to all repositories in the project.

     gcloud projects add-iam-policy-binding PROJECT_ID \
           --role=roles/artifactregistry.reader \
           --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]"
     

   • Grant repository-specific permission when you want service accounts to have different levels of access for each repository in your project.

     gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
        --location=LOCATION \
        --role=roles/artifactregistry.reader \
        --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
        --project=PROJECT_ID
     

   Replace the following:

   • PROJECT_ID: the organization's project ID.
   • FLEET_HOST_PROJECT_ID: if you're using GKE Workload Identity Federation for GKE, this is the same as PROJECT_ID. If you're using fleet Workload Identity Federation for GKE, this is the project ID of the fleet that your cluster is registered to.
   • KSA_NAME: the Kubernetes service account for the reconciler.
     • For root repositories, if the RootSync name is root-sync, use root-reconciler. Otherwise, use root-reconciler-ROOT_SYNC_NAME. If you install Config Sync using the Google Cloud console or the Google Cloud CLI, Config Sync automatically creates a RootSync object named root-sync.
   • REPOSITORY: the ID of the repository.
   • LOCATION: the regional or multi-regional location of the repository.

Google service account

If you store your OCI image in Artifact Registry and your cluster uses GKE Workload Identity Federation for GKE or fleet Workload Identity Federation for GKE, you can use gcpserviceaccount as your authentication type. Starting from version 1.17.2, it's recommended to use k8sserviceaccount instead. This option eliminates the extra steps of creating a Google service account and the associated IAM policy binding.

1. If you don't already have a service account, create a service account.

2. Grant the Artifact Registry Reader (roles/artifactregistry.reader) IAM role to the Google service account. For more information about Artifact Registry roles and permissions, see Configure roles and permissions for Artifact Registry.

   • Grant project-wide permission if the same permissions apply to all repositories in the project.

     gcloud projects add-iam-policy-binding PROJECT_ID  \
        --role=roles/artifactregistry.reader \
        --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"
     

   • Grant repository-specific permission when you want service accounts to have different levels of access for each repository in your project.

     gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
        --location=LOCATION \
        --role=roles/artifactregistry.reader \
        --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
        --project=PROJECT_ID
     

3. Create an IAM policy binding between the Kubernetes service account and the Google service account by running the following command:

   gcloud iam service-accounts add-iam-policy-binding
     GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --role=roles/iam.workloadIdentityUser \
       --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
       --project=PROJECT_ID
   

Replace the following:

• PROJECT_ID: the organization's project ID.
• FLEET_HOST_PROJECT_ID: if you're using GKE Workload Identity Federation for GKE, this is the same as PROJECT_ID. If you're using fleet Workload Identity Federation for GKE, this is the project ID of the fleet that your cluster is registered to.
• GSA_NAME: the custom Google service account that you want to use to connect to Artifact Registry. The service account must have the Artifact Registry Reader (roles/artifactregistry.reader) IAM role.
• KSA_NAME: the Kubernetes service account for the reconciler.
  • For root repositories, if the RootSync name is root-sync, use root-reconciler. Otherwise, use root-reconciler-ROOT_SYNC_NAME. If you install Config Sync using the Google Cloud console or the Google Cloud CLI, Config Sync automatically creates a RootSync object named root-sync.
• REPOSITORY: the ID of the repository.
• LOCATION: the regional or multi-regional location of the repository.

Compute Engine default service account

If you store your Helm chart in Artifact Registry and your cluster is GKE with Workload Identity Federation for GKE disabled, you can use gcenode as your authentication type. Config Sync uses the Compute Engine default service account. You must grant your Compute Engine default service account reader access to Artifact Registry.

1. Grant the Compute Engine service account read permission to Artifact Registry by running the following command:

   gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
      --role=roles/artifactregistry.reader
   

   Replace PROJECT_ID with your organization's project ID, and replace PROJECT_NUMBER with your organization's project number.

Token

Create a Secret with a Helm repository username and password:

kubectl create secret generic SECRET_NAME \
    --namespace=config-management-system \
    --from-literal=username=USERNAME \
    --from-literal=password=PASSWORD

Replace the following:

• SECRET_NAME: the name that you want to give your Secret.
• USERNAME: the Helm repository username.
• PASSWORD: the Helm repository password.

When you Configure Config Sync, you will use the Secret name you chose for spec.helm.secretRef.name.

Kubernetes service account

If you store your Helm chart in Artifact Registry and your cluster uses GKE Workload Identity Federation for GKE or fleet Workload Identity Federation for GKE, you can use k8sserviceaccount as your authentication type in version 1.17.2 and later. This option is recommended over gcpserviceaccount due to its simplified configuration process.

1. Grant the Artifact Registry Reader (roles/artifactregistry.reader) IAM role to the Kubernetes service account with the Workload Identity Federation for GKE pool. For more information about Artifact Registry roles and permissions, see Configure roles and permissions for Artifact Registry.

   • Grant project-wide permission if the same permissions apply to all repositories in the project.

     gcloud projects add-iam-policy-binding PROJECT_ID \
        --role=roles/artifactregistry.reader \
        --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]"
     

   • Grant repository-specific permission when you want service accounts to have different levels of access for each repository in your project.

     gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
        --location=LOCATION \
        --role=roles/artifactregistry.reader \
        --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
        --project=PROJECT_ID
     

   Replace the following:

   • PROJECT_ID: the organization's project ID.
   • FLEET_HOST_PROJECT_ID: if you're using GKE Workload Identity Federation for GKE, this is the same as PROJECT_ID. If you're using fleet Workload Identity Federation for GKE, this is the project ID of the fleet that your cluster is registered to.
   • KSA_NAME: the Kubernetes service account for the reconciler.
     • For root repositories, if the RootSync name is root-sync, use root-reconciler. Otherwise, use root-reconciler-ROOT_SYNC_NAME.
   • REPOSITORY: the ID of the repository.
   • LOCATION: the regional or multi-regional location of the repository.

Google service account

If you store your Helm chart in Artifact Registry and your cluster uses GKE Workload Identity Federation for GKE or fleet Workload Identity Federation for GKE, you can use gcpserviceaccount as your authentication type. Starting from version 1.17.2, it's recommended to use k8sserviceaccount instead. This option eliminates the extra steps of creating a Google service account and the associated IAM policy binding.

1. If you don't already have a service account, create a service account.

2. Grant the Artifact Registry Reader (roles/artifactregistry.reader) IAM role to the Google service account. For more information about Artifact Registry roles and permissions, see Configure roles and permissions for Artifact Registry.

   • Grant project-wide permission if the same permissions apply to all repositories in the project.

     gcloud projects add-iam-policy-binding PROJECT_ID  \
           --role=roles/artifactregistry.reader \
           --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"
     

   • Grant repository-specific permission when you want service accounts to have different levels of access for each repository in your project.

     gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
        --location=LOCATION \
        --role=roles/artifactregistry.reader \
        --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
        --project=PROJECT_ID
     

3. Create an IAM policy binding between the Kubernetes service account and the Google service account by running the following command:

   gcloud iam service-accounts add-iam-policy-binding
     GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --role=roles/iam.workloadIdentityUser \
       --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]"
       --project=PROJECT_ID
   

Replace the following:

• PROJECT_ID: the organization's project ID.
• FLEET_HOST_PROJECT_ID: if you're using GKE Workload Identity Federation for GKE, this is the same as PROJECT_ID. If you're using fleet Workload Identity Federation for GKE, this is the project ID of the fleet that your cluster is registered to.
• GSA_NAME: the custom Google service account that you want to use to connect to Artifact Registry. The service account must have the Artifact Registry Reader (roles/artifactregistry.reader) IAM role.
• KSA_NAME: the Kubernetes service account for the reconciler.
  • For root repositories, if the RootSync name is root-sync, use root-reconciler. Otherwise, use root-reconciler-ROOT_SYNC_NAME.
• REPOSITORY: the ID of the repository.
• LOCATION: the regional or multi-regional location of the repository.

Compute Engine default service account

If you store your Helm chart in Artifact Registry and your cluster is GKE with Workload Identity Federation for GKE disabled, you can use gcenode as your authentication type. Config Sync uses the Compute Engine default service account. You must grant your Compute Engine default service account reader access to Artifact Registry. You might need to grant the storage-ro access scope to grant read-only permission to pull images.

1. Grant the Compute Engine service account read permission to Artifact Registry:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
       --role=roles/artifactregistry.reader
   

   Replace PROJECT_ID with your organization's project ID, and replace PROJECT_NUMBER with your organization's project number.

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 individual clusters automatically registers those clusters to your fleet.

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

   Go to Config

2. Click add Install Config Sync.
3. Select Auto-upgrades (Preview) to enable Config Sync to upgrade versions automatically or select Manual upgrades to manage the Config Sync version yourself. For more information about how auto-upgrades work, see Upgrade Config Sync.
4. Under Installation options, select one of the following options:
   • Install Config Sync on entire fleet (recommended): Config Sync will be installed on all clusters in the fleet.
   • Install Config Sync on individual clusters: all selected clusters will be automatically registered to a fleet. Config Sync will be installed on all clusters in the fleet.
5. If you're installing Config Sync on individual clusters, in the Available clusters table, select the clusters on which you want to install Config Sync.
6. Click Install Config Sync. In the Settings tab, after a few minutes, you should see Enabled in the Status 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 a source of truth. You can deploy the same package to multiple clusters or deploy different packages to different clusters. You can edit a package after deploying it, except for some settings like package name and sync type. For more information, see Manage packages.

To deploy a package, complete the following steps:

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

   Go to Config Sync dashboard

2. Click Deploy Package.

3. In the Select clusters for package deployment table, select the cluster that you want to deploy a package to and then click Continue.

4. Select either Package hosted on Git or Package hosted on OCI as your source type and then click Continue.

5. In the Package details section, enter a Package name, which identifies the RootSync or RepoSync object.

6. In the Sync type field, choose either Cluster scoped sync or Namespace scoped sync as the sync type.

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

7. In the Source 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 truth as the Repository URL.
     2. Optional: Update the Revision field to check out if you're not using the default HEAD.
     3. Optional: Update the Path field if you don't want to sync from the root repository.
     4. Optional: Update the Branch field if you're not using the default main 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 truth as the Image.
     2. Enter the path of the directory to sync from, relative to the root directory, as the Directory.

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

   1. Select an Authentication type. Config Sync needs read-only access to your 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 Sync read-only access to your Git repository, OCI image, or Helm chart (gcloud CLI only). Choose the same authentication type that you configured when you installed Config Sync:

      • None: Use no authentication.
      • SSH: Authenticate by using an SSH key pair.
      • Cookiefile: Authenticate by using a cookiefile.
      • Token: Authenticate by using an access token or password.
      • Google Cloud Repository: Use a Google service account to access a Cloud Source Repositories repository. Only select this option if Workload Identity Federation for GKE is not enabled in your cluster.
      • Workload Identity: Use a Google service account to access a Cloud Source Repositories repository.

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

   3. Enter a Git proxy URL for the HTTPS proxy to be used when communicating with the source of truth.

   4. Choose Hierarchy to change the Source format.

      The default value Unstructured is recommended in most cases since it lets you organize your source of truth however you want.

9. Click Deploy Package.

   You are redirected to the Config Sync Packages page. After a few minutes, you should see Synced in the Sync status column for the cluster that you configured.

gcloud

Before you continue, make sure you've registered your clusters to a fleet.

1. Enable the ConfigManagement fleet feature:

   gcloud beta container fleet config-management enable
   

2. Prepare the configuration by either creating a new apply-spec.yaml manifest or by using an existing manifest. Using an existing manifest lets you configure your cluster with the same settings used by another cluster.

   Create new manifest

   To configure Config Sync with new settings for your cluster, create a file named apply-spec.yaml and copy the following YAML file into it.

   You can set all of the optional spec.configSync fields that you need when you create your manifest, and later use kubectl commands for configuration. You can also only set the spec.configSync.enabled field as true and omit the optional fields. You can then later use kubectl commands to create additional RootSync objects or RepoSyncs that you can fully manage using kubectl commands later.

   # apply-spec.yaml
   
   applySpecVersion: 1
   spec:
     # upgrades: UPGRADE_SETTING
     configSync:
       # Set to true to install and enable Config Sync
       enabled: true
       # If you don't have a source of truth yet, omit the
       # following fields. You can configure them later.
       sourceType: SOURCE_TYPE
       sourceFormat: FORMAT
       syncRepo: REPO
       syncRev: REVISION
       syncBranch: BRANCH
       secretType: SECRET_TYPE
       gcpServiceAccountEmail: EMAIL
       metricsGcpServiceAccountEmail: METRICS_EMAIL
       policyDir: DIRECTORY
       preventDrift: PREVENT_DRIFT
   

   Replace the following:

   • (Preview) UPGRADE_SETTING: un-comment the field and set to auto to configure Config Sync to automatically upgrade. Set to manual to manually upgrade Config Sync yourself. The default value is manual. This flag is supported only for GKE on Google Cloud clusters. To use this field, you might need to update the gcloud CLI by running gcloud components update.

   • SOURCE_TYPE: add git to sync from a Git repository, oci to sync from an OCI image, or helm to sync from a Helm chart. If no value is specified, the default is git.

   • FORMAT: add unstructured to use an unstructured repository or add hierarchy to use a hierarchical repository. These values are case-sensitive. This field is optional and the default value is hierarchy. We recommend that you add unstructured, because this format lets you organize your configs in the way that is most convenient to you.

   • REPO: add the URL of the source of truth. Git and Helm repository URLs use either the HTTPS or SSH protocol. For example, https://github.com/GoogleCloudPlatform/anthos-config-management-samples. If you plan to use SSH as your secretType, enter your URL with the SSH protocol. This field is required and if you don'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 the latest tag, but you can pull in images by TAG or DIGEST instead. Specify TAG or DIGEST in the PACKAGE_NAME:

     • To pull by TAG: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME:TAG
     • To pull by DIGEST: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME@sha256:DIGEST

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

   • SECRET_TYPE: one of the following secretTypes:

     git

     • none: Use no authentication.
     • ssh: Use an SSH key pair.
     • cookiefile: Use a cookiefile.
     • token: Use a token.
     • gcpserviceaccount: Use a Google service account to access a Cloud Source Repositories. If you select this authentication type, you need to create an IAM policy binding after you finish configuring Config Sync. For details, see the Google service account tab of the Grant Config Sync read-only access to Git section.
     • gcenode: Use a Google service account to access a Cloud Source Repositories. Only select this option if Workload Identity Federation for GKE is not enabled in your cluster.
     • githubapp: Use a GitHub App to authenticate to a GitHub repository.

     For more information on these authentication types, see Granting Config Sync read-only access to Git.

     oci

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

     helm

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

   • EMAIL: If you added gcpserviceaccount as your secretType, add your Google service account email address. For example, acm@PROJECT_ID.iam.gserviceaccount.com.

   • METRICS_EMAIL: the email of the Google Cloud Service Account (GSA) used for exporting Config Sync metrics to Cloud Monitoring. The GSA should have the Monitoring Metric Writer (roles/monitoring.metricWriter) IAM role. The Kubernetes ServiceAccount default in the namespace config-management-monitoring should be bound to the GSA.

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

   • PREVENT_DRIFT: If set to true, enables the Config Sync admission webhook to prevent drifts by rejecting conflicting changes from being pushed to live clusters. The default setting is false. Config Sync always remediates drifts no matter the value of this field.

   For a complete list of fields that you can add to the spec field, see gcloud fields.

   Use existing manifest

   To configure your cluster with the same settings used by another cluster, fetch the settings from a registered cluster:

   gcloud alpha container fleet config-management fetch-for-apply \
       --membership=MEMBERSHIP_NAME \
       --project=PROJECT_ID \
       > CONFIG_YAML_PATH
   

   Replace the following:

   • MEMBERSHIP_NAME: the membership name of the registered cluster that has the Config Sync settings you want to use
   • PROJECT_ID: your project ID
   • CONFIG_YAML_PATH: the path to the apply-spec.yaml file which contains the settings fetched from the cluster

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

   gcloud beta container fleet config-management apply \
       --membership=MEMBERSHIP_NAME \
       --config=CONFIG_YAML_PATH \
       --project=PROJECT_ID
   

   Replace the following:

   • MEMBERSHIP_NAME: the fleet membership name that you chose when you registered your cluster. You can find the name with gcloud container fleet memberships list.
   • CONFIG_YAML_PATH: the path to your apply-spec.yaml file.
   • PROJECT_ID: your project ID.

Terraform

For each cluster that you want to configure Config Sync, apply a google_gkehub_feature_membership resource block that contains a configmanagement and config_sync block:

resource "google_container_cluster" "cluster" {
 name = "EXISTING_CLUSTER_NAME"
 location = "EXISTING_CLUSTER_LOCATION"
}

resource "google_gke_hub_membership" "membership" {
 membership_id = "MEMBERSHIP_ID"
 endpoint {
   gke_cluster {
     resource_link = "//container.googleapis.com/${google_container_cluster.cluster.id}"
   }
 }
}

resource "google_gke_hub_feature" "feature" {
 name = "configmanagement"
 location = "global"
}

resource "google_gke_hub_feature_membership" "feature_member" {
 location = "global"
 feature = google_gke_hub_feature.feature.name
 membership = google_gke_hub_membership.membership.membership_id
 configmanagement {
   version = "VERSION"
   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"
     }
   }
 }
}

resource "google_container_cluster" "cluster" {
 name = "EXISTING_CLUSTER_NAME"
 location = "EXISTING_CLUSTER_LOCATION"
}

resource "google_gke_hub_membership" "membership" {
 membership_id = "MEMBERSHIP_ID"
 endpoint {
   gke_cluster {
     resource_link = "//container.googleapis.com/${google_container_cluster.cluster.id}"
   }
 }
}

resource "google_gke_hub_feature" "feature" {
 name = "configmanagement"
 location = "global"
}

resource "google_gke_hub_feature_membership" "feature_member" {
 location = "global"
 feature = google_gke_hub_feature.feature.name
 membership = google_gke_hub_membership.membership.membership_id
 configmanagement {
   version = "VERSION"
   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.

gcloud

Run the enable command for the feature, passing the apply-spec.yaml configuration file that you created when you configured Config Sync on an individual cluster:

gcloud beta container fleet config-management enable \
    --fleet-default-member-config=apply-spec.yaml

You can use this command to update your fleet default settings at any time. If you update your fleet default settings, you must re-sync your existing clusters to the default settings.

Console

1. In the Google Cloud console, go to the Feature Manager page.

   Go to Feature Manager

2. In the Config Sync pane, click Configure.

3. Review your fleet-level settings. All new clusters you create in the fleet inherit these settings.

4. Optional: To change the default settings, click Customize fleet settings. In the dialog that appears, do the following:

5. Select Auto-upgrades (Preview) to have Config Sync upgrade versions automatically or select Manual upgrades to manage the Config Sync version yourself. For more information about how auto-upgrades work, see Upgrade Config Sync.

6. If you selected Manual upgrades, in the Version list, select the Config Sync version that you want to use.

7. Click Save changes.

8. Click Configure.

9. In the Configuring fleet settings confirmation dialog, click Confirm. If you haven't previously enabled Config Sync, clicking Confirm also enables the anthosconfigmanagement.googleapis.com API.

Terraform

1. Create a directory for the fleet-default configuration Terraform files. To that directory, add a main.tf file with the following resource that configures Config Sync's settings:

   git

   terraform {
     required_providers {
       google = {
         source = "hashicorp/google"
         version = ">=5.16.0"
         }
       }
     }
   
   provider "google" {
     project = "PROJECT_ID"
   }
   
   resource "google_gke_hub_feature" "feature" {
     name = "configmanagement"
     location = "global"
     provider = google
     fleet_default_member_config {
       configmanagement {
       version = "VERSION"
       config_sync {
       source_format = "unstructured"
         git {
           sync_repo = "REPO"
           sync_branch = "BRANCH"
           policy_dir = "DIRECTORY"
           secret_type = "SECRET"
         }
       }
       }
     }
   }
   

   Replace the following:

   • PROJECT_ID: the fleet host project ID.
   • VERSION: (optional) the Config Sync version number. If left blank, the default is the latest version.
   • REPO: the URL to the repository containing your configuration files.
   • BRANCH: the repository branch, for example main.
   • DIRECTORY: the path within the Git repository that represents the top level of the repository you want to sync.
   • SECRET: the secret auth type.

   For a full list of settings supported in the Config Sync git block, see the Terraform reference documentation for GKE hub features.

   OCI

   terraform {
     required_providers {
       google = {
         source = "hashicorp/google"
         version = ">=5.16.0"
         }
       }
     }
   
   provider "google" {
     project = "PROJECT_ID"
   }
   
   resource "google_gke_hub_feature" "feature" {
     name = "configmanagement"
     location = "global"
     provider = google
     fleet_default_member_config {
       configmanagement {
       version = "VERSION"
       config_sync {
       source_format = "unstructured"
         oci {
           sync_repo = "REPO"
           policy_dir = "DIRECTORY"
           secret_type = "SECRET"
         }
       }
       }
     }
   }
   

   Replace the following:

   • PROJECT_ID: the fleet host project ID.
   • VERSION: the Config Sync version number. If left blank, the default is the latest version.
   • REPO: the URL to the OCI image repository containing configuration files.
   • DIRECTORY: the absolute path of the directory containing the resources you want to sync. Leave blank to use the root directory.
   • SECRET: the secret auth type.

   For a full list of settings supported in the Config Sync oci block, see the Terraform reference documentation for GKE hub features.

2. Initialize Terraform in the directory that you created:

   terraform init
   

3. Check that the changes you propose with Terraform match the expected plan:

   terraform plan
   

4. Create the default fleet member configurations:

   terraform apply
   

gcloud

1. Sync an existing membership to the fleet default configuration:

   gcloud beta container fleet config-management apply \
       --origin=FLEET \
       --membership=MEMBERSHIP_NAME
   

   Replace MEMBERSHIP_NAME with the fleet membership name of the cluster that you want to sync with the fleet default configuration.

2. Confirm that your membership configurations are synced with the fleet default:

   gcloud beta container fleet config-management status
   

   The output of this command should display as Yes for the Synced_to_Fleet_Default status for the membership that you synced.

console

1. Go to Feature Manager:

   Go to Feature Manager: Config Sync

2. In the cluster table, select the clusters that you want to sync to fleet settings.

3. Click Sync to fleet settings.

Console

Complete the following steps:

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

   Go to Config

2. On the Packages tab, check the Sync status column in the cluster table. A successful installation of Config Sync has a status of Installed. A successfully configured source of truth has a status of Synced.

gcloud

Run the following command:

gcloud beta container fleet config-management status \
    --project=PROJECT_ID

Replace PROJECT_ID with your project's ID.

A successful installation has a status of SYNCED. Starting in Config Sync version 1.18.0, the output also displays which version of Config Sync is installed and Config Sync's upgrade setting.

If you see an error after running the preceding command, make sure that you created the git-creds Secret. If you have created the Secret, try rerunning the following command:

gcloud beta container fleet config-management apply