Grant Config Sync access to your Git repository

This page describes how to authenticate Config Sync to your Git repository. Config Sync requires read-only access to your source of truth so it can read your configurations, apply them to your clusters, and keep them in sync.

Choose an authentication method

The authentication method that you use depends on what is supported for your source type.

The following table summarizes the authentication methods you can use with Config Sync:

Method Supported sources Description Limitations
No authentication Git, OCI, Helm No additional setup required. Only works if your source of truth is public.
SSH key pair Git Supported by most Git providers. Requires key management. Not supported for OCI or Helm.
token Git, Helm Supported by most Git providers. Good alternative if your organization doesn't permit the use of SSH keys. Supports username and password for Helm. Requires token management. Tokens can expire. Not supported for OCI.
Kubernetes service account OCI, Helm Uses IAM to grant Artifact Registry access directly to a Kubernetes service account. Requires Workload Identity Federation for GKE to be enabled on your cluster. Not supported for Git.
Google service account Git Uses IAM, which avoids storing credentials in Kubernetes Secrets. Recommended for Secure Source Manager and Cloud Source Repositories. Requires Workload Identity Federation for GKE to be enabled on your cluster. Requires configuration before and after installing Config Sync on your clusters. Not supported for repositories hosted outside of Secure Source Manager or Cloud Source Repositories.
GitHub App Git Direct integration with GitHub. Allows fine-grained permissions. Only supported for repositories hosted in GitHub. Only supported in Config Sync version 1.19.1 and later.

Config Sync also supports the following authentication methods; however, these methods are only recommended if you can't use one of the options listed in the preceding table:

  • cookiefile: might not be supported for all Git providers. Not supported for OCI or Helm.
  • Compute Engine default service account (gcenode): not recommended because this method only works if Workload Identity Federation for GKE is disabled. Supported for Git, OCI, and Helm.
  • Google service account for Helm and OCI: supported, but not recommended because the Kubernetes service account method requires less configuration.

Authentication with fleet packages

If you use fleet packages, you don't need to complete the instructions on this page. Fleet packages uses Cloud Build to authenticate to Git, which lets you authenticate once per project so you don't need to grant access every time that you install Config Sync on a cluster.

Before you begin

Before you grant Config Sync read-only access to your Git repository, complete the following tasks:

Use an SSH key pair

An SSH key pair consists of two files, a public key and a private key. Config Sync does not support creating passphrases. Depending on your security and compliance requirements, you can use a single key pair for all clusters, or a key pair per cluster.

To grant Config Sync read-only access to your Git repository by using an SSH key pair, complete the following steps:

  1. Create, or ask your security administrator to provide, an SSH key pair. If you need to create an SSH key pair, create a 4096-bit RSA key by running the following command:

    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. If you use a third-party Git repository host like GitHub, or you want to use a service account with Secure Source Manager, we recommend that you use a separate account for authentication.
    • /path/to/KEYPAIR_FILENAME: the path to the key pair file.

  2. Configure your repository to recognize the newly created public key. Refer to the documentation for your Git hosting provider. You can find instructions for some common Git hosting providers in the following list:

  3. Create the git-creds Secret with the private key:

    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.

  4. Optional, but recommended: To configure known hosts checking when using SSH authentication, add the known hosts key to the data.known_hosts field in the git_creds Secret.

    1. To add the known hosts key, run the following command:

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

    2. To add the known_hosts entry under data, run the following command:

        known_hosts: KNOWN_HOSTS_KEY

      Replace KNOWN_HOSTS_KEY with the known hosts key.

    To disable known_hosts checking, remove the known_hosts field from the Secret.

When you install Config Sync, use SSH key pair (ssh) as the authentication type.

When you enter the URL of your Git repository, the URL must use SSH protocol format. The format of the URL differs depending on the Git provider.

Use a cookiefile

The process for acquiring a cookiefile depends on the configuration of your repository. Generally, credentials are stored in a .gitcookies file in a home directory, or a security administrator provides them.

To grant Config Sync read-only access to your Git repository by using a cookiefile, complete the following steps:

After you create or obtain the cookiefile, add it to a new Secret in the cluster. We recommend that you use HTTPS for security reasons:

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

Replace /path/to/COOKIEFILE with your path and filename.

When you install Config Sync, use cookiefile (cookiefile) as the authentication type.

Use a token

If your organization does not permit the use of SSH keys, you might prefer to use a token.

