gke-gcloud-auth-plugin on a Mac

Install the plugin with Homebrew

The plugin is a gcloud component (Google's page Install kubectl and configure cluster access). With Homebrew:

brew install --cask google-cloud-sdk
gcloud components install gke-gcloud-auth-plugin kubectl

The cask name now resolves to gcloud-cli. It links gcloud, bq, gsutil and two credential helpers into /opt/homebrew/bin. The components land in /opt/homebrew/share/google-cloud-sdk/bin, so after both commands a fresh shell still answers gke-gcloud-auth-plugin not found to which. Homebrew says so at the end of the install:

To use additional binary components installed via gcloud, add the "/opt/homebrew/share/google-cloud-sdk/bin"
directory to your PATH environment variable

Check the plugin with its full path:

/opt/homebrew/share/google-cloud-sdk/bin/gke-gcloud-auth-plugin --version

It printed Kubernetes v37.0.0-22-gb501ae55e with SDK 592.0.0. The kubectl component is a separate binary in the same folder; a kubectl from elsewhere works too, as long as it can find the plugin.

Google's installer on a fresh Mac

Google's archive for Apple Silicon is google-cloud-cli-darwin-arm.tar.gz, followed by ./google-cloud-sdk/install.sh. The archive we downloaded on 7 November 2026 had no Python of its own, and install.sh needs one. On a Mac without Apple's Command Line Tools, python3 is only a stub, and the script stopped right after “Welcome to the Google Cloud CLI!”:

xcode-select: note: No developer tools were found, requesting install.

Install the Command Line Tools (xcode-select --install) or a Python first, or point CLOUDSDK_PYTHON at one, then run install.sh again and install the plugin with gcloud components install.

“executable gke-gcloud-auth-plugin not found” in Terminal

gcloud container clusters get-credentials writes a user entry whose exec runs the plugin, and kubectl looks the command up on PATH. With the plugin installed by Homebrew but its folder not on PATH, every kubectl call ends like this (exit 1):

Unable to connect to the server: getting credentials: exec: executable gke-gcloud-auth-plugin not found

It looks like you are trying to use a client-go credential plugin that is not installed.
...
Install gke-gcloud-auth-plugin for use with kubectl by following https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin

The message says the plugin is not installed even when it is. Add the SDK's bin folder to PATH in ~/.zprofile, then open a new Terminal window:

echo 'export PATH="/opt/homebrew/share/google-cloud-sdk/bin:$PATH"' >> ~/.zprofile

If gcloud is installed somewhere else, ask it where: gcloud info --format='value(installation.sdk_root)' prints the folder that holds bin. On our Mac, gcloud container fleet memberships get-credentials also wrote the bare name command: gke-gcloud-auth-plugin and failed the same way until PATH had the folder.

Apps started from the Dock or Finder

An app that reads your kubeconfig and runs the plugin itself, started from the Dock, Finder or Spotlight, does not get your shell's PATH. A test app started with open saw only this, with ~/.zprofile already fixed:

PATH=/usr/bin:/bin:/usr/sbin:/sbin
gke-gcloud-auth-plugin: not on PATH
Install gke-gcloud-auth-plugin for use with kubectl by following https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin

Writing the plugin's full path into the kubeconfig gets one step further and then fails inside the plugin, because it runs gcloud by name:

print credential failed with error: failed to retrieve access token: failure while executing gcloud, with args [config config-helper --format=json]: exec: "gcloud": executable file not found in $PATH

So give the exec entry both: the full command path and a PATH for the plugin. kubectl passes env to the plugin it starts:

users:
- name: gke_acme-prod_europe-west1_acme-gke
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: /opt/homebrew/share/google-cloud-sdk/bin/gke-gcloud-auth-plugin
      installHint: Install gke-gcloud-auth-plugin for use with kubectl by following https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin
      provideClusterInfo: true
      env:
      - name: PATH
        value: /opt/homebrew/share/google-cloud-sdk/bin:/usr/bin:/bin:/usr/sbin:/sbin

With that entry the same app got past both lookups and reached gcloud's own sign-in check. If you run get-credentials again, check that the user entry still has these lines.

“CRITICAL: ACTION REQUIRED” from get-credentials

Before it writes the kubeconfig, get-credentials runs gke-gcloud-auth-plugin --version, first by name and then from the SDK's own bin folder. When both fail, gcloud 590.0.0's source (lib/googlecloudsdk/api_lib/container/kubeconfig.py) logs this at critical level and writes the entry anyway; we read it in the source and did not trigger it:

CRITICAL: ACTION REQUIRED: gke-gcloud-auth-plugin, which is needed for continued use of kubectl, was not found or is not executable. Install gke-gcloud-auth-plugin for use with kubectl by following https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin

That means the component is missing from the SDK, not only from PATH. Run gcloud components install gke-gcloud-auth-plugin and then get-credentials again.

The plugin is found and kubectl still fails

In its default mode the plugin asks gcloud for a token by running gcloud config config-helper --format=json. With no account signed in to gcloud, the error changes from “not found” to:

Unable to connect to the server: getting credentials: exec: executable gke-gcloud-auth-plugin failed with exit code 1

and the line above it carries gcloud's reason, “You do not currently have an active account selected.” This error means the PATH part is fixed. Run gcloud auth login, or gcloud config set account when the account is already signed in.

Without the plugin

In its default mode the plugin turns gcloud's sign-in into a Kubernetes credential. kubectl for GKE without gcloud on a Mac compares the routes that skip it: the plugin reading Application Default Credentials, a small helper that does the same, a ServiceAccount token, and Ostgate, a Mac app whose kubeconfig entries sign kubectl in through the app, with no gcloud and no plugin on the Mac.

Symptoms and fixes

What we tested on

On 7 November 2026, in clean macOS virtual machines on an Apple Silicon Mac: macOS 15.7.7 with Homebrew 7.0.12, the gcloud-cli cask (Google Cloud SDK 592.0.0), the plugin's Kubernetes v37.0.0-22-gb501ae55e and kubectl v1.35.9-dispatcher; and macOS 26.6.2 without Command Line Tools for Google's archive. The kubeconfig named an example cluster on a documentation address, so every VM result above stops before any network call to Google; nothing was signed in. The fleet memberships get-credentials run is from 3 November 2026 on our own Mac with SDK 590.0.0.

Questions

Does the Homebrew google-cloud-sdk cask include gke-gcloud-auth-plugin?

No. The cask links gcloud, bq, gsutil and two credential helpers into /opt/homebrew/bin. The plugin comes from gcloud components install gke-gcloud-auth-plugin and lands in /opt/homebrew/share/google-cloud-sdk/bin, which is not on PATH until you add it.

Why does kubectl find the plugin in Terminal but not in an app from the Dock?

An app started from Finder or the Dock gets PATH=/usr/bin:/bin:/usr/sbin:/sbin from macOS and never reads ~/.zprofile or ~/.zshrc. Write the plugin's absolute path into the kubeconfig and give the exec entry a PATH that includes the SDK's bin folder.

Does gke-gcloud-auth-plugin need gcloud?

In its default mode, yes: it runs gcloud config config-helper for every token, so gcloud has to be on its PATH and signed in. Without an account it fails with "You do not currently have an active account selected."

Can kubectl reach GKE without the plugin?

Yes, with any credential plugin that prints a Google access token, or a ServiceAccount token in the kubeconfig. The guide kubectl for GKE without gcloud on a Mac compares the routes, Ostgate's included.