Cluster Lifecycle and Control Plane

The hosted cluster startup roadmap describes startup dependencies, readiness checks, and the resources to inspect when a HostedCluster has not finished starting.

HostedCluster Lifecycle

Creation

sequenceDiagram
    participant User
    participant HC as HostedCluster
    participant HO as HyperShift Operator
    participant CPNS as CP Namespace
    participant CPO as Control Plane Operator
    participant CAPI as ClusterAPI
    participant NP as NodePool
    participant Cloud as Cloud Provider

    User->>HC: Creates HostedCluster CR
    HO->>HC: Watch & Reconcile
    HO->>HO: Validates release image, config
    HO->>CPNS: Creates namespace<br/>{hc-ns}-{hc-name}
    HO->>CPNS: Copies secrets<br/>(pull-secret, SSH, encryption)
    HO->>CPNS: Creates HostedControlPlane CR
    HO->>CPNS: Deploys CPO Deployment
    HO->>CPNS: Deploys CAPI Manager + Provider
    HO->>CPNS: Configures NetworkPolicies

    CPO->>CPO: Reads HCP, resolves release image
    CPO->>CPNS: Deploys etcd StatefulSet
    CPO->>CPNS: Deploys kube-apiserver
    CPO->>CPNS: Deploys +30 components
    CPO->>HC: Reports status via HCP

    HO->>HC: Copies kubeconfig to user namespace

    User->>NP: Creates NodePool CR
    HO->>NP: Watch & Reconcile
    HO->>CPNS: Creates Token + UserData Secrets
    HO->>CAPI: Creates MachineDeployment + MachineTemplate
    CAPI->>Cloud: Provisions instances
    Cloud-->>CPNS: Nodes boot, fetch ignition
    Cloud-->>HC: Nodes join the guest cluster

Steady State

• The CPO continuously reconciles all components against the HCP spec
• The PKI operator rotates certificates automatically
• The NodePool controller manages auto-repair and scaling
• Status flow: CPO -> HCP status -> HO -> HC status

Upgrade

See also: Upgrades for detailed upgrade procedures and version skew policies.

Control plane and data plane upgrades are decoupled:

graph LR
    subgraph "Control Plane Upgrade"
        A[Change HC.spec.release] --> B[HO updates HCP]
        B --> C[CPO deploys new versions<br/>of components]
    end

    subgraph "Data Plane Upgrade"
        D[Change NP.spec.release] --> E[New config hash]
        E --> F[New token/userdata Secrets]
        F --> G[CAPI rolling update<br/>of MachineDeployment]
    end

    A -.->|independent| D

• controlPlaneRelease: allows patching management-side components without touching the data plane
• NodePool releases can be updated independently (within N-3 y-stream skew)

Deletion

The HO requests NodePool deletion, then CAPI Cluster deletion. CAPI waits for worker descendants before deleting the referenced HCP. The CPO handles HCP cleanup, coordinating with HCCO when guest cloud-resource cleanup is enabled. HO waits for the CAPI Cluster to disappear before removing the HCP namespace. For an AWS CLI destroy, the CLI keeps the HostedCluster present until its remaining infrastructure cleanup finishes.

Follow the AWS teardown roadmap for the deletion gates, controller ownership, finalizer recovery, and cleanup verification.

Control Plane in Detail

CPO Reconciliation Flow

See also: Controller Architecture for the full controller dependency graph and reconciliation details.

flowchart TD
    START[Reconcile HCP] --> FETCH[Fetch HostedControlPlane]
    FETCH --> DEL{Deletion?}
    DEL -->|Yes| CLEANUP[Cleanup cloud resources<br/>Remove finalizer]
    DEL -->|No| FIN[Add finalizer]
    FIN --> VALIDATE[Validate configuration]
    VALIDATE --> ETCD_STATUS[Check etcd status]
    ETCD_STATUS --> KMS[Validate KMS config]
    KMS --> KAS_STATUS[Check KAS availability]
    KAS_STATUS --> INFRA[Setup infrastructure status<br/>endpoints, DNS, routes]
    INFRA --> IGNITION_CFG[Reconcile ignition configs]
    IGNITION_CFG --> OAUTH_PWD[Reconcile kubeadmin password]
    OAUTH_PWD --> CONTEXT[Build ControlPlaneContext]
    CONTEXT --> COMPONENTS[Iterate registered components]

    subgraph "Component Loop"
        COMPONENTS --> C1[Component.Reconcile]
        C1 --> PRED{Predicate<br/>passes?}
        PRED -->|No| DELETE_RES[Delete component resources]
        PRED -->|Yes| DEPS{Dependencies<br/>ready?}
        DEPS -->|No| WAIT[Skip, requeue]
        DEPS -->|Yes| RECONCILE[Reconcile manifests<br/>+ workload]
        RECONCILE --> STATUS_CR[Update ControlPlaneComponent CR]
    end

for _, c := range r.components {
    r.Log.Info("Reconciling component", "component_name", c.Name())
    if err := c.Reconcile(cpContext); err != nil {
        errs = append(errs, err)
    }
}

Component Dependencies

Components reconcile when their dependencies are ready; their registration order does not determine startup order. Most components wait for kube-apiserver. See Foundation components for the dependency graph and exceptions, and Control-plane convergence for dependency conditions and diagnostic checks.

Status Propagation

graph LR
    CPC[ControlPlaneComponent CRs<br/><i>per-component</i><br/>Available / RolloutComplete] --> HCP_STATUS[HCP Status<br/>Conditions:<br/>EtcdAvailable<br/>KubeAPIServerAvailable<br/>ValidConfiguration]
    HCP_STATUS --> HC_STATUS[HC Status<br/>Conditions:<br/>Available<br/>Progressing<br/>Degraded]

    HC_STATUS --> USER[Visible to the user]