GKE Cluster Creation

This reference guides creating Google Kubernetes Engine (GKE) clusters by providing a set of best-practice templates and guiding through mode selection and customization. The golden path Autopilot configuration is the default for all new clusters.

MCP Tools: list_clusters, create_cluster, get_cluster, list_operations, get_operation

Workflow

1. Discover context: Use list_clusters to see existing clusters. Use gcloud config get-value project if project unknown.
2. Gather inputs: project_id, location (region or zone), cluster_name, environment type. If missing essential details, ask the user before taking action.
3. Select mode & explain trade-offs: If the user hasn't specified a template or mode, present the available templates (e.g., Autopilot, Standard Regional, GPU Inference, AI Hypercompute) and explain key trade-offs (Cost vs. Availability, Autopilot vs. Standard node management).
4. Configure networking: auto-create subnet (default) or bring-your-own.
5. Review golden path settings: present the default configuration block (gcloud command or create_cluster JSON payload) and confirm with the user before creation.
6. Create: Use MCP create_cluster tool or gcloud CLI.
7. Track: Use get_operation to monitor creation progress.
8. Verify: Use get_cluster with readMask="*" to confirm golden path settings applied.

Mode Selection

Criteria	Autopilot (Golden Path)	Standard
Node management	Google-managed	Self-managed
Pricing	Pay per pod resource	Pay per node (VM)
: : request : :
Node customization	Via ComputeClasses	Full control
DaemonSets	Allowed (with	Full control
: : restrictions) : :
GPU/TPU	Supported via	Supported via node pools
: : ComputeClasses : :
Best for	Most production workloads	Kernel tuning, custom OS,
: : : privileged workloads :

Rule: Default to Autopilot unless the customer has a specific requirement that Autopilot cannot satisfy.

Best Practices

When guiding the user or generating configurations, adhere to these GKE best practices:

Security & Networking

1. Private Clusters: Default to private clusters (enablePrivateNodes: true) with a private control plane and restricted public endpoints (enable-master-authorized-networks) to minimize attack surface.
2. VPC-Native Networking: Use VPC-native clusters (useIpAliases: true / --enable-ip-alias) to enable alias IP ranges and pod-level firewall rules.
3. Workload Identity: Prefer Workload Identity (workloadPool: <PROJECT_ID>.svc.id.goog) for securely granting GKE workloads access to Google Cloud services instead of static service account keys.
4. Shielded GKE Nodes: Enable Shielded GKE Nodes (--enable-shielded-nodes, --enable-secure-boot) against rootkits and bootkits.
5. Least Privilege (RBAC): Institute strict Role-Based Access Control limits (scoped-rbs-bindings).

Cost Optimization

1. Autoscaling: Enable Cluster Autoscaler and Horizontal/Vertical Pod Autoscaler (--enable-autoscaling, --enable-vertical-pod-autoscaling) to adjust resources based on demand.
2. Right-Sizing & Spot VMs: Choose appropriate machine types and node counts. Consider Spot VMs (--spot) for fault-tolerant, non-critical batch or inference workloads.

High Availability & Reliability

1. Regional Clusters: Use Regional Clusters for production environments to ensure control plane replication across multiple zones (--region instead of --zone). Note: Standard regional creates nodes across 3 zones by default.
2. Pod Disruption Budgets: Recommend setting Pod Disruption Budgets for application stability during node maintenance.
3. Release Channels: Subscribe to a release channel (REGULAR or STABLE) for automated, safer cluster upgrades.

Templates

1. Golden Path Autopilot (Production)

This is the default. All settings match ../gke-golden-path/assets/golden-path-autopilot.yaml.

Via gcloud:

gcloud container clusters create-auto <CLUSTER_NAME> \
  --region <REGION> \
  --project <PROJECT_ID> \
  --release-channel regular \
  --enable-private-nodes \
  --enable-master-authorized-networks \
  --enable-dns-access \
  --enable-secret-manager \
  --secret-manager-rotation-interval=120s \
  --scoped-rbs-bindings \
  --monitoring=SYSTEM,API_SERVER,SCHEDULER,CONTROLLER_MANAGER,STORAGE,POD,DEPLOYMENT,STATEFULSET,DAEMONSET,HPA,CADVISOR,KUBELET,DCGM \
  --quiet

Via MCP (create_cluster):

