Upgrade Config Sync

This page explains how to upgrade the Config Sync version installed on your clusters.

Auto-upgrade Config Sync

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

You can configure Config Sync to auto-upgrade to newer versions on your GKE on Google Cloud clusters.

Enabling auto-upgrades for Config Sync helps streamline your management experience. Google assumes responsibility for automatically upgrading Config Sync versions and overseeing the lifecycle of its components. Enabling auto-upgrades gives you the following benefits:

• Lower maintenance overhead: avoid monitoring for newer Config Sync versions and manually upgrading Config Sync across your clusters.
• Stay on supported versions: Google maintains the latest supported version in your clusters, ensuring you aren't using an unsupported version of Config Sync.
• Increased reliability: Google manages the Config Sync components and reconciles the components in case of any alterations.

Config Sync versions and GKE release channels

Config Sync picks the version to upgrade based on the Google Kubernetes Engine cluster release channel. A cluster not using a GKE release channel is treated as a cluster using the Stable GKE release channel.

You can use auto-upgrades to ensure Config Sync is upgraded on your clusters automatically. When a new version of Config Sync is available on a release channel, Config Sync upgrades the Config Sync version that matches the cluster release channel. The Rapid channel offers the latest version of Config Sync as soon as it's available. The Regular channel offers the latest version of Config Sync reasonably soon. The Stable channel offers the latest version of Config Sync only after being validated on the Rapid and Regular channels.

For more information about release channels, see About release channels.

The following table shows the current Config Sync version available in each release channel:

Release channel	Config Sync version
Rapid or Regular	1.20
Stable (or no channel)	1.19.2

Enable auto-upgrades

Enable auto-upgrades to ensure Config Sync is upgraded on your clusters automatically across your fleet.

You can enable auto-upgrades only on GKE on Google Cloud clusters with GKE Enterprise enabled.

Caution: You can't switch back to manual upgrades through the Google Cloud console after enabling auto-upgrades. Use gcloud or Terraform to switch back instead.

To install Config Sync and enable auto-upgrades, follow the instructions in Install Config Sync.

To enable auto-upgrades on a cluster that already has Config Sync installed, complete the following steps:

1. Confirm that your GKE cluster is enrolled in a release channel. If the GKE cluster is not enrolled in a release channel, Config Sync auto-upgrades as if the cluster is using the Stable GKE release channel.
2. If you have not previously configured Config Sync to send metrics to Cloud Monitoring, grant metric-writing permissions. This is required for auto-upgrades.

3. Ensure that Config Sync is on a supported version:

   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, click Edit cluster config.
   3. From the Version drop-down list, select the version that you want to upgrade to.
   4. Click Upgrade Config Sync.

   gcloud

   1. (Optional) 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
      

   2. To upgrade Config Sync, 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 fleet membership name that you chose when you registered your cluster. You can find the membership name by running gcloud container fleet memberships list.

4. Enable Config Sync auto-upgrades:

   console

   Enable auto-upgrades on individual clusters

   To enable auto-upgrades on individual clusters, complete the following steps:

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

      Go to Config

   2. Click Config Sync settings.
   3. Select Edit cluster config for the cluster that you want to update.
   4. In the settings pane that appears, select Auto-upgrades.
   5. Click Change Config Sync settings. In the Settings tab, after a few minutes, you should see Yes in the Auto-upgrades column for the cluster that you selected.

   Enable auto-upgrades as a fleet default

   To enable auto-upgrades across your fleet of clusters, 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. To change the default settings, click Customize fleet settings.

   4. In the dialog that appears, select Auto-upgrades.

   5. Click Save changes.

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

      1. Go to the Feature Manager page.

         Go to Feature Manager

      2. In the Config Sync pane, click View details.

      3. In the Clusters in the fleet list, select the clusters that you want to sync.

      4. Click Sync to fleet settings and click Confirm in the confirmation dialog that appears. This operation can take a few minutes to complete.

   gcloud

   To enable auto-upgrades on an individual cluster, complete the following steps:

   1. Update your Google Cloud CLI to the latest version:

      gcloud components update
      

   2. Update your existing Config Sync apply spec file to include the upgrades: auto field, for example:

      applySpecVersion: 1
      spec:
        upgrades: auto
        configSync:
          enabled: true
      # other fields intentionally omitted
      

   3. Apply the updated apply-spec.yaml file:

      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 with gcloud container fleet memberships list.
      • CONFIG_YAML_PATH: the path to your apply-spec.yaml file.
      • PROJECT_ID: your project ID.

   4. Confirm that auto-upgrade is enabled:

      gcloud beta container fleet config-management status \
        --project=PROJECT_ID
      

      Replace PROJECT_ID with your project's ID.

      The Upgrades column displays 'auto' for clusters with auto-upgrades enabled. If there is an error when enabling auto-upgrades, the Status column displays ERROR with a detailed error message.

Change your release channel

For information about changing your cluster's release channel, see Change your cluster's release channel in the GKE documentation. If you have auto-upgrades for Config Sync enabled, you should consider the following when changing your release channel:

• If you change your release channel to a less stable channel (for example, from Stable to Rapid), Config Sync will auto-upgrade from the latest version supported on the original release channel to the latest version supported on the new release channel.
• If you change your release channel to a more stable channel (for example, from Rapid to Stable), Config Sync won't downgrade versions. Over time, the latest version supported on the original release channel will be promoted to the new release channel. As newer versions become available on the new release channel, Config Sync will auto-upgrade normally.
• If you unsubscribe from a release channel, it does not affect Config Sync auto-upgrades. The Config Sync version will be upgraded as if your cluster was enrolled in the Stable release channel.

Manually upgrade Config Sync

Before you upgrade Config Sync, check the release notes for details on what's changed between versions. If you need to upgrade from an unsupported Config Sync version, you must perform a step-by-step upgrade with increments to no more than three minor versions at a time. For example, if the current Config Sync version is 1.14.0, first upgrade to version 1.17.0, and then to version 1.20.0.

Note: If you use Config Controller to install and manage Config Sync, you don't need to manually upgrade. Config Controller is a managed service, so Google upgrades it automatically. For details on Config Controller changes, see the Config Controller release notes.

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 Config Sync version you want to upgrade, select Edit cluster config.
3. From the Version drop-down list, select the version that you want to upgrade to.
4. Click Upgrade Config Sync.

gcloud

1. (Optional) 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
   

2. 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 fleet membership name that you chose when you registered your cluster. You can find the membership name by running gcloud container fleet memberships list.