Upgrading an admin workstation VM

This page describes how to upgrade an existing admin workstation for security patches. To determine whether an upgrade contains a security patch, see Release notes. To learn about the available versions, see Versions.

See also:

Overview

GKE On-Prem releases might include security patches for the admin workstation VM. When security patches become available, you should upgrade your admin workstation to the latest version. You should only need to upgrade your admin workstation if a security patch becomes available for GKE On-Prem. Otherwise, you should just download the new version of gkectl.

To upgrade an existing workstation VM to the latest version, you modify the Terraform files (TF and TFVARS) that you used to install the admin workstation. Then you run terraform init and terraform apply.

Before you begin

Setting variables for the local Docker registry

If your admin workstation VM runs the provided Docker registry, do the steps in this section. If your admin workstation does not run the provided Docker registry, skip this section.

  1. In your TF file, look for the vars block and uncomment the variables in the FOR UPGRADING section that looks like this:

    ########################
#### FOR UPGRADING #####
# reg_htpasswd = "${file(var.registry_htpasswd)}"
# reg_cert = "${file(var.registry_cert)}"
# reg_private_key = "${file(var.registry_private_key)}"
# reg_ca = "${file(var.registry_ca)}"
########################

  2. Copy these files from the old admin workstation VM to the machine from which you're performing the upgrade, such as your laptop:

    • /var/lib/gke/registry/auth/htpasswd
    • /var/lib/gke/registry/gke.pem
    • /var/lib/gke/registry/gke-key.pem
    • /var/lib/gke/registry/ca.pem

  3. In the Terraform variables (TFVARS) file, uncomment and set the following variables:

    • Set reg_htpasswd to the path of your htpasswd file.
    • Set reg_cert to the path of your gke.pem file.
    • Set reg_private_key to the path of your gke-keyfile.
    • Set reg_ca to the path of your ca.pem file.

Setting the template for the new admin workstation VM

In the Terraform variables section, at the top of the file, set vm_template to the latest version. The value of vm_template looks like this:

gke-on-prem-admin-appliance-vsphere-[VERSION]

Upgrading the admin workstation VM

To delete the old admin workstation VM and replace it with an upgraded VM, run the following command:

terraform init && terraform apply -auto-approve -input=false

IP address or DNS name of the admin workstation

If your GKE On-Prem cluster uses the Docker registry provided with the admin workstation, then one of the following must be true:

  • The upgraded admin workstation VM must have the same IP address as the old admin workstation VM. If you are using static IP addresses, you can ensure that this is the case.

  • You must have a DNS hostname for your admin workstation VM. If you are using DHCP, the IP address of the admin workstation might change during an upgrade, but GKE On-Prem can find the registry by using a DNS name.

Upgrading clusters

Now you have the latest version of the admin workstation VM. Recall that you upgraded your admin workstation to the latest version because of security updates. The next step is to determine whether you need to upgrade your clusters.

Check the Release notes to see whether there are security updates to the node OS images. If there are security updates to the node OS images, then you need to upgrade your clusters. Start by upgrading your admin cluster to the latest version, and then upgrade your user clusters to the latest version.

For instructions on how to upgrade your clusters, see Upgrading clusters.

Troubleshooting

Refer to Troubleshooting.