# SkillPatch skill: gke-basics

A hub/routing skill for Google Kubernetes Engine (GKE) that provides core cluster discovery, a quick-start setup guide, and a comprehensive routing table to direct agents toward the most appropriate specialized GKE sub-skill. It covers 16 GKE scenarios ranging from networking and security to AI/ML workloads and cost optimization. It also defines rules for handling conceptual vs. hands-on queries efficiently.

You (the agent) were given this URL and asked to use this skill. This is a **public** skill — no SkillPatch account, API key, or prior setup is required. Two ways to use it:

**1. Use it right now** — the skill's complete file tree (SKILL.md + all reference files) is inlined below; read `SKILL.md` first, then follow it, consulting the other files as it directs.

**2. Install the exact package onto disk** (recommended if you can run a shell — this reproduces the skill byte-for-byte, including any binary assets that can't be inlined):

```bash
mkdir -p .claude/skills/gke-basics
curl -sSL https://skillpatch.dev/install_skill/gke-basics | tar -xz -C .claude/skills/
```

(`.claude/skills/` is Claude Code's convention; use whatever directory your agent loads skills from.)


---

## Skill files (6)

- `SKILL.md`
- `references/cli-reference.md`
- `references/client-library-usage.md`
- `references/core-concepts.md`
- `references/iac-usage.md`
- `references/mcp-usage.md`


### `SKILL.md`

````markdown
---
name: gke-basics
metadata:
  category: Containers
description: >-
  Core GKE cluster discovery and hub. Use to route to specialized GKE skills.
  Do not use for specialized tasks (networking, security, etc.) directly.
---

# GKE Basics

Managed Kubernetes platform on Google Cloud. Defaults to Autopilot mode.

## Quick Start

```bash
gcloud services enable container.googleapis.com --quiet
gcloud container clusters create-auto my-cluster --region=us-central1 --quiet
gcloud container clusters get-credentials my-cluster --region=us-central1 --quiet
```

## GKE Skill Routing Table

Load the single, most specific GKE sub-skill below matching your workload
requirements. **Do not load multiple GKE skills unless explicitly required.**

| Scenario             | Trigger Keywords             | Target Skill           |
| -------------------- | ---------------------------- | ---------------------- |
| Golden Path Defaults | production defaults, golden  | `gke-golden-path`      |
:                      : path                         :                        :
| Cluster Creation     | create cluster, provision    | `gke-cluster-creation` |
:                      : GKE                          :                        :
| Networking & Ingress | private cluster, VPC,        | `gke-networking`       |
:                      : Gateway API, Ingress, DNS    :                        :
| Security & IAM       | Workload Identity, Secret    | `gke-security`         |
:                      : Manager, RBAC, hardening     :                        :
| Autoscaling          | HPA, VPA, Cluster            | `gke-scaling`          |
:                      : Autoscaler, NAP              :                        :
| Compute Classes      | ComputeClass, Spot fallback, | `gke-compute-classes`  |
:                      : GPU/TPU nodes                :                        :
| Cost Optimization    | Spot VMs, rightsizing, cost  | `gke-cost`             |
:                      : allocation                   :                        :
| AI/ML Workloads      | LLM, GPU/TPU inference,      | `gke-inference`        |
:                      : serving, vLLM                :                        :
| Cluster Upgrades     | upgrade, maintenance window, | `gke-upgrades`         |
:                      : release channel              :                        :
| Observability        | monitoring, logging,         | `gke-observability`    |
:                      : Prometheus, dashboards       :                        :
| Multi-tenancy        | namespace isolation,         | `gke-multitenancy`     |
:                      : resource quota, LimitRange   :                        :
| Batch & HPC          | batch, HPC, Kueue, JobSet,   | `gke-batch-hpc`        |
:                      : parallel jobs                :                        :
| App Onboarding       | containerize, Dockerfile,    | `gke-app-onboarding`   |
:                      : deploy app, onboard          :                        :
| Backup & DR          | backup plan, restore,        | `gke-backup-dr`        |
:                      : disaster recovery, CMEK      :                        :
| Storage & PVC        | SSD, PV, PVC, StorageClass,  | `gke-storage`          |
:                      : GCS FUSE                     :                        :
| Reliability          | PDB, health probe, liveness, | `gke-reliability`      |
:                      : readiness                    :                        :

## Conceptual & Informational Queries (CRITICAL)

For purely conceptual, educational, or informational questions (e.g. "What is
GKE?", "Explain GKE architecture", or "Compare Standard vs Autopilot" in a
generic sense):

*   **Rule**: **Answer immediately using your pre-trained knowledge.**
*   **Constraint**: **Do not execute code searches, directory listings, or other
    tool calls** unless the user explicitly requests you to inspect the local
    workspace or run a command. Keep it fast, cheap, and direct.

````


### `references/cli-reference.md`

````markdown
# CLI & Tool Reference for GKE

## Tool Preference

Default preference order:

```
1. GKE MCP Tools  (preferred — structured, auditable, no shell required)
2. gcloud CLI     (fallback — when MCP doesn't expose the operation)
3. kubectl        (fallback — purely in-cluster ops not covered by MCP)
```

### When to use each

| Interface         | When to Use                | Examples                    |
| ----------------- | -------------------------- | --------------------------- |
| **GKE MCP Tools** | Default for all cluster    | `create_cluster`,           |
:                   : and K8s operations when    : `get_cluster`,              :
:                   : MCP server is available.   : `get_k8s_resource`,         :
:                   : Structured I/O, supports   : `apply_k8s_manifest`,       :
:                   : dry-run, no                : `get_k8s_logs`              :
:                   : shell/kubeconfig needed.   :                             :
| **`gcloud` CLI**  | No MCP equivalent, or user | `gcloud container ai        |
:                   : explicitly requested CLI.  : profiles`, `gcloud          :
:                   : Required for\: GIQ model   : container                   :
:                   : discovery, available K8s   : get-server-config`, `gcloud :
:                   : versions, maintenance      : iam service-accounts`       :
:                   : windows, monitoring        :                             :
:                   : components, IAM/SA setup,  :                             :
:                   : Cloud Logging queries.     :                             :
| **`kubectl`**     | Neither MCP nor `gcloud`   | `kubectl top pods`,         |
:                   : covers the operation, or   : `kubectl scale deployment`, :
:                   : user explicitly prefers    : `helm install`              :
:                   : kubectl. Required for\:    :                             :
:                   : `kubectl top`, `kubectl    :                             :
:                   : scale`, `kubectl exec`,    :                             :
:                   : `kubectl port-forward`,    :                             :
:                   : Helm, custom CRDs not in   :                             :
:                   : MCP.                       :                             :

### User preference override

If the user states a preference, respect it for the session:

-   **"Use gcloud" / "Use CLI"** → `gcloud` for cluster ops, `kubectl` for K8s
    resource ops. Skip MCP.
-   **"Use kubectl"** → `kubectl` for all K8s resource ops, `gcloud` for
    cluster-level ops. Skip MCP.
-   **"Use MCP"** / no preference → Default. Use MCP for everything it supports.

Even with an override, fall back through the chain for unsupported operations
(e.g., cluster creation always requires `gcloud` or MCP).

--------------------------------------------------------------------------------

> All MCP tools use hierarchical resource paths — see
> [`parent` format](#parent--name-format-quick-reference) at the bottom.

## Cluster Operations

| Operation           | MCP Tool         | CLI Fallback       | Mode        |
| ------------------- | ---------------- | ------------------ | ----------- |
| List clusters       | `list_clusters`  | `gcloud container  | READ        |
:                     :                  : clusters list`     :             :
| Get cluster details | `get_cluster`    | `gcloud container  | READ        |
:                     :                  : clusters describe` :             :
| Create cluster      | `create_cluster` | `gcloud container  | MUTATE      |
:                     :                  : clusters           :             :
:                     :                  : create-auto`       :             :
| Update cluster      | `update_cluster` | `gcloud container  | DESTRUCTIVE |
:                     :                  : clusters update`   :             :
| Get K8s versions    | —                | `gcloud container  | READ        |
:                     :                  : get-server-config` :             :
| Get credentials     | —                | `gcloud container  | READ        |
:                     :                  : clusters           :             :
:                     :                  : get-credentials`   :             :
| Delete cluster      | —                | `gcloud container  | DESTRUCTIVE |
:                     :                  : clusters delete`   :             :

```
# List clusters in a project (all regions)
list_clusters(parent="projects/<PROJECT_ID>/locations/-")

# Get cluster details (all fields)
get_cluster(name="projects/<PROJECT_ID>/locations/<REGION>/clusters/<CLUSTER_NAME>", readMask="*")

# Create golden path Autopilot cluster
create_cluster(
  parent="projects/<PROJECT_ID>/locations/<REGION>",
  cluster='{"name":"<CLUSTER_NAME>","autopilot":{"enabled":true},"privateClusterConfig":{"enablePrivateNodes":true},...}'
)
```

```bash
# Get available Kubernetes versions (CLI-only)
gcloud container get-server-config --region <REGION> --format="yaml(channels)" --quiet

# Create golden path Autopilot cluster (see gke-cluster-creation.md for full templates)
gcloud container clusters create-auto <CLUSTER_NAME> \
  --region <REGION> --project <PROJECT_ID> \
  --enable-private-nodes --enable-master-authorized-networks \
  --enable-dns-access --release-channel regular \
  --enable-secret-manager --scoped-rbs-bindings \
  --quiet

# Get credentials (CLI-only)
gcloud container clusters get-credentials <CLUSTER_NAME> --region <REGION> --project <PROJECT_ID> --quiet
```

## Node Pool Operations

| Operation        | MCP Tool           | CLI Fallback         | Mode        |
| ---------------- | ------------------ | -------------------- | ----------- |
| List node pools  | `list_node_pools`  | `gcloud container    | READ        |
:                  :                    : node-pools list`     :             :
| Get node pool    | `get_node_pool`    | `gcloud container    | READ        |
:                  :                    : node-pools describe` :             :
| Create node pool | `create_node_pool` | `gcloud container    | MUTATE      |
:                  :                    : node-pools create`   :             :
| Update node pool | `update_node_pool` | `gcloud container    | DESTRUCTIVE |
:                  :                    : node-pools update`   :             :

```
list_node_pools(parent="projects/<PROJECT_ID>/locations/<REGION>/clusters/<CLUSTER_NAME>")

create_node_pool(
  parent="projects/<PROJECT_ID>/locations/<REGION>/clusters/<CLUSTER_NAME>",
  nodePool='{"name":"<POOL_NAME>","config":{"machineType":"e2-standard-4"},"initialNodeCount":3,...}'
)
```

## Cluster Updates

| Operation         | MCP Tool         | CLI Fallback            | Mode        |
| ----------------- | ---------------- | ----------------------- | ----------- |
| Update cluster    | `update_cluster` | `gcloud container       | DESTRUCTIVE |
: settings          :                  : clusters update`        :             :
| Update monitoring | —                | `gcloud container       | DESTRUCTIVE |
:                   :                  : clusters update         :             :
:                   :                  : --monitoring=...`       :             :
| Set maintenance   | —                | `gcloud container       | DESTRUCTIVE |
: window            :                  : clusters update         :             :
:                   :                  : --maintenance-window-*` :             :

```
# Enable VPA via MCP
update_cluster(
  name="projects/<PROJECT_ID>/locations/<REGION>/clusters/<CLUSTER_NAME>",
  update='{"desiredVerticalPodAutoscaling":{"enabled":true}}'
)
```

```bash
# Update monitoring components (CLI-only)
gcloud container clusters update <CLUSTER_NAME> --region <REGION> \
  --monitoring=SYSTEM,API_SERVER,SCHEDULER,CONTROLLER_MANAGER,STORAGE,POD,DEPLOYMENT,STATEFULSET,DAEMONSET,HPA \
  --quiet
```

## Kubernetes Resource Operations

| Operation       | MCP Tool                 | CLI Fallback     | Mode        |
| --------------- | ------------------------ | ---------------- | ----------- |
| Get/list        | `get_k8s_resource`       | `kubectl get`    | READ        |
: resources       :                          :                  :             :
| Describe        | `describe_k8s_resource`  | `kubectl         | READ        |
: resource        :                          : describe`        :             :
| Apply manifest  | `apply_k8s_manifest`     | `kubectl apply`  | DESTRUCTIVE |
| Patch resource  | `patch_k8s_resource`     | `kubectl patch`  | DESTRUCTIVE |
| Delete resource | `delete_k8s_resource`    | `kubectl delete` | DESTRUCTIVE |
| List API        | `list_k8s_api_resources` | `kubectl         | READ        |
: resources       :                          : api-resources`   :             :
| Check auth      | `check_k8s_auth`         | `kubectl auth    | READ        |
:                 :                          : can-i`           :             :

```
# List all deployments in a namespace
get_k8s_resource(
  parent="projects/<PROJECT_ID>/locations/<REGION>/clusters/<CLUSTER_NAME>",
  resourceType="deployment", namespace="<NAMESPACE>"
)

# Apply a manifest (with dry-run)
apply_k8s_manifest(parent="...", yamlManifest="...", dryRun=true)

# Patch deployment resources for rightsizing
patch_k8s_resource(
  parent="projects/<PROJECT_ID>/locations/<REGION>/clusters/<CLUSTER_NAME>",
  resourceType="deployment", name="<DEPLOYMENT>", namespace="<NAMESPACE>",
  patch='{"spec":{"template":{"spec":{"containers":[{"name":"app","resources":{"requests":{"cpu":"200m","memory":"256Mi"}}}]}}}}'
)

# Check RBAC permissions
check_k8s_auth(parent="...", verb="create", resourceType="deployments", namespace="<NAMESPACE>")
```

## Diagnostics & Observability

Operation           | MCP Tool                 | CLI Fallback             | Mode
------------------- | ------------------------ | ------------------------ | ----
List events         | `list_k8s_events`        | `kubectl events`         | READ
Get container logs  | `get_k8s_logs`           | `kubectl logs`           | READ
Cluster info        | `get_k8s_cluster_info`   | `kubectl cluster-info`   | READ
K8s version         | `get_k8s_version`        | `kubectl version`        | READ
Rollout status      | `get_k8s_rollout_status` | `kubectl rollout status` | READ
Query Cloud Logging | —                        | `gcloud logging read`    | READ

```
# Get recent events across all namespaces
list_k8s_events(parent="...", allNamespaces=true, limit="50")

# Get logs (last 100 lines, or previous crash)
get_k8s_logs(parent="...", name="<POD>", namespace="<NS>", tail="100")
get_k8s_logs(parent="...", name="<POD>", namespace="<NS>", previous=true)

# Check rollout status
get_k8s_rollout_status(parent="...", resourceType="deployment", name="<DEPLOY>", namespace="<NS>")
```

## Operations Tracking

| Operation        | MCP Tool           | CLI Fallback         | Mode        |
| ---------------- | ------------------ | -------------------- | ----------- |
| List operations  | `list_operations`  | `gcloud container    | READ        |
:                  :                    : operations list`     :             :
| Get operation    | `get_operation`    | `gcloud container    | READ        |
:                  :                    : operations describe` :             :
| Cancel operation | `cancel_operation` | `gcloud container    | DESTRUCTIVE |
:                  :                    : operations cancel`   :             :

```
list_operations(parent="projects/<PROJECT_ID>/locations/<REGION>")
get_operation(name="projects/<PROJECT_ID>/locations/<REGION>/operations/<OP_ID>")
```

## AI/ML Inference (GIQ) — CLI-Only

```bash
gcloud container ai profiles models list --quiet
gcloud container ai profiles list --model=<MODEL_NAME> --quiet
gcloud container ai profiles manifests create \
  --model=<MODEL_NAME> --model-server=<SERVER> \
  --accelerator-type=<ACCELERATOR> \
  --target-ntpot-milliseconds=<NTPOT> --quiet > inference.yaml

# Deploy generated manifest via MCP
apply_k8s_manifest(parent="...", yamlManifest="<contents of inference.yaml>")
```

## kubectl-Only Operations

No MCP or `gcloud` equivalent:

```bash
kubectl top pods --all-namespaces --sort-by=cpu
kubectl top nodes
kubectl scale deployment <DEPLOYMENT> --replicas=<N> -n <NAMESPACE>
kubectl exec -it <POD_NAME> -n <NAMESPACE> -- /bin/sh
kubectl port-forward svc/<SERVICE> <LOCAL_PORT>:<REMOTE_PORT> -n <NAMESPACE>
kubectl cp <NAMESPACE>/<POD>:<PATH> <LOCAL_PATH>
kubectl run debug --rm -it --image=busybox -- /bin/sh
kubectl drain <NODE_NAME> --ignore-daemonsets --delete-emptydir-data
helm install <RELEASE> <CHART> -n <NAMESPACE>
helm upgrade <RELEASE> <CHART> -n <NAMESPACE>
```

## `parent` / `name` Format Quick Reference

```
Project+Region:  projects/{PROJECT}/locations/{REGION}
Cluster:         projects/{PROJECT}/locations/{REGION}/clusters/{CLUSTER}
Node Pool:       projects/{PROJECT}/locations/{REGION}/clusters/{CLUSTER}/nodePools/{POOL}
Operation:       projects/{PROJECT}/locations/{REGION}/operations/{OP_ID}
```

Use `locations/-` to match all regions/zones when listing.

## Error Handling

Error / Symptom                       | Likely Cause                                 | Remediation
------------------------------------- | -------------------------------------------- | -----------
`PERMISSION_DENIED` on cluster create | Missing `container.clusters.create` IAM role | Grant `roles/container.admin` or `roles/container.clusterAdmin`
Quota exceeded                        | Regional vCPU, GPU, or IP address limits     | Request quota increase or select a different region
IP exhaustion / CIDR conflict         | Pod subnet too small or overlapping ranges   | Re-plan IP ranges; may require cluster recreation (Day-0)
Workload Identity not working         | Missing OIDC issuer or federated credential  | Verify `workloadIdentityConfig.workloadPool`; configure federated identity binding
Private cluster unreachable           | No authorized networks or DNS endpoint       | Enable `dnsEndpointConfig.allowExternalTraffic` or add authorized networks
Secret Manager rotation failing       | SA missing `secretmanager.versions.access`   | Grant Secret Manager accessor role to workload's GSA
Control-plane metrics missing         | Monitoring components not configured         | Enable APISERVER, SCHEDULER, CONTROLLER_MANAGER in `monitoringConfig`

````


### `references/client-library-usage.md`

````markdown
# GKE Client Libraries

To interact with the GKE (Kubernetes) API programmatically, use the official
Kubernetes client libraries.

**Prerequisite:** These libraries interact with the Kubernetes API. You must
already have a running GKE cluster and valid credentials (for example, by
running `gcloud container clusters get-credentials`) before running this code.

## Getting Started

Kubernetes client libraries allow you to manage clusters and workloads from
within your application code.

### Python

-   **Installation:**

    ```bash
    pip install kubernetes
    ```

-   **Usage Example:**

    ```python
    from kubernetes import client, config
    config.load_kube_config() # Loads from ~/.kube/config
    v1 = client.CoreV1Api()
    print("Listing pods with their IPs:")
    ret = v1.list_pod_for_all_namespaces(watch=False)
    for i in ret.items:
        print("%s\t%s\t%s" % (i.status.pod_ip, i.metadata.namespace, i.metadata.name))
    ```

### Go

-   **Installation:**

    ```bash
    go get k8s.io/client-go@latest
    ```

-   **Usage Example:**

    ```go
    import (
        "k8s.io/client-go/kubernetes"
        "k8s.io/client-go/tools/clientcmd"
    )
    config, _ := clientcmd.BuildConfigFromFlags("", kubeconfig)
    clientset, _ := kubernetes.NewForConfig(config)
    pods, _ := clientset.CoreV1().Pods("").List(
        context.Background(), metav1.ListOptions{})
    ```

### Node.js (TypeScript)

-   **Installation:**

    ```bash
    npm install @kubernetes/client-node
    ```

-   **Usage Example:**

    ```javascript
    const k8s = require('@kubernetes/client-node');

    const kc = new k8s.KubeConfig();
    kc.loadFromDefault(); // Automatically detects local vs. in-cluster configuration

    const k8sApi = kc.makeApiClient(k8s.CoreV1Api);

    // In most recent library versions, parameters must be passed inside an object
    k8sApi.listNamespacedPod({ namespace: 'default' }).then((res) => {
        const pods = res.items || res.body.items;
        console.log(`Found ${pods.length} pods in 'default' namespace.`);
    });
    ```

### Java

-   [Java Reference](https://github.com/kubernetes-client/java)

## GKE-specific API (Container Service)

To manage the GKE *service* itself (e.g., create/delete clusters)
programmatically, use the Google Cloud Container client libraries.

-   [Google Cloud Container Client Libraries](https://cloud.google.com/kubernetes-engine/docs/reference/libraries)

````


### `references/core-concepts.md`

```markdown
# GKE Core Concepts

Google Kubernetes Engine (GKE) is a managed Kubernetes platform for deploying,
managing, and scaling containerized applications on Google Cloud infrastructure.
It handles cluster provisioning, upgrades, and node management, letting teams
focus on workloads rather than infrastructure.

> **MCP Tools:** `list_clusters`, `get_cluster`

## Cluster Modes

| Mode          | Who Manages Nodes            | Best For                      |
| ------------- | ---------------------------- | ----------------------------- |
| **Autopilot** | Google — fully managed       | Most workloads. No node-level |
: (recommended) : nodes, scaling, and security : ops. Pay per pod resource     :
:               :                              : request.                      :
| **Standard**  | You — full control over node | Workloads requiring kernel    |
:               : pools, OS, machine types     : customization, specific node  :
:               :                              : OS, or DaemonSets not         :
:               :                              : supported by Autopilot        :

**Default: Autopilot.** Use Standard only when Autopilot has a documented
limitation for your workload.

## Cluster Architecture

-   **Regional clusters** (recommended): Control plane replicated across 3
    zones. Higher availability, no single-zone failure risk.
-   **Zonal clusters**: Single control plane zone. Lower cost, acceptable for
    dev/test.
-   **Private clusters** (golden path default): Nodes have no public IPs.
    Control plane accessible via private endpoint or DNS endpoint.

## Networking Model

GKE uses **VPC-native** clusters with alias IP ranges:

-   Each pod gets a routable IP from the pod CIDR
-   Dataplane V2 (eBPF-based) is the golden path default — provides built-in
    Network Policy enforcement
-   Cloud DNS for in-cluster DNS resolution
-   Gateway API for ingress/load balancing

## Scaling Model

-   **Horizontal Pod Autoscaler (HPA)**: Scales pod replicas based on CPU,
    memory, or custom metrics
-   **Vertical Pod Autoscaler (VPA)**: Recommends or auto-adjusts pod resource
    requests
-   **Cluster Autoscaler / NAP**: Scales nodes to match pod demand (Autopilot
    handles this automatically)
-   **ComputeClasses**: Declarative node selection — machine family, Spot VMs,
    GPU targeting

## Identity & Security Model

-   **Workload Identity Federation**: Pods assume Google Cloud IAM identities
    without static keys
-   **Secret Manager integration**: Secrets synced to Kubernetes with automatic
    rotation
-   **Pod Security Standards**: `restricted` profile enforced on production
    namespaces
-   **Shielded Nodes**: Secure Boot and integrity monitoring
    (Autopilot-enforced)

## Regional Availability

GKE is available in all Google Cloud regions. Autopilot clusters are regional by
default. See https://cloud.google.com/about/locations for the full region list.

## Pricing

GKE pricing depends on the cluster mode:

-   **Autopilot**: Pay for pod resource requests (vCPU, memory, ephemeral
    storage). No cluster management fee.
-   **Standard**: Pay for underlying Compute Engine VMs plus a per-cluster
    management fee.

For current pricing, see https://cloud.google.com/kubernetes-engine/pricing.

```


### `references/iac-usage.md`

````markdown
# GKE Infrastructure as Code

GKE resources, including clusters and Kubernetes objects, can be provisioned and
managed using Terraform.

## Terraform

Terraform uses two main providers for GKE:

*   The **Google Cloud provider** connects to the Google Cloud API to manage GKE
    cluster infrastructure using Terraform resources such as
    `google_container_cluster` for the cluster itself, and
    `google_container_node_pool` for nodes in Standard mode.
*   The **Kubernetes provider** connects to the Kubernetes API to manage
    workloads inside the cluster using Kubernetes resources such as Deployments
    and Services.

### GKE Autopilot Cluster Example

```hcl
resource "google_container_cluster" "primary" {
  name     = "my-gke-cluster"
  location = "us-central1"

  enable_autopilot = true

  # Do NOT specify node configurations (like initial_node_count or node_config)
  # in Autopilot mode; doing so causes a Terraform provider error.

  # Deletion protection should be set to false for testing
  deletion_protection = false
}
```

### Deploying a Workload Example (Kubernetes Provider)

```hcl
resource "kubernetes_deployment_v1" "default" {
  metadata {
    name = "hello-app"
  }
  spec {
    replicas = 2
    selector {
      match_labels = {
        app = "hello-app"
      }
    }
    template {
      metadata {
        labels = {
          app = "hello-app"
        }
      }
      spec {
        container {
          image = "us-docker.pkg.dev/google-samples/containers/gke/hello-app:2.0"
          name  = "hello-app"
        }
      }
    }
  }
}
```

### Reference Documentation

-   [Terraform Google Provider - Container Cluster](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/container_cluster)

-   [Terraform Google Provider - Kubernetes Provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs)

## YAML Samples

GKE cluster configurations and Kubernetes manifests can also be defined using
YAML for use with `kubectl apply` or Deployment Manager.

-   [GKE YAML Samples](https://docs.cloud.google.com/docs/samples?product=googlekubernetesengine)

````


### `references/mcp-usage.md`

````markdown
# GKE MCP Server Usage

The GKE MCP server provides 23 structured tools for cluster management,
Kubernetes resource operations, and diagnostics — without requiring shell access
or kubeconfig setup.

## Connecting to the GKE MCP Server

The GKE remote MCP server is available for AI clients that support the Model
Context Protocol. For setup instructions, see
https://docs.cloud.google.com/kubernetes-engine/docs/how-to/use-gke-mcp.md.txt

## Available Tools

All tools use hierarchical resource paths:

```
Project+Region:  projects/{PROJECT}/locations/{REGION}
Cluster:         projects/{PROJECT}/locations/{REGION}/clusters/{CLUSTER}
Node Pool:       projects/{PROJECT}/locations/{REGION}/clusters/{CLUSTER}/nodePools/{POOL}
Operation:       projects/{PROJECT}/locations/{REGION}/operations/{OP_ID}
```

Use `locations/-` to match all regions when listing.

### Cluster Management

| Tool             | Mode        | Purpose                                   |
| ---------------- | ----------- | ----------------------------------------- |
| `list_clusters`  | READ        | Discover clusters in a project/region     |
| `get_cluster`    | READ        | Inspect cluster config. Use `readMask` to |
:                  :             : select fields                             :
| `create_cluster` | MUTATE      | Create a cluster from JSON config         |
| `update_cluster` | DESTRUCTIVE | Change Day-1 cluster settings             |

### Node Pool Management

Tool               | Mode        | Purpose
------------------ | ----------- | ------------------------------
`list_node_pools`  | READ        | List pools in a cluster
`get_node_pool`    | READ        | Get pool details
`create_node_pool` | MUTATE      | Add a pool (Standard clusters)
`update_node_pool` | DESTRUCTIVE | Modify a pool

### Kubernetes Resources

| Tool                     | Mode        | Purpose                             |
| ------------------------ | ----------- | ----------------------------------- |
| `get_k8s_resource`       | READ        | List/get any K8s resource (supports |
:                          :             : label/field selectors)              :
| `describe_k8s_resource`  | READ        | Detailed info with events and       |
:                          :             : conditions                          :
| `apply_k8s_manifest`     | DESTRUCTIVE | Apply YAML manifests (supports      |
:                          :             : `dryRun`)                           :
| `patch_k8s_resource`     | DESTRUCTIVE | JSON patch resource fields          |
| `delete_k8s_resource`    | DESTRUCTIVE | Remove resources (supports          |
:                          :             : `cascade`, `dryRun`)                :
| `list_k8s_api_resources` | READ        | Discover available resource types   |

### Diagnostics & Observability

| Tool                     | Mode | Purpose                                   |
| ------------------------ | ---- | ----------------------------------------- |
| `list_k8s_events`        | READ | Scheduling failures, OOM kills, evictions |
| `get_k8s_logs`           | READ | Container logs (supports `tail`, `since`, |
:                          :      : `previous`)                               :
| `get_k8s_cluster_info`   | READ | Control plane and service endpoints       |
| `get_k8s_version`        | READ | Kubernetes server version                 |
| `get_k8s_rollout_status` | READ | Deployment/StatefulSet rollout progress   |
| `check_k8s_auth`         | READ | Verify RBAC permissions for a user/SA     |

### Operations

Tool               | Mode        | Purpose
------------------ | ----------- | ----------------------------------
`list_operations`  | READ        | Pending/running cluster operations
`get_operation`    | READ        | Track create/upgrade progress
`cancel_operation` | DESTRUCTIVE | Abort stuck operations

## Tool Preference

Default: **MCP tools > gcloud CLI > kubectl**. See
[cli-reference.md](./cli-reference.md) for the full coverage comparison, CLI
fallback commands, and user preference override options.

````