Configure syncing from multiple repositories

When you install Config Sync, you can configure a root repository. After you have configured a root repository, you have the option to configure other root and namespace repositories. Namespace repositories let you do things like delegate the setup and control of repositories to non-administrative users. To learn more about these types of repositories, see the Repositories section in the Config Sync overview.

Namespace repositories require the RepoSync API. If you installed Config Sync using the Google Cloud console or Google Cloud CLI and a version of 1.7.0 or later, this API is already enabled. If you installed Config Sync using kubectl and are using a ConfigManagement object to configure your Git repository, we recommend that you migrate your ConfigManagement object, to enable the RepoSync API.

Although Config Sync automatically detects changes from the source of truth, you can add an extra layer of drift detection by adding an admission webhook to the namespace repositories. For details on how to do this, see Prevent config drift.

Before you begin

  • Create, or make sure you have access to, an unstructured Git repository that can contain the configs that Config Sync syncs to. Namespace repositories must use the unstructured format.
  • Create, or make sure you have access to, a cluster that is on an Anthos supported platform and version.
  • Create, or make sure you have access to, a GKE cluster that meets the requirements for Config Sync.

Limitations

  • NamespaceSelectors (including annotations pointing to Selectors) only work in root repositories.

Choose your preferred configuration method

Choose between one of the two methods for configuring your repositories:

Control repositories in a central repository

Control root repositories in a root repository

Starting from version 1.11.0, Config Sync supports syncing from multiple root repositories. The central administrator can use a central root repository to manage multiple root repositories. Because Config Sync manages the RootSync objects, this method prevents any local changes to RootSync configurations in the cluster.

To use this method, complete the following tasks:

  1. In the central root repository, create a RootSync object with a unique name.

    apiVersion: configsync.gke.io/v1beta1
    kind: RootSync
    metadata:
      name: ROOT_SYNC_NAME
      namespace: config-management-system
    spec:
      sourceFormat: ROOT_FORMAT
      git:
       repo: ROOT_REPOSITORY
         revision: ROOT_REVISION
         branch: ROOT_BRANCH
         dir: "ROOT_DIRECTORY"
         auth: ROOT_AUTH_TYPE
         gcpServiceAccountEmail: ROOT_EMAIL
         secretRef:
           name: ROOT_SECRET_NAME
         noSSLVerify: ROOT_NO_SSL_VERIFY
    

    Replace the following:

    • ROOT_SYNC_NAME: add the name of your RootSync object. The name should be unique in the cluster and have no more than 26 characters.
    • ROOT_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 as this format lets you organize your configs in the way that is most convenient to you.
    • ROOT_REPOSITORY: add the URL of the Git repository to use as the root repository. You can enter URLs using either the HTTPS or SSH protocol. For example, https://github.com/GoogleCloudPlatform/anthos-config-management-samples uses the HTTPS protocol. If you don't enter a protocol, the URL is treated as an HTTPS URL. This field is required.
    • ROOT_REVISION: add the Git revision (tag or hash) to check out. This field is optional and the default value is HEAD.
    • ROOT_BRANCH: add the branch of the repository to sync from. This field is optional and the default value is master.
    • ROOT_DIRECTORY: add the path in the Git repository to the root directory that contains the configuration that you want to sync to. This field is optional and the default is the root directory (/) of the repository.
    • ROOT_AUTH_TYPE: add one of the following authentication types:

      • none: Use no authentication
      • ssh: Use a SSH key pair
      • cookiefile: Use a cookiefile
      • token: Use a token
      • gcpserviceaccount: Use a Google service account to access a repository in Cloud Source Repositories.
      • gcenode: Use a Google service account to access a a repository in 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.

      This field is required.

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

    • ROOT_SECRET_NAME: add the name of your Secret. If you are using a Secret, you must add the Secret's public key to the Git provider. This field is optional.

    • ROOT_NO_SSL_VERIFY: To disable the SSL certificate verification, set this field to true. The default value is false.

    For an explanation of the fields and a complete list of fields that you can add to the spec field, see RootSync fields.

  2. Commit the changes to the root repository:

     git add .
     git commit -m 'Setting up a new root repository.'
     git push
    
  3. You can repeat the above steps if you need to configure multiple root repositories.

