walkthrough-hostedcluster-create

name	walkthrough-hostedcluster-create
description	Guided exploration of the HostedCluster create flow from API types through GKE provisioning
user-invocable	false
disable-model-invocation	true

HostedCluster Create Flow

Trace the end-to-end flow of creating a HostedCluster on GCP — from API definition through controller reconciliation to GKE cluster provisioning and status updates.

Layer 1 — API Types

Start here. Find the HostedCluster API type definition in the hypershift repository. Show me:

• The HostedClusterSpec and HostedClusterStatus structures
• The GCP-specific platform configuration within the spec (look for the GCP platform type)
• What GCP resources are encoded in the API types — what does a user declare when they want a cluster on GCP?
• How the API types relate to the Kubernetes CRD that gets installed

Help me understand: the API types are the contract. Everything downstream is driven by what's declared here.

Layer 2 — Validation and Admission

Trace how HostedCluster creation requests are validated before they reach the controller. Find:

• Webhook validators for the HostedCluster resource
• GCP-specific validation logic — what GCP-specific fields are validated and why?
• What preconditions must be met before a cluster can be created?
• How validation errors are surfaced to the user

Help me understand: validation is the first line of defense. It catches misconfigurations before they become expensive reconciliation failures.

Layer 3 — Controller Reconciliation

This is the core of the system. Find the HostedCluster controller and trace its reconcile function. Show me:

• How the controller detects a new HostedCluster (watch, queue, reconcile loop)
• The structure of the reconciliation — is it a single function or broken into phases/sub-reconcilers?
• How the controller delegates to platform-specific (GCP) logic
• Error handling and retry patterns — what happens when a reconciliation step fails?
• How the controller manages the lifecycle of child resources (what other Kubernetes objects does it create?)

Help me understand: the reconcile loop is the engine. It continuously drives the actual state toward the desired state declared in the API types.

Layer 4 — GCP API Interactions

Trace from the controller into the GCP-specific provisioning code. Show me:

• Where and how GKE clusters are created (the actual GCP API calls)
• Network and VPC setup — how networking is configured for the hosted cluster
• IAM and service account configuration
• How Workload Identity Federation (WIF) is set up for the cluster
• How the code authenticates to GCP APIs

Help me understand: this layer bridges the Kubernetes abstraction to the cloud provider reality. The patterns here (credential management, API error handling, resource lifecycle) repeat across all GCP interactions.

Layer 5 — Status Updates

Follow how provisioning status flows back to the HostedCluster object. Show me:

• How status conditions are updated as provisioning progresses
• How errors from GCP API calls are surfaced in the status
• The progression from initial creation through to the cluster being available
• What external systems or users watch these status conditions

Help me understand: status is the feedback loop. It's how the system communicates progress, failures, and health — both to operators and to other controllers that depend on the HostedCluster being ready.

Cross-Cutting Concerns

As you trace the flow, also point out these patterns when you encounter them:

• Secrets and credentials — How are GCP credentials managed? Where are they stored? How do they flow through the system? Describe storage locations and data flow only — never output actual credential values, tokens, keys, passwords, client secrets, or PII.
• Observability — What logging, metrics, and Kubernetes events are emitted? How would an operator debug a failed provisioning?
• Error handling — How does the code handle GCP API rate limiting, transient failures, or resource conflicts?
• Testing — What test patterns exist for the GCP platform code? How is the controller tested?

Design Context

Throughout the exploration, reference the design decisions documented in this repository (design-decisions/) to explain why certain architectural choices were made.