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

Choose an authentication method

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

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

Config Sync also supports the following authentication methods; however, these methods are onlyrecommended 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 usefleet packages, you don't need to complete the instructionson this page. Fleet packages uses Cloud Build to authenticate to Git, whichlets you authenticate once per project so you don't need to grant accessevery 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 followingtasks:

• Prepare, or have access to, a Git repository where you store your configurationfiles that you want Config Sync to sync. For more information, see thefollowing resources:

  • Add configs to a source of truth: conceptual information about configurations.
  • GitOps best practices: tips and general best practices for organizing and managing your repository.
  • Use an unstructured repo: recommendations for using and organizing an unstructured repository.

• Create, or have access to, a GKE cluster. Before creatinga cluster,review cluster configuration requirements and recommendations for Config Sync.

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 thefollowing command:

   ssh-keygen-trsa-b4096\-C"GIT_REPOSITORY_USERNAME"\-N''\-f/path/to/KEYPAIR_FILENAME

   Replace the following:

   • GIT_REPOSITORY_USERNAME: the username that you wantConfig Sync to use to authenticate to the repository. If you usea third-party Git repository host like GitHub, or you want to use aservice account with Secure Source Manager, we recommend that youuse a separate account for authentication.
   • /path/to/KEYPAIR_FILENAME: the path to the key pairfile.

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

   • Secure Source Manager
   • Bitbucket
   • GitHub
   • GitLab

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

   kubectlcreatensconfig-management-system &&\kubectlcreatesecretgenericgit-creds\--namespace=config-management-system\--from-file=ssh=/path/to/KEYPAIR_PRIVATE_KEY_FILENAME

   Note: If you need to use a proxy, pass the--from-literal=https_proxy=HTTPS_PROXY_URL flag.

   Replace/path/to/KEYPAIR_PRIVATE_KEY_FILENAME withthe name of the private key.

4. Optional, but recommended: To configure known hosts checking when using SSHauthentication, add the known hosts key to thedata.known_hosts field inthegit_creds Secret.

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

      kubectleditsecretgit-creds--namespace=config-management-system

   2. To add theknown_hosts entry underdata, run the following command:

      known_hosts:KNOWN_HOSTS_KEY

      ReplaceKNOWN_HOSTS_KEY with the known hosts key.

   To disableknown_hosts checking, remove theknown_hosts field from theSecret.

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 acookiefile depends on the configuration of yourrepository. Generally, credentials are stored in a.gitcookies file in a homedirectory, or a security administrator provides them.

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

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

kubectlcreatensconfig-management-system &&\kubectlcreatesecretgenericgit-creds\--namespace=config-management-system\--from-file=cookie_file=/path/to/COOKIEFILE

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

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

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

   kubectlcreatensconfig-management-system &&\kubectlcreatesecretgenericgit-creds\--namespace=config-management-system\--from-literal=username=USERNAME\--from-literal=token=TOKEN

   Note: If you need to use a proxy, pass the--from-literal=https_proxy=HTTPS_PROXY_URL flag.

   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 asyour managed cluster by using a Google service account. You must meet thefollowing requirements:

• Your repository is inSecure Source Manager orCloud Source Repositories.
• Your cluster hasWorkload Identity Federation for GKEorfleet Workload Identity Federation for GKE enabled.

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 theService Account Admin (roles/iam.serviceAccountAdmin) IAM role on the service account. For more information about granting roles, seeManage access to projects, folders, and organizations.

   You might also be able to get the required permissions throughcustom roles or otherpredefined 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 therepository type that you're using:

   Secure Source Manager

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

   • Grant project-wide permission if the same permissions apply to allrepositories in the project:

     gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--role=roles/securesourcemanager.instanceAccessor\--member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

     gcloudprojectsadd-iam-policy-bindingPROJECT_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 accountthat you want to connect to Secure Source Manager.

   • To grant repository-specific permission, see the Secure Source Managerdocumentation forGranting users repository-level roles.

   When you install Config Sync, useWorkload 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 allrepositories in the project:

     gcloudprojectsadd-iam-policy-bindingPROJECT_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 accountthat you want to connect to Cloud Source Repositories.

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

     gcloudsourcereposset-iam-policyREPOSITORYPOLICY_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 thatcontains the Identity and Access Management policy.

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

The following step must be completedafter configuring Config Syncbecause the Kubernetes service account is not created until you configureConfig Sync for the first time. You only need to do this once per fleet.To create the binding that lets the Kubernetes service accountact as the Google service account, run the following command:

gcloudiamservice-accountsadd-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 useWorkload Identity Federation for GKE, the value is the same asPROJECT_ID. If you use fleet Workload Identity Federation for GKE, usethe project ID of the fleet that your cluster is registered to as the value.
• GSA_NAME: the custom Google service account thatyou want to use to connect to Secure Source Manager or Cloud Source Repositories.
• KSA_NAME: the Kubernetes service account for thereconciler. In most cases, the value isroot-sync because Config Syncautomatically creates a RootSync object namedroot-sync when installed with the Google Cloud console or the Google Cloud CLI.Otherwise, useroot-reconciler-ROOT_SYNC_NAME as the value.

If you have issues connecting to Config Sync with a Google service account,refer toTroubleshooting 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 GKEenabled, you can use a Compute Engineservice account to authenticate. This method is supported only for repositories inSecure Source Manager and Cloud Source Repositories.

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

gcloudprojectsadd-iam-policy-bindingPROJECT_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,useGoogle 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 yourrepository to Config Sync:

1. Follow theinstructions on GitHubto 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 eitherthe client or application ID:

   client ID

   kubectlcreatensconfig-management-system &&\kubectlcreatesecretgenericgit-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

   • ReplaceCLIENT_ID with the client ID for the GitHub App.
   • ReplaceINSTALLATION_ID with the installation ID for the GitHub App.
   • Replace/path/to/GITHUB_PRIVATE_KEY withthe name of the file containing the private key.
   • ReplaceBASE_URL with the base URL for theGitHub API endpoint. This value is only needed when the repository is nothosted at www.github.com. The argument can otherwise be omitted anddefaults tohttps://api.github.com/.

   application ID

   kubectlcreatensconfig-management-system &&\kubectlcreatesecretgenericgit-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

   • ReplaceAPPLICATION_ID with the application ID for the GitHub App.
   • ReplaceINSTALLATION_ID with the installation ID for the GitHub App.
   • Replace/path/to/GITHUB_PRIVATE_KEY withthe name of the file containing the private key.
   • ReplaceBASE_URL with the base URL for theGitHub API endpoint. This value is only required if the repositoryis not hosted at www.github.com. The argument can otherwise beomitted and defaults tohttps://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 yoursource of truth, review the following troubleshooting topics:

• Connecting to the source of truth
• Permission issues with a Google service account

What's next

• Install Config Sync with default settings
• Customize your Config Sync installation