With Config Sync, you can manage your Kubernetes resources by syncing configurations from a central source of truth, such as a Git repository, an OCI image, or a Helm chart. If the default installation instructions don't suit your needs, you might need to customize your Config Sync installation.
This page shows you how to perform an advanced installation and configuration of Config Sync. The installation process includes the following:
- Installing Config Sync on individual clusters using the Google Cloud console, the Google Cloud CLI, or Terraform.
- Configuring your root repository, including source type, format, and authentication.
- Verifying the successful installation and configuration of Config Sync.
Limitations
Config Sync doesn't support configuring helm
as the source type
using the Google Cloud console or the Google Cloud CLI. You can configure your
RootSync
or RepoSync
object to sync from a Helm repository using the
Kubernetes API, or
declare it in another source of truth.
See
Configuration for the Helm repository
for more information.
Before you begin
Before you install Config Sync, prepare your source of truth and a suitable cluster.
Grant Config Sync access to your source of truth
To synchronize configuration from a source of truth to your clusters, Config Sync requires read-only access to your repository. To authorize Config Sync to read your configurations, complete the following steps:
Create, or have access to, a source of truth that contains the configuration files that you want Config Sync to sync to your clusters. For more information, see the following 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.
If your source of truth is public, no further action is needed. Config Sync doesn't require extra permissions.
If your source of truth is private, complete the instructions in one of the following pages:
Review cluster requirements
Before you create a cluster, review cluster requirements.
Install Config Sync
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. For more information, see
Configure Config Sync with kubectl
commands.
Console
Install Config Sync
To install Config Sync, all clusters must be registered to a fleet. When you install Config Sync in the Google Cloud console, selecting individual clusters automatically registers those clusters to your fleet.
- In the Google Cloud console, go to the Config page under the Features section.
- Click add Install Config Sync.
- Select the Config Sync version that you want to use.
- Under Installation options, select one of the following options:
- Install Config Sync on entire fleet (recommended): Config Sync is installed on all clusters in the fleet.
- Install Config Sync on individual clusters: Config Sync is installed on the clusters that you select. Any selected clusters are automatically registered to your fleet.
- If you're installing Config Sync on individual clusters, in the Available clusters table, select the clusters on which you want to install Config Sync.
- Click Install Config Sync. In the Settings tab, after a few minutes, you should see Enabled in the Status column for the clusters in your fleet.
Deploy a package
After you have registered your clusters to a fleet and installed Config Sync, you can configure Config Sync to deploy a package to a cluster from a source of truth. You can deploy the same package to multiple clusters or deploy different packages to different clusters. You can edit a package after deploying it, except for some settings like package name and sync type. For more information, see Manage packages.
To deploy a package, complete the following steps:
In the Google Cloud console, go to the Config Sync dashboard.
Click Deploy Package.
In the Select clusters for package deployment table, select the cluster that you want to deploy a package to and then click Continue.
Select either Package hosted on Git or Package hosted on OCI as your source type and then click Continue.
In the Package details section, enter a Package name, which identifies the RootSync or RepoSync object.
In the Sync type field, choose either Cluster scoped sync or Namespace scoped sync as the sync type.
Cluster scoped sync creates a RootSync object and Namespace scoped sync creates a RepoSync object. For more information about these objects, see Config Sync architecture.
In the Source section, complete the following:
For sources hosted in a Git repository, enter the following fields:
- Enter the URL of the Git repository that you're using as a source of truth as the Repository URL.
- Optional: Update the Revision field to check out if you're not using
the default
HEAD
. - Optional: Update the Path field if you don't want to sync from the root repository.
- 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:
- Enter the URL of the OCI image that you're using as a source of truth as the Image.
- Enter the path of the directory to sync from, relative to the root directory, as the Directory.
(Optional): Expand the Advanced settings section to complete the following:
Select an Authentication type. Config Sync needs read-only access to your source of truth to read the configuration files in the source and apply them to your clusters. Unless your source requires no authentication, such as a public repository, ensure that you grant Config Sync read-only access to your Git repository, OCI image, or Helm chart (gcloud CLI only). Choose the same authentication type that you configured when you installed Config Sync:
- None: Use no authentication.
- SSH: Authenticate by using an SSH key pair.
- Cookiefile: Authenticate by using a
cookiefile
. - Token: Authenticate by using an access token or password.
- Google Cloud Repository: Use a Google service account to access a Cloud Source Repositories repository. Only select this option if Workload Identity Federation for GKE is not enabled in your cluster.
- Workload Identity: Use a Google service account to access a Cloud Source Repositories repository.
Enter a number in seconds to set the Sync wait time, which determines how long Config Sync waits between attempts to pull from the source of truth.
Enter a Git proxy URL for the HTTPS proxy to be used when communicating with the source of truth.
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.
Click Deploy Package.
You are redirected to the Config Sync Packages page. After a few minutes, you should see Synced in the Sync status column for the cluster that you configured.
gcloud
Before you continue, make sure you've registered your clusters to a fleet.
Enable the
ConfigManagement
fleet feature:gcloud beta container fleet config-management enable
Prepare the configuration by creating a file named
apply-spec.yaml
and copying 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 usekubectl
commands for configuration. You can also only set thespec.configSync.enabled
field astrue
and omit the optional fields. You can then later usekubectl
commands to create additional RootSync objects or RepoSyncs that you can fully manage usingkubectl
commands later.# apply-spec.yaml applySpecVersion: 1 spec: configSync: 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 secretType: SECRET_TYPE gcpServiceAccountEmail: EMAIL metricsGcpServiceAccountEmail: METRICS_EMAIL policyDir: DIRECTORY preventDrift: false
Replace the following:
SOURCE_TYPE
: addgit
to sync from a Git repository,oci
to sync from an OCI image, orhelm
to sync from a Helm chart. If no value is specified, the default isgit
.FORMAT
: addunstructured
to use an unstructured repository or addhierarchy
to use a hierarchical repository. These values are case-sensitive. This field is optional and the default value ishierarchy
. We recommend that you addunstructured
, 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 yoursecretType
, 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 thelatest
tag, but you can pull in images byTAG
orDIGEST
instead. SpecifyTAG
orDIGEST
in thePACKAGE_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
- To pull by
REVISION
: the Git revision (tag or hash) or branch name to sync from. When using a hash, it must be a full hash, and not an abbreviated form.SECRET_TYPE
: one of the followingsecretTypes
:git
none
: Use no authentication.ssh
: Use an SSH key pair.cookiefile
: Use acookiefile
.token
: Use a token.gcpserviceaccount
: Use a Google service account to access a Cloud Source Repositories or Secure Source Manager repository. 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 access to Git with a Google service account section.gcenode
: Use a Google service account to access a Cloud Source Repositories. Only select this option if Workload Identity Federation for GKE is not enabled in your cluster.githubapp
: Use a GitHub App to authenticate to a GitHub repository.
For more information on these authentication types, see Grant Config Sync access to Git.
oci
none
: Use no authenticationgcenode
: Use the Compute Engine default service account to access an image in Artifact Registry. Only select this option if Workload Identity Federation for GKE is not enabled in your cluster.gcpserviceaccount
: Use a Google service account to access an image.
helm
token
: Use a token.gcenode
: Use the Compute Engine default service account to access an image in Artifact Registry. Only select this option if Workload Identity Federation for GKE is not enabled in your cluster.gcpserviceaccount
: Use a Google service account to access an image.
EMAIL
: If you addedgcpserviceaccount
as yoursecretType
, 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 ServiceAccountdefault
in the namespaceconfig-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.
For a complete list of fields that you can add to the
spec
field, see gcloud fields.Apply the
apply-spec.yaml
file. If you are using an existing manifest, you should apply the file to the cluster that you want to configure with the settings that you fetched in the previous command:gcloud beta container fleet config-management apply \ --membership=MEMBERSHIP_NAME \ --config=CONFIG_YAML_PATH \ --project=PROJECT_ID
Replace the following:
MEMBERSHIP_NAME
: the fleet membership name that you chose when you registered your cluster. You can find the name withgcloud container fleet memberships list
.CONFIG_YAML_PATH
: the path to yourapply-spec.yaml
file.PROJECT_ID
: your project ID.
Terraform
For each cluster that you want to configure Config Sync,
apply a google_gkehub_feature_membership
resource block that contains
a configmanagement
and config_sync
block, such as in the following example:
git
Replace the following:
REPO
: the URL to the Git repository that contains your configuration files.BRANCH
: the repository branch, for examplemain
.DIRECTORY
: the path within the Git repository that represents the top level of the repository you want to sync.SECRET
: the secret auth type.
oci
Replace the following:
REPO
: the URL to the OCI image repository that contains your configuration files.DIRECTORY
: the absolute path of the directory containing the resources you want to sync. To use the root directory, leave this field blank.SECRET
: the secret auth type.
Repeat this process for each cluster that you want to sync.
For more information about using Terraform, see Terraform support for Config Sync.
After you configure your root repository, you can optionally 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.
Verify the installation
After you install and configure Config Sync, you can verify that the installation completed successfully.
gcloud
Run the following command:
nomos status
A successful installation shows a status of SYNCED
or PENDING
.
For more details about the information supplied by nomos status
, including
reported errors, see Check Config Sync status
in the nomos
command-line tool documentation.
console
Complete the following steps:
- In the Google Cloud console, go to the Config page under the Features section.
- 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.
What's next
- Learn how to upgrade Config Sync.
- Learn more about the
gcloud
commands for configuring Config Sync. - Discover how to configure syncing from multiple repositories.
- Use the
nomos
command. - Read the Introduction to troubleshooting Config Sync.
- Learn how to uninstall Config Sync.
- Review the Default Config Sync permissions.