To grant Config Sync read-only access to your Git repository by using a token, complete the following steps:

  1. Generate a token from your Git provider. Refer to the documentation for your Git hosting provider for instructions. You can find instructions for some common Git hosting providers in the following list:

  2. After you create or obtain a token, add it to a new Secret in the cluster. We recommend that you use HTTPS for security reasons:

    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.

When you install Config Sync, use token (token) as the authentication type.

Use a Google service account

You can grant Config Sync access to a repository in the same project as your managed cluster by using a Google service account. You must meet the following requirements:

To grant Config Sync read-only access to your Git repository by using a Google service account, complete the following steps:

  1. To get the permissions that you need to create a policy binding, ask your administrator to grant you the Service Account Admin (roles/iam.serviceAccountAdmin) IAM role on the service account. For more information about granting roles, see Manage access to projects, folders, and organizations.

    You might also be able to get the required permissions through custom roles or other predefined roles.

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

  3. Grant the IAM role to the Google service account, depending on the repository type that you're using:

    Secure Source Manager

    Grant the Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor) and Secure Source Manager Repo Reader (roles/securesourcemanager.repoReader) IAM roles to the Google service account:

    • 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/securesourcemanager.instanceAccessor \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

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

      Replace the following:

      • PROJECT_ID: your project ID.
      • GSA_NAME: the name of the Google service account that you want to connect to Secure Source Manager.

    • To grant repository-specific permission, see the Secure Source Manager documentation for Granting users repository-level roles.

    When you install Config Sync, use Workload Identity (gcpserviceaccount) as the authentication type. You must also add your service account email.

    Secure Source Manager requires a specific format for the repository URL: https://SSM_INSTANCE_ID-PROJECT_NUMBER-git.INSTANCE_LOCATION.sourcemanager.dev/PROJECT_ID/REPO_NAME.git.

    Cloud Source Repositories

    Grant the Cloud Source Repositories Reader (roles/source.reader) IAM role to the Google service account:

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

      Replace the following:

      • PROJECT_ID: your project ID.
      • GSA_NAME: the name of the Google service account that you want to connect to Cloud Source Repositories.

    • 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

      Replace the following:

      • PROJECT_ID: your project ID.
      • REPOSITORY: the name of the repository.
      • POLICY_FILE: the JSON or YAML file that contains the Identity and Access Management policy.

    When you install Config Sync, use Workload Identity (gcpserviceaccount) as the authentication type. You must also add your service account email.

The following step must be completed after configuring Config Sync because the Kubernetes service account is not created until you configure Config Sync for the first time. You only need to do this once per fleet. To create the binding that lets the Kubernetes service account act as the Google service account, run 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:

  • FLEET_HOST_PROJECT_ID: if you use Workload Identity Federation for GKE, the value is the same as PROJECT_ID. If you use fleet Workload Identity Federation for GKE, use the project ID of the fleet that your cluster is registered to as the value.
  • GSA_NAME: the custom Google service account that you want to use to connect to Secure Source Manager or Cloud Source Repositories.
  • KSA_NAME: the Kubernetes service account for the reconciler. In most cases, the value is root-sync because Config Sync automatically creates a RootSync object named root-sync when installed with the Google Cloud console or the Google Cloud CLI. Otherwise, use root-reconciler-ROOT_SYNC_NAME as the value.

If you have issues connecting to Config Sync with a Google service account, refer to Troubleshooting permission issues with a Google service account.

Use a Compute Engine default service account

As an alternative to a Google service account, if you don't have Workload Identity Federation for GKE enabled, you can use a Compute Engine service account to authenticate. This method is supported only for repositories in Secure Source Manager and Cloud Source Repositories.

To grant Config Sync read-only access to your repository by using a Compute Engine default service account, grant the default service account the roles/source.reader role:

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

Replace the following:

  • PROJECT_ID: your project ID
  • PROJECT_NUMBER: with your project number.

When you install Config Sync, use Google Cloud Repository (gcenode) as the authentication type.

Use a GitHub App

If your repository is in GitHub, you can use the GitHub App to connect your repository to Config Sync:

  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 by using either the client or application ID:

    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 value is only needed when the repository is not hosted at www.github.com. The argument can otherwise be omitted and defaults to https://api.github.com/.

    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 value is only required if the repository is not hosted at www.github.com. The argument can otherwise be omitted and defaults to https://api.github.com/.

When you install Config Sync, use GitHub app (githubapp) as the authentication type.

Troubleshooting

For help troubleshooting issues related to connecting Config Sync to your source of truth, review the following troubleshooting topics:

What's next