Control namespace repositories in a root repository

Namespace repositories can be managed by a root repository. Because the namespace repository objects are managed by Config Sync, this method prevents any local changes to the namespace repository definitions.

To use this method, complete the following tasks:

  1. In the root repository, declare a namespace configuration:

    # ROOT_REPO/namespaces/NAMESPACE/namespace.yaml
    apiVersion: v1
    kind: Namespace
    metadata:
      name: NAMESPACE
    

    Replace NAMESPACE with a name for your namespace.

  2. In the root repository, create a RepoSync object in the same namespace:

    # ROOT_REPO/namespaces/NAMESPACE/repo-sync.yaml
     # If you are using a Config Sync version earlier than 1.8.0,
     # use: apiVersion: configsync.gke.io/v1alpha1
    apiVersion: configsync.gke.io/v1beta1
    kind: RepoSync
    metadata:
      name: REPO_SYNC_NAME
      namespace: NAMESPACE
    spec:
      # Since this is for a namespace repository, the format should be unstructured
      sourceFormat: unstructured
      git:
       repo: NAMESPACE_REPOSITORY
       revision: NAMESPACE_REVISION
       branch: NAMESPACE_BRANCH
       dir: "NAMESPACE_DIRECTORY"
       auth: NAMESPACE_AUTH_TYPE
       gcpServiceAccountEmail: NAMESPACE_EMAIL
       secretRef:
         name: NAMESPACE_SECRET_NAME
       # The `noSSLVerify` field is supported in Anthos Config Management version 1.8.2 and later.
       noSSLVerify: NAMESPACE_NO_SSL_VERIFY
    

    Replace the following:

    • REPO_SYNC_NAME: add the name of your RepoSync object. For versions earlier than 1.11.0, it must be repo-sync. For version 1.11.0 or later, the name should be unique across the namespace. REPO_SYNC_NAME and NAMESPACE should have no more than 24 characters. If NAMESPACE_AUTH_TYPE is used, REPO_SYNC_NAME, NAMESPACE, and NAMESPACE_AUTH_TYPE should have no more than 44 characters.
    • NAMESPACE: add the name of your namespace.
    • NAMESPACE_REPOSITORY: add the URL of the Git repository to use as the namespace repository. You can enter URLs using either the HTTPS or SSH protocol. For example, https://github.com/GoogleCloudPlatform/anthos-config-management-samples uses the HTTPS protocol. If you don't enter a protocol, the URL is treated as an HTTPS URL. This field is required.
    • NAMESPACE_REVISION: add the Git revision (tag or hash) to check out. This field is optional and the default value is HEAD.
    • NAMESPACE_BRANCH: add the branch of the repository to sync from. This field is optional and the default value is master.
    • NAMESPACE_DIRECTORY: add the path in the Git repository to the root directory that contains the configuration that you want to sync to. This field is optional and the default is the root directory (/) of the repository.
    • NAMESPACE_AUTH_TYPE: add one of the following authentication types:

      • none: Use no authentication
      • ssh: Use a SSH key pair
      • cookiefile: Use a cookiefile
      • token: Use a token
      • gcpserviceaccount: Use a Google service account to access a repository in Cloud Source Repositories.
      • gcenode: Use a Google service account to access a repository in 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.

      This field is required.

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

    • NAMESPACE_SECRET_NAME: add the name you intend to give your Secret. This field is optional.

    • NAMESPACE_NO_SSL_VERIFY: To disable the SSL certificate verification, set this field to true. The default value is false.

    For an explanation of the fields and a complete list of fields that you can add to the spec field, see RepoSync fields.

  3. In the root repository, declare a RoleBinding configuration that grants the SERVICE_ACCOUNT_NAME service account permission to manage objects in the namespace. Config Sync automatically creates the SERVICE_ACCOUNT_NAME service account when the RepoSync config is synced to the cluster.

    To declare the RoleBinding, create the following object:

    # ROOT_REPO/namespaces/NAMESPACE/sync-rolebinding.yaml
     kind: RoleBinding
     apiVersion: rbac.authorization.k8s.io/v1
     metadata:
       name: syncs-repo
       namespace: NAMESPACE
     subjects:
     - kind: ServiceAccount
       name: SERVICE_ACCOUNT_NAME
       namespace: config-management-system
     roleRef:
       kind: ClusterRole
       name: RECONCILER_ROLE
       apiGroup: rbac.authorization.k8s.io
    

    Replace the following:

    • NAMESPACE: add the name of your namespace.
    • SERVICE_ACCOUNT_NAME: add the name of the reconciler's service account. If the RepoSync name is repo-sync, SERVICE_ACCOUNT_NAME is ns-reconciler-NAMESPACE. Otherwise, it is ns-reconciler-NAMESPACE-REPO_SYNC_NAME.
    • RECONCILER_ROLE: as the central administrator, you can set the RECONCILER_ROLE to enforce what kinds of configuration can be synced from the namespace repository. You can choose one of the following roles:

      • A default ClusterRole:

        • admin
        • edit

        To learn more, see User-facing roles.

      • A user-defined ClusterRole or Role declared in the root repository. This role allows for fine grained permissions.

  4. Commit the changes to the root repository:

     git add .
     git commit -m 'Setting up a new namespace repository.'
     git push
    
  5. If required, create a Secret based on your preferred authentication method. If you used none as your authentication type, you can skip this step.

    The Secret must meet following requirements:

    • Create the Secret in the same namespace as the RepoSync.
    • The Secret's name must match the spec.git.secretRef name you defined in repo-sync.yaml.
    • You must add the Secret's public key to the Git provider.
  6. To verify the configuration, use kubectl get on one of the objects in the namespace repository. For example:

    kubectl get rolebindings -n NAMESPACE
    
  7. You can repeat the above steps if you need to configure multiple namespace repositories.

