Install Config Sync

With Config Sync, you can manage Kubernetes resources with configuration files stored in a source of truth. Config Sync supports Git repositories, OCI images, and Helm charts as a source of truth. This page shows you how to enable and configure Config Sync so that it syncs from your root repository. Config Sync is available with Google Kubernetes Engine (GKE) Enterprise edition.

When you install Config Sync using the Google Cloud console or the Google Cloud CLI, the RootSync and RepoSync APIs are enabled by default. This provides you with additional features such as syncing from multiple repositories and syncing Kustomize and Helm configurations.

Before you begin

Before you install Config Sync, prepare your environment, ensure you meet cluster requirements, and grant the right user roles.

Prepare your local environment

Prepare your local environment by completing the following tasks:

  1. Create, or make sure you have access to, a source of truth. This is where you add the configs that Config Sync syncs to. To learn more about how to set up your configs and source of truth, see one of the following guides:
  2. Install and initialize the Google Cloud CLI, which provides the gcloud, and nomos commands. If you use Cloud Shell, the Google Cloud CLI comes pre-installed.
  3. Enable the GKE Enterprise API.

    Enable GKE Enterprise API

Cluster requirements

Create, or make sure you have access to, a cluster that meets the following requirements:

  • Is on a Google Kubernetes Engine (GKE) Enterprise edition supported platform and version.
  • If you use Autopilot clusters, Autopilot adjusts the container resource requirements to meet the following rules:

    Due to these rules, for Autopilot clusters, Config Sync:

    • adjusts user-specified resource override limits to match requests.
    • only applies overrides when there exists one or more resource requests higher than the corresponding adjusted output declared in the annotation, or there exists one or more resource requests lower than the corresponding input declared in the annotation.
  • (Optional) has Workload Identity enabled if you use GKE clusters. Workload Identity is the recommended way to access Google Cloud services from applications running within GKE due to its improved security properties and manageability. If you enabled Workload Identity and want to enable Cloud Monitoring for Config Sync, you must grant the correct metric writing permissions.

  • If you want to use a private GKE cluster, configure the Cloud NAT to permit egress from private GKE nodes. For details, see Example GKE setup. Alternatively, you can enable Private Google Access to connect to the set of external IP addresses used by Google APIs and services.

  • If you want to use a Google service account when you grant Config Sync access to your source of truth, then you must include the read-only scope in access scopes for the nodes in the cluster for Cloud Source Repositories.

    You can add the read-only scope by including cloud-source-repos-ro in the --scopes list specified at cluster creation time, or by using the cloud-platform scope at cluster creation time. For example:

    gcloud container clusters create CLUSTER_NAME --scopes=cloud-platform
    

    You cannot modify access scopes after you create a node pool. However, you can create a new node pool with the proper access scope while using the same cluster. The default gke-default scope does not include cloud-source-repos-ro.

  • If you have strict VPC Firewall requirements that block any unnecessary traffic, you need to Create firewall rules to permit the following traffic on public GKE clusters:

    • TCP: Allow ingress and egress on port 53 and 443

    • UDP: Allow egress on port 53

    If you don't include these rules, Config Sync doesn't sync correctly, with nomos status reporting the following error:

    Error: KNV2004: unable to sync repo Error in the git-sync container

    You can skip these steps if using a private GKE cluster.

Prepare your cluster

After you have created a suitable cluster, complete the following steps:

  1. Grant the required IAM roles to the user registering the cluster.

  2. If you plan to use the Google Cloud CLI to configure Config Sync or use clusters outside Google Cloud, ensure that your GKE clusters or clusters outside of Google Cloud are registered to a fleet now. If you plan to use the Google Cloud console, you can register GKE clusters when you configure Config Sync.

Install Config Sync

In the following sections, you grant Config Sync access to one of the following sources of truth:

After you have granted access, you can configure Config Sync.

Grant access to Git

Config Sync needs read-only access to your Git repository so that it can read the configs committed to the repository and apply them to your clusters.

If your repository does not require authentication for read-only access, you can continue to configure Config Sync and use none as your authentication type. For example, if you can browse the repository using a web interface without logging in, or if you can use git clone to create a clone of the repository locally without providing credentials or using saved credentials, then you don't need to authenticate. In this case, you don't need to create a Secret.

However, most users need to create credentials because read access to their repository is restricted. If credentials are required, they are stored in the git-creds Secret on each enrolled cluster (unless you are using a Google service account). The Secret must be named git-creds because this is a fixed value.

