Version 1.12. This version is no longer supported. For information about how to upgrade to version 1.13, see Upgrading Anthos on bare metal in the 1.13 documentation. For more information about supported and unsupported versions, see the Version history page in the latest documentation.

Upgrade clusters

When you install a new version of bmctl, you can upgrade your existing clusters that were created with an earlier version. Upgrading a cluster to the latest Google Distributed Cloud version brings added features and fixes to your cluster. It also ensures that your cluster remains supported. You can upgrade admin, hybrid, standalone, or user clusters with the bmctl upgrade cluster command.

Upgrade considerations

The following sections outline rules and best practices to consider before you upgrade a cluster.

Preview features

Preview features are subject to change and are provided for testing and evaluation purposes only. Do not use Preview features on your production clusters. We do not guarantee that clusters that use Preview features can be upgraded. In some cases, we explicitly block upgrades for clusters that use Preview features.

For information about breaking changes related to upgrading, see the release notes.

SELinux

If you want to enable SELinux to secure your containers, you must make sure that SELinux is enabled in Enforced mode on all your host machines. Starting with Google Distributed Cloud release 1.9.0 or later, you can enable or disable SELinux before or after cluster creation or cluster upgrades. SELinux is enabled by default on Red Hat Enterprise Linux (RHEL) and CentOS. If SELinux is disabled on your host machines or you aren't sure, see Securing your containers using SELinux for instructions on how to enable it.

Google Distributed Cloud supports SELinux in only RHEL and CentOS systems.

Version rules for upgrades

When you download and install a new version of bmctl, you can upgrade your admin, hybrid, standalone, and user clusters created or upgraded with an earlier version of bmctl. Clusters can't be downgraded to a lower version.

You can only upgrade a cluster to a version that matches the version of bmctl you are using. That is, if you are using version 1.12.9 of bmctl, you can upgrade a cluster to version 1.12.9 only.

Patch version upgrades

For a given minor version, you can upgrade to any higher patch version. That is, you can upgrade a 1.12.X version cluster to version 1.12.Y as long as Y is greater than X. For example, you can upgrade from 1.11.0 to 1.11.1 and you can upgrade from 1.11.1 to 1.11.3. We recommend that you upgrade to the latest patch version whenever possible to ensure your clusters have the latest security fixes.

Minor version upgrades

You can upgrade clusters from one minor version to the next, regardless of the patch version. That is, you can upgrade from 1.N.X to 1.N+1.Y, where 1.N.X is the version of your cluster and N+1 is the next available minor version. The patch versions, X and Y, don't affect the upgrade logic in this case. For example, you can upgrade from 1.11.3 to 1.12.9.

You can't skip minor versions when upgrading clusters. If you attempt to upgrade to a minor version that is two or more minor versions higher than the cluster version, bmctl emits an error. For example, you can't upgrade a version 1.10.0 cluster to version 1.12.0.

An admin cluster can manage user clusters that are on the same or previous minor version. Managed user clusters can't be more than one minor version lower than the admin cluster, so before upgrading an admin cluster to a new minor version, make sure that all managed user clusters are at the same minor version as the admin cluster.

The examples in the following upgrade instructions show the upgrade process from version 1.11.2 to Google Distributed Cloud 1.12.9.

Pod density

Google Distributed Cloud supports the configuration of up to 250 maximum pods per node with nodeConfig.PodDensity.MaxPodsPerNode. You can configure pod density during cluster creation only. You can't update pod density settings for existing clusters.

Known issues

For information about potential problems related to cluster upgrades, see Upgrading Anthos clusters on bare metal on the Known Issues page.

Upgrade admin, standalone, hybrid, or user clusters

When you download and install a new version of bmctl, you can upgrade your admin, hybrid, standalone, and user clusters created with an earlier version. For a given version of bmctl, a cluster can be upgraded to the same version only.

First, download the latest bmctl, then modify the appropriate cluster config files, and then issue the bmctl upgrade cluster command to complete the upgrade.

Download the latest bmctl from the Cloud Storage bucket and use chmod to give bmctl execute permissions to all users:
```
gcloud storage cp gs://anthos-baremetal-release/bmctl/1.12.9/linux-amd64/bmctl bmctl
chmod a+x bmctl
```

Modify the cluster config file to change the Google Distributed Cloud cluster version from 1.11.2 to 1.12.9. The following shows an example from an admin cluster config:

---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: cluster1
  namespace: cluster-cluster1
spec:
  # Cluster type. This can be:
  #   1) admin:  to create an admin cluster. This can later be used to create user clusters.
  #   2) user:   to create a user cluster. Requires an existing admin cluster.
  #   3) hybrid: to create a hybrid cluster that runs admin cluster components and user workloads.
  #   4) standalone: to create a cluster that manages itself, runs user workloads, but does not manage other clusters.
  type: admin
  # Anthos cluster version.
  # Change the following line from 1.11.2 to 1.12.9, shown below
  anthosBareMetalVersion: 1.12.9

When upgrading clusters to 1.12.9, you must register the clusters with Connect to your project fleet, if they have not been registered already.
1. Manually create service accounts and retrieve the JSON key files as described in Configuring service accounts for use with Connect on the Enabling Google services and service accounts page.
2. Reference the downloaded JSON keys in the associated gkeConnectAgentServiceAccountKeyPath and gkeConnectRegisterServiceAccountKeyPath fields of the cluster config file.
Use the bmctl upgrade cluster command to complete the upgrade:
```
bmctl upgrade cluster -c CLUSTER_NAME --kubeconfig ADMIN_KUBECONFIG
```
Replace the following:
- CLUSTER_NAME: the name of the cluster to upgrade.
- ADMIN_KUBECONFIG: the path to the admin cluster kubeconfig file.
Preflight checks are run as part of the cluster upgrade to validate cluster status and node health. The cluster upgrade doesn't proceed if the preflight checks fail.