Control namespace repositories in a namespace repository

Config Sync supports syncing from multiple namespace repositories per namespace in version 1.11.0 and later. Namespace repositories can be managed in a namespace repository in the same namespace.

To use this method, complete the following tasks:

  1. In a namespace repository, create a RepoSync object in the same namespace:

    apiVersion: configsync.gke.io/v1beta1
    kind: RepoSync
    metadata:
      name: REPO_SYNC_NAME
      namespace: NAMESPACE
    spec:
      # Since this is for a namespace repository, the format should be unstructured
      sourceFormat: unstructured
      git:
       repo: NAMESPACE_REPOSITORY
       revision: NAMESPACE_REVISION
       branch: NAMESPACE_BRANCH
       dir: "NAMESPACE_DIRECTORY"
       auth: NAMESPACE_AUTH_TYPE
       gcpServiceAccountEmail: NAMESPACE_EMAIL
       secretRef:
         name: NAMESPACE_SECRET_NAME
       noSSLVerify: NAMESPACE_NO_SSL_VERIFY
    

    Replace the following:

    • REPO_SYNC_NAME: add the name of your RepoSync object. The name should be unique across the namespace. REPO_SYNC_NAME and NAMESPACE should have no more than 24 characters. If NAMESPACE_AUTH_TYPE is used, REPO_SYNC_NAME, NAMESPACE, and NAMESPACE_AUTH_TYPE should have no more than 44 characters.
    • NAMESPACE: add the name of your namespace.
    • NAMESPACE_REPOSITORY: add the URL of the Git repository to use as the namespace repository. You can enter URLs using either the HTTPS or SSH protocol. For example, https://github.com/GoogleCloudPlatform/anthos-config-management-samples uses the HTTPS protocol. If you don't enter a protocol, the URL is treated as an HTTPS URL. This field is required.
    • NAMESPACE_REVISION: add the Git revision (tag or hash) to check out. This field is optional and the default value is HEAD.
    • NAMESPACE_BRANCH: add the branch of the repository to sync from. This field is optional and the default value is master.
    • NAMESPACE_DIRECTORY: add the path in the Git repository to the root directory that contains the configuration that you want to sync to. This field is optional and the default is the root directory (/) of the repository.
    • NAMESPACE_AUTH_TYPE: add one of the following authentication types:

      • none: Use no authentication
      • ssh: Use a SSH key pair
      • cookiefile: Use a cookiefile
      • token: Use a token
      • gcpserviceaccount: Use a Google service account to access a repository in Cloud Source Repositories.
      • gcenode: Use a Google service account to access a repository in 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.

      This field is required.

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

    • NAMESPACE_SECRET_NAME: add the name you intend to give your Secret. This field is optional.

    • NAMESPACE_NO_SSL_VERIFY: To disable the SSL certificate verification, set this field to true. The default value is false.

    For an explanation of the fields and a complete list of fields that you can add to the spec field, see RepoSync fields.

  2. In the namespace repository, declare a RoleBinding configuration that grants the SERVICE_ACCOUNT_NAME service account permission to manage objects in the namespace. Config Sync automatically creates the SERVICE_ACCOUNT_NAME service account when the RepoSync config is synced to the cluster.

    To declare the RoleBinding, create the following object:

    # ROOT_REPO/namespaces/NAMESPACE/sync-rolebinding.yaml
     kind: RoleBinding
     apiVersion: rbac.authorization.k8s.io/v1
     metadata:
       name: syncs-repo
       namespace: NAMESPACE
     subjects:
     - kind: ServiceAccount
       name: SERVICE_ACCOUNT_NAME
       namespace: config-management-system
     roleRef:
       kind: ClusterRole
       name: RECONCILER_ROLE
       apiGroup: rbac.authorization.k8s.io
    

    Replace the following:

    • NAMESPACE: add the name of your namespace.
    • SERVICE_ACCOUNT_NAME: add the name of the reconciler's service account. If the RepoSync name is repo-sync, SERVICE_ACCOUNT_NAME is ns-reconciler-NAMESPACE. Otherwise, it is ns-reconciler-NAMESPACE-REPO_SYNC_NAME.
    • RECONCILER_ROLE: as the central administrator, you can set the RECONCILER_ROLE to enforce what kinds of configuration can be synced from the namespace repository. You can choose one of the following roles:

      • A default ClusterRole:

        • admin
        • edit

        To learn more, see User-facing roles.

      • A user-defined ClusterRole or Role declared in the root repository. This role allows for fine grained permissions.

  3. Commit the changes to the root repository:

     git add .
     git commit -m 'Setting up a new namespace repository.'
     git push
    
  4. If required, create a Secret based on your preferred authentication method. If you used none as your authentication type, you can skip this step.

    The Secret must meet following requirements:

    • Create the Secret in the same namespace as the RepoSync.
    • The Secret's name must match the spec.git.secretRef name you defined in repo-sync.yaml.
    • You must add the Secret's public key to the Git provider.
  5. To verify the configuration, use kubectl get on one of the objects in the namespace repository. For example:

    kubectl get rolebindings -n NAMESPACE
    
  6. You can repeat the above steps if you need to configure multiple namespace repositories.