Config Sync supports the following mechanisms for authentication:

  • SSH key pair (ssh)
  • Cookiefile (cookiefile)
  • Token (token)
  • Google service account (gcpserviceaccount)
  • Compute Engine default service account (gcenode)

The mechanism that you choose depends on what your repository supports. Generally, we recommend using an SSH key pair. GitHub and Bitbucket both support using an SSH key pair. However, if you are using a repository in Cloud Source Repositories, we recommend that you use a Google service account instead as the process is simpler. If your organization hosts your repository and you don't know which authentication methods are supported, contact your administrator.

To use a repository in Cloud Source Repositories as your Config Sync repository, complete the following steps to retrieve your Cloud Source Repositories URL:

  1. List all repositories:

    gcloud source repos list
    
  2. From the output, copy the URL from the repository that you want to use. For example:

    REPO_NAME  PROJECT_ID  URL
    my-repo    my-project  https://source.developers.google.com/p/my-project/r/my-repo-csr
    

    You need to use this URL when you configure Config Sync in the following section. If you configure Config Sync using the Google Cloud console, you add the URL in the URL field. If you configure Config Sync using the Google Cloud CLI, you add the URL to the syncRepo field of your configuration file.

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:

  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:

  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 or fleet Workload Identity, 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 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 Identitypool. 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, this is the same as PROJECT_ID. If you're using fleet Workload Identity, 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 on Google Cloud with Workload Identity 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.

Grant Config Sync read-only access to OCI

Config Sync needs read-only access to your OCI image stored in Artifact Registry so that it can read the configs included in the image and apply them to your clusters.

If your image does not require authentication for read-only access, you can continue to configure Config Sync and use none as your authentication type. For example, if your image is public and can be accessed by anyone on the internet, then you don't need to authenticate.

However, most users need to create credentials to access restricted images. Config Sync supports the following mechanisms for authentication:

  • Kubernetes service account (k8sserviceaccount)
  • Google service account (gcpserviceaccount)
  • Compute Engine default service account (gcenode)

Kubernetes service account

If you store your OCI image in Artifact Registry and your cluster uses GKE Workload Identity or fleet Workload Identity, 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 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, this is the same as PROJECT_ID. If you're using fleet Workload Identity, 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 or fleet Workload Identity, 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, this is the same as PROJECT_ID. If you're using fleet Workload Identity, 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 on Google Cloud with Workload Identity 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.

Grant Config Sync read-only access to Helm

Config Sync needs read-only access to your Helm repository so that it can read the Helm charts in your repository and install them in your clusters.

If your repository does not require authentication for read-only access, you can continue to configure Config Sync and use none as your authentication type. For example, if your Helm repository is public and can be accessed by anyone on the internet, then you don't need to authenticate.

However, most users need to create credentials to access private Helm repositories. Config Sync supports the following mechanisms for authentication:

  • Token (token)
  • Kubernetes service account (k8sserviceaccount)
  • Google service account (gcpserviceaccount)
  • Compute Engine default service account (gcenode)

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 the ConfigManagement Operator, 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 or fleet Workload Identity, 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 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, this is the same as PROJECT_ID. If you're using fleet Workload Identity, 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 or fleet Workload Identity, 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, this is the same as PROJECT_ID. If you're using fleet Workload Identity, 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 on Google Cloud with Workload Identity 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.

Configure Config Sync

In this section, you configure the settings for your root repository. If you're syncing to a Git repository, you can use the Google Cloud console to guide you through the installation process and automate some steps.

When you install Config Sync using the Google Cloud console or the Google Cloud CLI, Config Sync automatically creates a RootSync object named root-sync. You can use kubectl commands to modify root-sync and add additional Config Sync configurations. To learn more, see Configure Config Sync with kubectl commands.

Console

Install Config Sync

To use Config Sync, you must first register your clusters. Registering your clusters lets them share a common set of configurations and policies.

To register your clusters, complete the following tasks:

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

    Go to Config

  2. Click Install Config Sync.
  3. In the Available Clusters table, select the cluster that you want to register and then click Install Config Sync.

    After a few minutes, you should see Installed in the Config sync status column for the cluster that you selected.

Deploy a package

