gcp-gke

Use when working with Gcp Gke — google Kubernetes Engine cluster operations, node pool management, workload analysis, autopilot configuration, and upgrade planning via gcloud CLI.

SKILL.md

GitHub

GKE Skill

Manage and analyze Google Kubernetes Engine clusters using gcloud container commands.

Discovery-First Rule

ALWAYS discover before acting. Never assume cluster names, zones, node pool names, or Kubernetes versions.

# Discover clusters
gcloud container clusters list --format=json \
  --filter="" \
  | jq '[.[] | {name: .name, location: .location, status: .status, version: .currentMasterVersion, nodeCount: .currentNodeCount, autopilot: .autopilot.enabled}]'

Parallel Execution Requirement

ALL independent operations MUST run in parallel using background jobs (&) and wait.

for cluster in $(gcloud container clusters list --format="value(name,location)" | tr '\t' ','); do
  {
    name=$(echo "$cluster" | cut -d',' -f1)
    location=$(echo "$cluster" | cut -d',' -f2)
    gcloud container clusters describe "$name" --location="$location" --format=json
  } &
done
wait

Helper Functions

# Get cluster details
get_cluster_details() {
  local name="$1" location="$2"
  gcloud container clusters describe "$name" --location="$location" --format=json \
    | jq '{name: .name, status: .status, version: .currentMasterVersion, network: .network, subnetwork: .subnetwork, releaseChannel: .releaseChannel.channel, masterAuth: .masterAuthorizedNetworksConfig, addons: .addonsConfig, autoscaling: .autoscaling, shieldedNodes: .shieldedNodes.enabled}'
}

# List node pools
list_node_pools() {
  local cluster="$1" location="$2"
  gcloud container node-pools list --cluster="$cluster" --location="$location" --format=json \
    | jq '[.[] | {name: .name, version: .version, machineType: .config.machineType, diskSizeGb: .config.diskSizeGb, nodeCount: .initialNodeCount, autoscaling: .autoscaling, status: .status, management: .management}]'
}

# Get available upgrades
get_upgrades() {
  local cluster="$1" location="$2"
  gcloud container get-server-config --location="$location" --format=json \
    | jq '{validMasterVersions: .validMasterVersions[:5], validNodeVersions: .validNodeVersions[:5], defaultClusterVersion: .defaultClusterVersion}'
}

# Get cluster operations
get_operations() {
  local location="$1"
  gcloud container operations list --location="$location" --format=json --sort-by="~startTime" --limit=10 \
    | jq '[.[] | {name: .name, type: .operationType, status: .status, startTime: .startTime, endTime: .endTime, targetLink: .targetLink}]'
}

Common Operations

1. Cluster Health Overview

clusters=$(gcloud container clusters list --format="value(name,location)" | tr '\t' ',')
for cluster in $clusters; do
  {
    name=$(echo "$cluster" | cut -d',' -f1)
    location=$(echo "$cluster" | cut -d',' -f2)
    echo "=== Cluster: $name ==="
    get_cluster_details "$name" "$location"
    list_node_pools "$name" "$location"
  } &
done
wait

2. Node Pool Management

# Node pool details with autoscaling config
gcloud container node-pools list --cluster="$CLUSTER" --location="$LOCATION" --format=json \
  | jq '[.[] | {name: .name, machineType: .config.machineType, nodeCount: .initialNodeCount, minNodes: .autoscaling.minNodeCount, maxNodes: .autoscaling.maxNodeCount, autoRepair: .management.autoRepair, autoUpgrade: .management.autoUpgrade, preemptible: .config.preemptible, spot: .config.spot}]'

# Node pool utilization (via kubectl after getting credentials)
gcloud container clusters get-credentials "$CLUSTER" --location="$LOCATION"
kubectl top nodes

3. Workload Analysis

# Get credentials and analyze workloads
gcloud container clusters get-credentials "$CLUSTER" --location="$LOCATION"
kubectl get deployments --all-namespaces -o json | jq '[.items[] | {namespace: .metadata.namespace, name: .metadata.name, replicas: .spec.replicas, available: .status.availableReplicas, ready: .status.readyReplicas}]'

4. Autopilot Configuration

# Check if cluster is Autopilot
gcloud container clusters describe "$CLUSTER" --location="$LOCATION" --format=json \
  | jq '{autopilot: .autopilot.enabled, workloadPolicies: .autopilot.workloadPolicyConfig, resourceLimits: .autoscaling.resourceLimits}'

# Autopilot workload scaling classes
kubectl get priorityclasses -o json | jq '[.items[] | {name: .metadata.name, value: .value}]'

5. Upgrade Planning

# Current vs available versions
gcloud container clusters describe "$CLUSTER" --location="$LOCATION" --format=json \
  | jq '{masterVersion: .currentMasterVersion, nodeVersion: .currentNodeVersion, releaseChannel: .releaseChannel.channel}'

# Available upgrades
get_upgrades "$CLUSTER" "$LOCATION"

# Check node pool version skew
gcloud container node-pools list --cluster="$CLUSTER" --location="$LOCATION" --format=json \
  | jq '[.[] | {pool: .name, version: .version}]'

Output Format

Present results as a structured report:

Gcp Gke Report
══════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

  1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
  2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
  3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
  4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
  5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Shortcut Counter Why
"I'll skip discovery and check known resources" Always run Phase 1 discovery first Resource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check" Follow the full discovery → analysis flow Quick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine" Audit configuration explicitly Defaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this" Always check relevant metrics when available API/CLI responses show current state; metrics reveal trends and intermittent issues
"I don't have access to that" Try the command and report the actual error Assumed permission failures prevent useful investigation; actual errors are informative

Common Pitfalls

  1. Zonal vs regional: Zonal clusters have a single control plane; regional clusters have three. Use --location (not --zone) to work with both.
  2. Autopilot restrictions: Autopilot clusters do not allow SSH to nodes, privileged containers, or host network access. Check autopilot status first.
  3. Release channels: Clusters in a release channel get automatic upgrades. Manual version pinning requires opting out of the release channel.
  4. Node auto-provisioning: NAP creates node pools automatically. Check autoscaling.enableNodeAutoprovisioning before manually creating pools.
  5. Workload Identity: GKE Workload Identity replaces node-level service accounts. Check workloadIdentityConfig before troubleshooting IAM issues.