Control repositories with the Kubernetes API

In this method, the central administrator delegates declaration of other RootSync objects to other administrators. For RepoSync objects, the central administrator only declares the namespace in the root repository and delegates declaration of the RepoSync object to the application operator.

Control root repositories

Other administrators can control root repositories by completing the following tasks:

  1. Declare a RootSync object:

    # root-sync.yaml
    apiVersion: configsync.gke.io/v1beta1
    kind: RootSync
    metadata:
      name: ROOT_SYNC_NAME
      namespace: config-management-system
    spec:
      sourceFormat: ROOT_FORMAT
      git:
        repo: ROOT_REPOSITORY
        revision: ROOT_REVISION
        branch: ROOT_BRANCH
        dir: "ROOT_DIRECTORY"
        auth: ROOT_AUTH_TYPE
        gcpServiceAccountEmail: ROOT_EMAIL
        secretRef:
          name: ROOT_SECRET_NAME
        noSSLVerify: ROOT_NO_SSL_VERIFY
    

    Replace the following:

    • ROOT_SYNC_NAME: add the name of your RootSync object. For versions earlier than 1.11.0, it must be root-sync. For version 1.11.0 or later, the name should be unique in the cluster and have no more than 26 characters.
    • ROOT_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 as this format lets you organize your configs in the way that is most convenient to you.
    • ROOT_REPOSITORY: add the URL of the Git repository to use as the root repository. You can enter URLs using either the HTTPS or SSH protocol. For example, https://github.com/GoogleCloudPlatform/anthos-config-management-samples uses the HTTPS protocol. If you don't enter a protocol, the URL is treated as an HTTPS URL. This field is required.
    • ROOT_REVISION: add the Git revision (tag or hash) to check out. This field is optional and the default value is HEAD.
    • ROOT_BRANCH: add the branch of the repository to sync from. This field is optional and the default value is master.
    • ROOT_DIRECTORY: add the path in the Git repository to the root directory that contains the configuration that you want to sync to. This field is optional and the default is the root directory (/) of the repository.
    • ROOT_AUTH_TYPE: add one of the following authentication types:

      • none: Use no authentication
      • ssh: Use a SSH key pair
      • cookiefile: Use a cookiefile
      • token: Use a token
      • gcpserviceaccount: Use a Google service account to access a repository in Cloud Source Repositories.
      • gcenode: Use a Google service account to access a repository in 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.

      This field is required.

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

    • ROOT_SECRET_NAME: add the name of your Secret. If you are using a Secret, you must add the Secret's public key to the Git provider. This field is optional.

    • ROOT_NO_SSL_VERIFY: To disable the SSL certificate verification, set this field to true. The default value is false.

    For an explanation of the fields and a complete list of fields that you can add to the spec field, see RootSync fields.

  2. Apply the changes:

    kubectl apply -f root-sync.yaml
    
  3. You can repeat the above steps if you need to configure multiple root repositories.