After you have registered your clusters, you can deploy a package from a source of truth to your Config Sync cluster. You can deploy a package to more than one cluster at a time, and add multiple packages to a single cluster.

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 Source section, complete the following:

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

      1. Enter a Package name, which identifies the RootSync or RepoSync object.
      2. Enter the URL of the Git repository that you're using as a source of truth as the Repository URL.
      3. Optional: Update the Revision field to check out if you're not using the default HEAD.
      4. Optional: Update the Path field if you don't want to sync from the root repository.
      5. 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.
  7. In the Sync type field, choose either RootSync or RepoSync as the sync type.

    RootSync objects are cluster-scoped and RepoSync object are namespace-scoped. For more information about these objects, see RootSync and RepoSync fields.

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

    1. Select an Authentication type:

      • None: Use no authentication.
      • SSH: Use an SSH key pair.
      • Cookiefile: Use a cookiefile.
      • Token: Use a token.
      • Google Cloud Repository: Use a Google service account to access a Cloud Source Repositories repository. Only select this option if Workload Identity 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 syncing 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.

  10. To update a package, on the Packages tab, expand the package name that you want to edit and then click Edit.

gcloud

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

  1. 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:
  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:

  • 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) to sync from. This field is optional and the default value is HEAD. Starting from Config Sync version 1.17.0, you can also specify a branch name in the syncRev field. When using a hash in version 1.17.0 or later, it must be a full hash, and not an abbreviated form.

  • BRANCH: the branch of the repository to sync from. This field is optional and the default is master. Starting from Config Sync version 1.17.0, it's recommended to use the syncRev field to specify a branch name for simplicity. If both the syncRev field and the syncBranch field are specified, syncRev takes precedence over syncBranch.

  • 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 is not enabled in your cluster.

    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 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 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

2. 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 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.

After you have finished configuring your root repository, you can optionally choose to configure syncing from multiple repositories, including other root repositories and namespace repositories. The namespace repositories are helpful if you want a repository that contains namespace-scoped configs synced to a particular namespace across clusters.

Configure fleet-level defaults

If you have enabled Google Kubernetes Engine (GKE) Enterprise edition, you can enable and configure Config Sync as a fleet-level default for your clusters. This means that every new GKE on Google Cloud cluster registered during cluster creation will have Config Sync enabled on the cluster with the settings you specify. You can find out more about fleet default configuration in Manage fleet-level features.

To configure fleet-level defaults for Config Sync, complete the following steps:

  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 register to the fleet inherit these settings.

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

    1. In the Version list, select the Config Sync version that you want to use.
    2. Click Save changes.
  5. Click Configure.

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

  7. Optional: Sync existing clusters to the default settings:

    1. In the Clusters in the fleet list, select the clusters that you want to sync.
    2. Click Sync to fleet settings and click Confirm in the confirmation dialog that appears. This operation can take a few minutes to complete.

Verify the installation

After you have installed and configured Config Sync, you can verify that the installation completed successfully.

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

You can also use the nomos status command to check if the Config Sync is installed successfully. A valid installation with no problems has a status of PENDING or SYNCED. An invalid or incomplete installation has a status of NOT INSTALLED OR NOT CONFIGURED. The output also includes any reported errors.

Upgrade Config Sync

Before you upgrade Config Sync, check the release notes for details on what's changed between versions.

To upgrade Config Sync, complete the following steps:

Console

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

    Go to Config

  2. Under the Settings tab, next to the cluster whose version you want to upgrade, select the context menu and then select Edit Config.
  3. From the version drop-down list, select the version that you want to upgrade to.
  4. Click Upgrade Config Sync.

gcloud

Run the following command:

gcloud beta container fleet config-management upgrade \
    --version=VERSION \
    --membership=MEMBERSHIP_NAME

Replace the following:

  • VERSION: the version that you want to upgrade to
  • MEMBERSHIP_NAME: the membership name that you chose when you registered your cluster. You can find the membership name by running gcloud container fleet memberships list.

Check the Config Management version

If you want to check which Config Sync version is installed on your clusters before you upgrade, run the following command:

gcloud beta container fleet config-management version

To learn more about this command, see the reference documentation.

Role-based access controls (RBAC) and permissions

Policy Controller, Config Sync and Config Controller includes highly-privileged workloads. The following table lists permissions for these workloads:

Component Namespace Service Account Permissions Description
ConfigManagement Operator config-management-system config-management-operator cluster-admin ConfigManagement Operator installs the other components in this table. Some of those components require cluster-admin permissions, so ConfigManagement Operator requires them as well.
Config Sync config-management-system See Config Sync permissions for required permissions.

Resource requests

The following section lists the resource requests for Config Sync.

The following table lists Kubernetes resource requirements for Config Sync components. For more information, see Managing Resources for Containers in the Kubernetes documentation.

Not all components listed are created. The following conditions cause each component to be scheduled:

  • config-management-operator is installed when Config Sync is enabled.
  • reconciler-manager is installed when Config Sync is enabled.
  • admission-webhook is installed when drift prevention is enabled.
  • a reconciler is installed for each RootSync and RepoSync.
  • otel-collector is installed when Config Sync is enabled.

