Here's what to know about changes to kubectl authentication coming in GKE v1.26

Important changes to Kubectl authentication are coming in GKE v1.26

While Google created Kubernetes, the platform has become the de-facto standard for container orchestration thanks to a large open-source community. 

To ensure the separation between the open source version of Kubernetes and those versions that are customized by services providers like Google, the open source community is requiring that all provider-specific code that currently exists in the OSS code base be removed starting with v1.26.

While this causes a number of changes on the server side from the OSS community in v1.26, there is one that affects kubectl on the client side as well. This post outlines changes you can make today that will prevent complications when v1.26 rolls out.

NOTE: The transition from provider-specific code in OSS to plugin based credentials retrieval is now planned for v1.26 due to customer feedback. Customers are encouraged to proactively deploy the plugin in their environments using the below flag at the earliest and let us know if they have any issues.

A new kubectl plugin called “gke-gcloud-auth-plugin”

Existing versions of kubectl and custom Kubernetes clients contain provider-specific code to manage authentication between the client and Google Kubernetes Engine. Starting with v1.26, this code will no longer be included as part of the OSS kubectl. GKE users will need to download and use a separate authentication plugin to generate GKE-specific tokens. This new binary, gke-gcloud-auth-plugin, uses the Kubernetes Client-go Credential Plugin mechanism to extend kubectl’s authentication to support GKE. Because plugins are already supported by kubectl, you can switch to the new mechanism now, before v1.26 becomes available.  

Below are the installation instructions and technical details of this new binary.

Kubectl authentication plugin installation instructions

You will need to install the gke-gcloud-auth-plugin binary on all systems where kubectl or Kubernetes custom clients are used. To install the binary, use one of the following methods.

Install using "gcloud components install"

Run the following command:

gcloud components install gke-gcloud-auth-plugin

Note: gcloud is the recommended way to install the binary on Windows and OS X

Install using "apt-get install" for DEB based systems

Run the following command:

sudo apt-get install google-cloud-sdk-gke-gcloud-auth-plugin

Note: Customers using apt-get install may need to set up Google Cloud-Sdk repository source, if not already set for other CLOUD-SDK component installations.

Install using "yum install" for RPM based systems

Run the following command:

sudo yum install google-cloud-sdk-gke-gcloud-auth-plugin

Note: Customers using yum install may need to set up Google Cloud-Sdk repository source, if not already set for other CLOUD-SDK component installations.

Verify installation

If this binary is installed correctly, the binary should be discoverable in the PATH. To verify that the installation worked correctly,  open a new terminal and run 

gke-gcloud-auth-plugin --version 

For Windows, 

gke-gcloud-auth-plugin.exe --version

Run kubectl with the new plugin prior to the release of v1.26

To have kubectl use the new binary plugin for authentication instead of using the default provider-specific code, use the following steps. 

1. Set export USE_GKE_GCLOUD_AUTH_PLUGIN=True in ~/.bashrc (or in Environment variables for Windows).

2. Run the following command: 

source ~/.bashrc

For Windows environments, start a new terminal.

3. Update gcloud to the latest version. 

gcloud components update

4. Run the following command: 

gcloud container clusters get-credentials CLUSTER_NAME

Replace the CLUSTER_NAME with the name of your cluster. This will force the config for this cluster to be updated to the Client-go Credential Plugin configuration. 

Potential kubectl plugin errors

If you install the plugin prior to the release of 1.26 and experience issues with it, you can revert to using the provider-specific code by setting export USE_GKE_GCLOUD_AUTH_PLUGIN=False in ~/.bashrc (or in Environment variables for Windows) and rerunning steps 2-4 above.

Once v1.26 is released, or if your plugin was not installed correctly, you may receive one of the following error messages.

For these errors, reinstall and verify the plugin.

The following error:

is received if you are using a version of kubectl or custom Kubernetes client that has been built with a version of the OSS code base of v1.26 or later and you have not installed the plugin.  

To fix this error, use the following steps:

1. Install gke-gcloud-auth-plugin as described above.

2. Update to the latest Gcloud tool using the cloud-sdk gcloud components update.

3. Rerun the following command to update the configuration for the cluster.
   gcloud container clusters get-credentials CLUSTER_NAME

   Replace the CLUSTER_NAME with the name of your cluster.

For more information on kubectl authentication and the new plug in, go to cloud documentation or open a support case.

• Install kubectl and configure cluster access

• Deprecated authentication plugin for Kubernetes clients

• Install required plugins

• Troubleshooting