{
  "parent": "projects/<PROJECT_ID>/locations/<REGION>",
  "cluster": {
    "name": "<CLUSTER_NAME>",
    "autopilot": { "enabled": true },
    "privateClusterConfig": { "enablePrivateNodes": true },
    "masterAuthorizedNetworksConfig": {
      "privateEndpointEnforcementEnabled": true
    },
    "releaseChannel": { "channel": "REGULAR" },
    "secretManagerConfig": {
      "enabled": true,
      "rotationConfig": { "enabled": true, "rotationInterval": "120s" }
    },
    "rbacBindingConfig": {
      "enableInsecureBindingSystemAuthenticated": false,
      "enableInsecureBindingSystemUnauthenticated": false
    }
  }
}

2. Autopilot Dev/Test

Relaxes some golden path defaults for cost savings and easier access in non-production.

Via gcloud:

gcloud container clusters create-auto <CLUSTER_NAME> \
  --region <REGION> \
  --project <PROJECT_ID> \
  --release-channel rapid \
  --quiet

Via MCP (create_cluster):

{
  "parent": "projects/<PROJECT_ID>/locations/<REGION>",
  "cluster": {
    "name": "<CLUSTER_NAME>",
    "autopilot": { "enabled": true },
    "releaseChannel": { "channel": "RAPID" }
  }
}

Warning: This does not apply golden path security hardening. Suitable for dev/test only.

3. Standard Regional (High Availability / Custom Requirements)

Best when Autopilot cannot be used (e.g., custom kernel tuning, specific node OS requirements). Creates 3 nodes across zones by default.

Via gcloud:

gcloud container clusters create <CLUSTER_NAME> \
  --region <REGION> \
  --project <PROJECT_ID> \
  --num-nodes 3 \
  --machine-type e2-standard-4 \
  --disk-type pd-balanced \
  --enable-autoscaling --min-nodes 1 --max-nodes 10 \
  --enable-shielded-nodes --enable-secure-boot \
  --workload-pool=<PROJECT_ID>.svc.id.goog \
  --enable-private-nodes \
  --enable-master-authorized-networks \
  --enable-vertical-pod-autoscaling \
  --enable-dataplane-v2 \
  --release-channel regular \
  --quiet

Via MCP (create_cluster):

{
  "parent": "projects/<PROJECT_ID>/locations/<REGION>",
  "cluster": {
    "name": "<CLUSTER_NAME>",
    "initialNodeCount": 3,
    "nodeConfig": {
      "machineType": "e2-standard-4",
      "diskType": "pd-balanced",
      "diskSizeGb": 100,
      "oauthScopes": ["https://www.googleapis.com/auth/cloud-platform"],
      "shieldedInstanceConfig": {
        "enableSecureBoot": true,
        "enableIntegrityMonitoring": true
      },
      "workloadMetadataConfig": {
        "mode": "GKE_METADATA"
      }
    },
    "privateClusterConfig": { "enablePrivateNodes": true },
    "releaseChannel": { "channel": "REGULAR" },
    "workloadIdentityConfig": {
      "workloadPool": "<PROJECT_ID>.svc.id.goog"
    }
  }
}

4. GPU Inference & AI Workloads (L4 / ComputeClass)

Best for: AI/ML Inference, small model serving. Can be provisioned via Autopilot + ComputeClass or via Standard node pool with g2-standard-4 (nvidia-l4). Note: Requires g2-standard-4 quota.

Autopilot ComputeClass / GIQ approach:

# 1. Create golden path cluster (same as template 1)
gcloud container clusters create-auto <CLUSTER_NAME> \
  --region <REGION> --project <PROJECT_ID> \
  --enable-private-nodes --enable-master-authorized-networks \
  --enable-dns-access --enable-secret-manager --scoped-rbs-bindings \
  --quiet

# 2. Apply GPU ComputeClass (see gke-compute-classes.md)
kubectl apply -f gpu-compute-class.yaml

# 3. Or use GIQ for inference (see gke-inference.md)
gcloud container ai profiles manifests create \
  --model=gemma-2-9b-it --model-server=vllm --accelerator-type=nvidia-l4 --quiet > inference.yaml
kubectl apply -f inference.yaml

Standard Node Pool approach via MCP (create_cluster):