1.17

Deployment name CPU request (m) per replica Memory request (Mi) per replica
config-management-operator 100 100
resource-group-controller-manager 110 300
admission-webhook1 10 100
otel-collector 200 400
reconciler-manager 20 150
reconciler (one per RootSync and RepoSync) See reconciler deployment for details.

1 The admission webhook has two replicas, so when calculating the total resource requests, you need to double the value if you are using the admission webhook. The admission webhook is disabled by default.

1.16

Deployment name CPU request (m) per replica Memory request (Mi) per replica
config-management-operator 100 100
resource-group-controller-manager 110 300
admission-webhook1 10 100
otel-collector 200 400
reconciler-manager 20 150
reconciler (one per RootSync and RepoSync) See reconciler deployment for details.

1 The admission webhook has two replicas, so when calculating the total resource requests, you need to double the value if you are using the admission webhook. The admission webhook is disabled by default.

1.15

Deployment name CPU request (m) per replica Memory request (Mi) per replica
config-management-operator 100 100
resource-group-controller-manager 110 300
admission-webhook1 10 100
otel-collector 200 400
reconciler-manager 20 150
reconciler (one per RootSync and RepoSync) See reconciler deployment for details.

1 The admission webhook has two replicas, so when calculating the total resource requests, you need to double the value if you are using the admission webhook. The admission webhook is disabled by default.

Reconciler deployment

For each RootSync and RepoSync, Config Sync creates an independent reconciler deployment to handle syncing. This improves reliability by reducing single points of failure and allows for individual reconcilers to be scaled independently.

The reconciler deployment consists of multiple containers:

Container name Description Condition
reconciler handles syncing and drift remediation always enabled
otel-agent handles sending metrics to the otel-collector always enabled
hydration-controller (Optional) handles Kustomize rendering enabled when the source includes a kustomize.yaml file
git-sync handles Git source retrieval enabled when spec.sourceType is git
gcenode-askpass-sidecar (Optional) used for Git authentication with the GKE metadata service enabled when spec.sourceType is git and spec.git.auth is gcenode or gcpserviceaccount
helm-sync handles Helm source retrieval enabled when spec.sourceType is helm
oci-sync handles OCI source retrieval enabled when spec.sourceType is oci

In Config Sync version 1.17.0 and later, the default resource requests for reconcilers are different for Standard and Autopilot clusters. All other cluster types use the Standard defaults.

Standard clusters

1.17

Container name CPU request (m) Memory request (Mi)
reconciler 50 200
otel-agent 10 100
hydration-controller (Optional) 10 100
git-sync 10 16
gcenode-askpass-sidecar (Optional) 10 20
helm-sync 75 128
oci-sync 25 32

1.16

Container name CPU request (m) Memory request (Mi)
reconciler 50 200
otel-agent 10 100
hydration-controller (Optional) 10 100
git-sync 10 200
gcenode-askpass-sidecar (Optional) 10 20
helm-sync 50 256
oci-sync 10 200

1.15

Container name CPU request (m) Memory request (Mi)
reconciler 50 200
otel-agent 10 100
hydration-controller (Optional) 10 100
git-sync 10 200
gcenode-askpass-sidecar (Optional) 10 20
helm-sync 50 256
oci-sync 10 200

Autopilot clusters

1.17

Container name CPU request and limit (m) Memory request and limit (Mi)
reconciler 700 512
otel-agent 10 64
hydration-controller (Optional) 200 256
git-sync 20 32
gcenode-askpass-sidecar (Optional) 50 64
helm-sync 150 256
oci-sync 50 64

1.16

In Config Sync versions earlier than 1.17.0, the resource requests are the same for Standard and Autopilot.

1.15

In Config Sync versions earlier than 1.17.0, the resource requests are the same for Standard and Autopilot.

To learn how to override the defaults resource requests and limits, see resource overrides.

Bundled Helm and Kustomize versions

Config Sync leverages the Helm and Kustomize executables to render the configurations under the hood. The following table provides a list of Config Sync versions that support the rendering feature, alongside the bundled Helm and Kustomize versions.

Config Sync versions Helm version Kustomize version
1.16.0 and later v3.11.3 v5.1.1
1.15.0 to 1.15.3 v3.11.3 v5.0.1
1.11.0 to 1.14.3 v3.6.3 v4.5.2

For information about rendering Helm through Kustomize, see Configure Kubernetes with Kustomize. For information about using the Helm API, see Syncing Helm charts from Artifact Registry.

What's next