Control namespace repositories

Central administrator tasks

The central administrator completes the following tasks:

  1. In the root repository, declare a namespace configuration for namespace repositories.

    # ROOT_REPO/namespaces/NAMESPACE/namespace.yaml
     apiVersion: v1
     kind: Namespace
     metadata:
       name: NAMESPACE
    

    Replace NAMESPACE with a name for your namespace.

  2. In the root repository, declare a RoleBinding to give the application operators permissions. Use RBAC escalation prevention to ensure that the application operator cannot later apply a role binding with permissions not granted by this role binding.

    To declare the RoleBinding, create the following manifest:

    # ROOT_REPO/namespaces/NAMESPACE/operator-rolebinding.yaml
     kind: RoleBinding
     # Add RBAC escalation prevention
     apiVersion: rbac.authorization.k8s.io/v1
     metadata:
       name: operator
       namespace: NAMESPACE
     subjects:
     - kind: User
       name: USERNAME
       apiGroup: rbac.authorization.k8s.io
     roleRef:
       kind: ClusterRole
       name: OPERATOR_ROLE
       apiGroup: rbac.authorization.k8s.io
    

    Replace the following:

    • NAMESPACE: add the namespace you created in the root repository.
    • USERNAME: add the username of the application operator.
    • OPERATOR_ROLE: as the central administrator, you can set OPERATOR_ROLE to enforce what kinds of configurations can be synced from the namespace repository. You can choose one of the following roles:

      • A default ClusterRole:

        • admin
        • edit

        To learn more, see User-facing roles.

      • A user-defined ClusterRole or Role declared in the root repository. This role allows for fine grained permissions.

  3. Commit the changes to the root repository:

     git add .
     git commit -m 'Setting up new namespace repository.'
     git push
    

Application operator tasks

