Guide · Agent skill
How to use the GKE Workload Identity Troubleshooter agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The gke-workload-identity skill is an agent skill, a folder of instructions that an AI agent such as Claude loads when a task matches it. It guides the agent through a fixed checklist for a Pod on Google Kubernetes Engine (GKE) that cannot authenticate to Google Cloud APIs. This guide shows you how to install it, how to ask for it, what it checks, and what to expect, so you can use it without prior experience with agent skills.
GKE Workload Identity Troubleshootergoogle/skills · Apache-2.0 Download the skill Quick start
- 1Download the ZIP. Download the skill ZIP from this page.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into the project's .claude/skills/ folder.
- 3Or upload in the Claude apps. In the Claude apps, go to Settings, then Capabilities, then Skills, and upload the skill.
- 4Describe the failure. Ask in plain language, including the error text, namespace, Pod name, and target API.
- 5Provide context. Supply the project, cluster, location, and the node pool if the agent asks for them.
- 6Review the proposed fix. Read the diagnosis and the proposed gcloud command, which names the single most-likely cause.
- 7Apply the change yourself. A person with appropriate privileges applies any change. The skill does not apply changes automatically.
What the skill makes the agent do
The skill covers Workload Identity Federation for GKE. It is used when a Pod returns errors such as HTTP/403 with 'iam.serviceAccounts.getAccessToken' denied, 'could not find default credentials', or an unreachable GKE metadata server. It also covers API calls that unexpectedly run as the node's default Compute Engine service account.
The agent reads logs and cluster configuration, classifies the error, and works through the checklist. It names one most-likely root cause, explicitly rules out other causes with evidence, and writes out the exact fix as a command for a human to apply.
- Reads the workload's logs and the gke-metadata-server logs
- Checks that Workload Identity is enabled on the cluster and on the node pool
- Verifies the Kubernetes service account (KSA) to Google service account (GSA) binding
- Checks IAM roles on the target resource
- Checks gke-metadata-server health
Install the skill on Claude
Download the skill ZIP from this page. For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder so it applies only there.
If you use the Claude apps instead, upload the skill under Settings, then Capabilities, then Skills.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills
How to trigger the skill with natural requests
You do not need to type a special command. Describe the failure in plain language and include the details the agent needs. The skill asks for or looks up the project ID, cluster, location, namespace, Pod name, and the exact error text.
The skill is meant for Pod authentication failures to Google Cloud. It is not meant for in-cluster Kubernetes RBAC errors, general crashes, or Pod security and NetworkPolicy questions.
- 'My Pod in namespace payments gets 403 iam.serviceAccounts.getAccessToken denied when calling Cloud Storage. Diagnose it.'
- 'Pods in our GKE cluster say could not find default credentials. Check Workload Identity.'
- 'Our workloads run as the node default service account instead of their own identity. Find out why.'
- 'Help me set up the KSA to GSA binding for this Pod and check it.'
What the checks look like in practice
The first step is gathering context: the project number, the cluster and its location, the Pod's Kubernetes service account, and the node pool the Pod runs on. The skill then reads the error signature and decides which branch of the checklist to follow.
If the cluster has no workload identity pool, Workload Identity is not enabled on the cluster. If the node pool's workloadMetadataConfig mode is GCE_METADATA or empty, the node pool is not using the GKE metadata server, which is the usual cause of Pods running as the node's default service account. In that case the skill says plainly that the KSA annotation and IAM bindings are ruled out.
- Check the cluster's workload pool with gcloud container clusters describe
- Check the node pool's mode with gcloud container node-pools describe
gcloud container node-pools describe "{node_pool}" --cluster "{cluster}" --location "{location}" --format="value(config.workloadMetadataConfig.mode)"Example of a proposed fix
When the node pool is the cause, the skill proposes a command and does not run it. A human with the right privileges applies it. Note that this change recreates nodes.
The fix is a proposal only. The skill never changes IAM, service accounts, node pools, or clusters itself.
gcloud container node-pools update "{node_pool}" --cluster "{cluster}" --location "{location}" --workload-metadata=GKE_METADATAWhat you need before you start
The skill runs commands, so the agent's environment needs the gcloud CLI with access to the project and kubectl with access to the cluster and namespace. The account needs read permissions on the GKE cluster, IAM policies, and Cloud Logging for the project.
The skill uses the network to reach Google Cloud and runs scripts. Review the skill files before installing if your organisation requires it. The skill folder includes SKILL.md and references/attribution.md.
- gcloud CLI with access to the project
- kubectl with access to the cluster and namespace
- Read permissions on the GKE cluster, IAM policies, and Cloud Logging
- Runs scripts: yes. Uses network: yes
Tips for getting a useful diagnosis
Give the exact error string and the time of the first failure. The skill uses that window for log queries, so a precise timestamp gives cleaner evidence.
Expect a proposal, not a fix. If the answer needs a privileged change, the skill hands off to a human with its findings.
- Paste the full error message, not a paraphrase
- Include the Pod name, namespace, and the target API
- Tell the agent which identity you expect the Pod to use
- Keep the proposed command and review it before applying
What people use it for
- Diagnosing a Pod that gets 403 errors when calling a Google Cloud API
- Finding out why a Pod runs as the node's default service account
- Checking a first-time Workload Identity Federation setup and its KSA to GSA bindings
- Working through 'could not find default credentials' errors with a consistent checklist
Frequently asked questions
How do I install the gke-workload-identity skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings, then Capabilities, then Skills.
What do I need to run it?
You need the gcloud CLI with access to the project, kubectl with access to the cluster and namespace, and read permissions on the GKE cluster, IAM policies, and Cloud Logging for the project.
Is the gke-workload-identity skill free?
The skill is licensed under Apache-2.0, as listed on this page. Check the licence file in the source before redistributing it.
Will the skill fix my GKE permissions automatically?
No. The skill is read-only. It proposes commands or manifest changes, and a human with appropriate privileges must apply them.
Does it handle Kubernetes RBAC errors?
No. In-cluster RBAC errors are explicitly excluded. The skill also routes general workload crashes and Pod Security Standards or NetworkPolicy issues to other skills.
Why does my Pod run as the node default service account?
Usually the node pool's workloadMetadataConfig mode is GCE_METADATA instead of GKE_METADATA. The skill checks this and proposes an update command, which recreates nodes.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are a platform or DevOps engineer debugging 403 or credential errors in GKE Pods, or setting up Workload Identity for the first time and want a repeatable checklist. Pick something else if your problem is in-cluster RBAC, general application crashes, or network policy, or if you want an agent that applies fixes for you.
Download the skill