{
  "parent": "projects/<PROJECT_ID>/locations/<REGION>",
  "cluster": {
    "name": "<CLUSTER_NAME>",
    "initialNodeCount": 1,
    "nodeConfig": {
      "machineType": "g2-standard-4",
      "accelerators": [
        {
          "acceleratorCount": "1",
          "acceleratorType": "nvidia-l4"
        }
      ],
      "diskSizeGb": 100,
      "oauthScopes": ["https://www.googleapis.com/auth/cloud-platform"]
    }
  }
}

5. AI Hypercompute (A3 HighGPU / Large Model Serving)

Best for: Large-scale LLM / AI model training and hypercompute inference. Note: High hourly cost and strict quota requirements (a3-highgpu-8g / nvidia-h100-80gb-hbm3).

Via gcloud:

gcloud container clusters create <CLUSTER_NAME> \
  --region <REGION> \
  --project <PROJECT_ID> \
  --num-nodes 1 \
  --machine-type a3-highgpu-8g \
  --accelerator type=nvidia-h100-80gb-hbm3,count=8 \
  --disk-size 200 \
  --scopes https://www.googleapis.com/auth/cloud-platform \
  --workload-pool=<PROJECT_ID>.svc.id.goog \
  --release-channel regular \
  --quiet

Via MCP (create_cluster):

{
  "parent": "projects/<PROJECT_ID>/locations/<REGION>",
  "cluster": {
    "name": "<CLUSTER_NAME>",
    "initialNodeCount": 1,
    "nodeConfig": {
      "machineType": "a3-highgpu-8g",
      "accelerators": [
        {
          "acceleratorCount": "8",
          "acceleratorType": "nvidia-h100-80gb-hbm3"
        }
      ],
      "diskSizeGb": 200,
      "oauthScopes": ["https://www.googleapis.com/auth/cloud-platform"]
    }
  }
}

Instructions

• ALWAYS ask for project_id if not in context.
• ALWAYS ask for region (or location).
• ALWAYS ask for a unique cluster_name.
• DEFAULT to golden path Autopilot unless customer specifies otherwise or has custom node/kernel/hypercompute requirements.
• ALWAYS WARN when deviating to GKE Standard, highlighting that it deviates from the golden path and explaining the added operational/management overhead (manually managing node pools, upgrades, and autoscaling).
• EXPLAIN TRADE-OFFS when presenting templates or mode choices to the user if they haven't specified one (e.g., Autopilot vs Standard, Cost vs Availability).
• PRESENT THE CONFIGURATION block (gcloud command or JSON payload) and ask for confirmation before calling any creation tool.
• WARN about Day-0 decisions (networking, private nodes) that are hard to change later.
• WARN explicitly about cost and quota requirements when the user selects GPU (g2-standard-4, a3-highgpu-8g), TPU, or multi-region/regional clusters (--region defaults to 3 zones).
• When using MCP create_cluster, the cluster.name parameter should be the short name (e.g., my-cluster), not the full resource path (projects/<PROJECT_ID>/locations/<REGION>/clusters/<CLUSTER_NAME>). The parent parameter defines the scope (projects/<PROJECT_ID>/locations/<REGION>).

Required final step: provision the Cluster Agent profile

Creating a cluster is not complete until it has a Cluster Agent. A managed cluster and its Cluster Agent profile are created together — never leave a newly created cluster without a profile. Immediately after create_cluster succeeds and the cluster is reachable, create its dedicated Cluster Agent profile (this is what makes the cluster delegable for runtime debugging). Use the cluster-agent-lifecycle skill:

python3 /opt/data/scripts/cluster_agent_profile.py create \
  --project "<project>" --cluster "<cluster>" --location "<location>"

The command is idempotent, so it is safe to re-run. This gives the new cluster an agent immediately. (The cluster-agent-reconcile cron would also pick it up on its next run — it manages every cluster in the project, so no labeling is required.)

Cluster Agent Profile Teardown

A managed cluster and its Cluster Agent profile are deleted together. When a cluster is decommissioned/deleted, also remove its dedicated Cluster Agent profile (created at onboarding). Use the cluster-agent-lifecycle skill:

python3 /opt/data/scripts/cluster_agent_profile.py delete \
  --project "<project>" --cluster "<cluster>" --location "<location>"

Do not delete a Cluster Agent profile while its cluster still exists.

Deleting the profile here is the immediate, preferred path. As a backstop, the hourly cluster-agent-reconcile job auto-prunes any profile whose cluster is definitively gone, so a profile missed during teardown is cleaned up on the next reconcile cycle.