The application operator can control namespace repositories by completing the following tasks:

  1. Declare a RoleBinding configuration that grants the auto-provisioned SERVICE_ACCOUNT_NAME service account permission to manage objects in the namespace. Config Sync automatically creates the SERVICE_ACCOUNT_NAME service account when the RepoSync config is synced to the cluster.

    To declare the RoleBinding, create the following manifest:

    # sync-rolebinding.yaml
    kind: RoleBinding
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      name: syncs-repo
      namespace: NAMESPACE
    subjects:
    - kind: ServiceAccount
      name: SERVICE_ACCOUNT_NAME
      namespace: config-management-system
    roleRef:
      kind: ClusterRole
      name: RECONCILER_ROLE
      apiGroup: rbac.authorization.k8s.io
    

    Replace the following:

    • NAMESPACE: add the namespace you created in the root repository.
    • SERVICE_ACCOUNT_NAME: add the name of the reconciler's service account. If the RepoSync name is repo-sync, SERVICE_ACCOUNT_NAME is ns-reconciler-NAMESPACE. Otherwise, it is ns-reconciler-NAMESPACE-REPO_SYNC_NAME.
    • RECONCILER_ROLE: as the application operator you can set RECONCILER_ROLE to enforce what kinds of configuration can be synced from the namespace repository. You can only further restrict the set of permissions the central administrator has granted you. As a result, this role cannot be more permissive than the OPERATOR_ROLE that the central administrator declared in the previous section.
  2. Apply the RoleBinding configuration:

    kubectl apply -f sync-rolebinding.yaml
    
  3. If required, create a Secret based on your preferred authentication method. If you used none as your authentication type, you can skip this step.

    The Secret must meet the following requirements:

    • Create the Secret in the same namespace as the RepoSync.
    • The Secret's name must match the spec.git.secretRef name you defined in root-sync.yaml.
    • You must add the Secret's public key to the Git provider.
  4. Declare a RepoSync configuration:

    # repo-sync.yaml
    # If you are using a Config Sync version earlier than 1.8.0,
    # use: apiVersion: configsync.gke.io/v1alpha1
    apiVersion: configsync.gke.io/v1beta1
    kind: RepoSync
    metadata:
      name: REPO_SYNC_NAME
      namespace: NAMESPACE
    spec:
      # Since this is for a namespace repository, the format should be unstructured
      sourceFormat: unstructured
      git:
       repo: NAMESPACE_REPOSITORY
       revision: NAMESPACE_REVISION
       branch: NAMESPACE_BRANCH
       dir: "NAMESPACE_DIRECTORY"
       auth: NAMESPACE_AUTH_TYPE
       gcpServiceAccountEmail: NAMESPACE_EMAIL
       secretRef:
         name: NAMESPACE_SECRET_NAME
       # The `noSSLVerify` field is supported in Anthos Config Management version 1.8.2 and later.
       noSSLVerify: REPO_SSL_VERIFY
    

    Replace the following:

    • REPO_SYNC_NAME: add the name of your RepoSync object. For versions earlier than 1.11.0, it must be repo-sync. For version 1.11.0 or later, specify any name you prefer.
    • NAMESPACE_REPOSITORY: add the URL of the Git repository to use as the namespace repository. You can enter URLs using either the HTTPS or SSH protocol. For example, https://github.com/GoogleCloudPlatform/anthos-config-management-samples uses the HTTPS protocol. If you don't enter a protocol, the URL is treated as an HTTPS URL. This field is required.
    • NAMESPACE_REVISION: add the Git revision (tag or hash) to check out. This field is optional and the default value is HEAD.
    • NAMESPACE_BRANCH: add the branch of the repository to sync from. This field is optional and the default value is master.
    • NAMESPACE_DIRECTORY: add the path in the Git repository to the root directory that contains the configuration that you want to sync to. This field is optional and the default is the root directory (/) of the repository.
    • NAMESPACE_AUTH_TYPE: add one of the following authentication types:

      • none: Use no authentication
      • ssh: Use a SSH key pair
      • cookiefile: Use a cookiefile
      • token: Use a token
      • gcpserviceaccount: Use a Google service account to access a repository in Cloud Source Repositories.
      • gcenode: Use a Google service account to access a repository in 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.

      This field is required.

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

    • NAMESPACE_SECRET_NAME: add the name you intend to give your Secret. This field is optional.

    • NAMESPACE_NO_SSL_VERIFY: To disable the SSL certificate verification, set this field to true. The default value is false.

    For an explanation of the fields and a complete list of fields that you can add to the spec field, see RepoSync fields.

    There can be at most one RepoSync object per namespace. To enforce this, the object's name must be repo-sync. All configs contained in the directory referenced by the RepoSync must also be in the same namespace as the RepoSync object.

  5. Apply the RepoSync configuration:

    kubectl apply -f repo-sync.yaml
    
  6. To verify the configuration, use kubectl get on one of the objects in the namespace repository. For example:

    kubectl get rolebindings -n NAMESPACE
    
  7. You can repeat the above steps if you need to configure multiple namespace repositories.

Verify the sync status of the repository

You can use the nomos status command to inspect the sync status of the repository:

nomos status

You should see output similar to the following example:

my_managed_cluster-1
  --------------------
  <root>   git@github.com:foo-corp/acme/admin@main
  SYNCED   f52a11e4
  --------------------
  bookstore  git@github.com:foo-corp/acme/bookstore@v1
  SYNCED     34d1a8c8

In this example output, the namespace repository is configured for a namespace named bookstore.

Verify the RootSync installation

When you create a RootSync object, Config Sync creates a reconciler with the root-reconciler prefix. A reconciler is a Pod that is deployed as a Deployment. It syncs manifests from a Git repository to a cluster.

You can verify that the RootSync object is working correctly by checking the status of the root-reconciler Deployment:

For Config Sync version earlier than 1.11.0:

kubectl get -n config-management-system deployment/root-reconciler

For Config Sync version 1.11.0 and later:

kubectl get -n config-management-system deployment -l configsync.gke.io/sync-name=ROOT_SYNC_NAME

Replace ROOT_SYNC_NAME with the name of RootSync.

You should see output similar to the following example:

NAME              READY   UP-TO-DATE   AVAILABLE   AGE
root-reconciler   1/1     1            1           3h42m

For further ways to explore the status of your RootSync object, see Monitoring RootSync and RepoSync objects.

Verify the RepoSync installation

When you create a RepoSync object, Config Sync creates a reconciler with the ns-reconciler-NAMESPACE prefix, where NAMESPACE is the namespace you created your RepoSync object in.

You can verify that the RepoSync object is working correctly by checking the status of the namespace reconciler Deployment:

For Config Sync version earlier than 1.11.0:

kubectl get -n config-management-system deployment/ns-reconciler-NAMESPACE

Replace NAMESPACE with the namespace that you created your namespace repository in.

For Config Sync version 1.11.0 and later:

kubectl get -n config-management-system deployment \
  -l configsync.gke.io/sync-name=REPO_SYNC_NAME \
  -l configsync.gke.io/sync-namespace=NAMESPACE

Replace REPO_SYNC_NAME with the name of RepoSync, and replace NAMESPACE with the namespace that you created your namespace repository in.

For further ways to explore the status of your RepoSync object, see Exploring the RootSync and RepoSync objects.

Remove a repository

Select the Central control method or Kubernetes API method tab to view the relevant instructions.

Central control method

If you used the Control repositories in a central repository method, a central administrator can follow the following two steps to remove a repository:

  1. Unmanage or delete the resources managed by the RootSync or RepoSync object following the troubleshooting instructions.

  2. Remove the RootSync or RepoSync object from the Git repository.

Kubernetes API method

If you used the Control namespace repositories with the Kubernetes API method, application operators can follow the following two steps to remove a namespace repository:

  1. Unmanage or delete the resources managed by the RootSync or RepoSync object following the troubleshooting instructions.

  2. Delete the RootSync or RepoSync object by running the following command:

    kubectl delete -f FILE_NAME
    

    Replace FILE_NAME with either root-sync.yaml or repo-sync.yaml.

What's next