Skip to content

HyperShift / Hosted Control Planes (HCP) - Onboarding Guide

How this guide relates to other docs

This is a curated learning path — it provides a structured narrative to help newcomers build a mental model of HyperShift step by step. It intentionally summarizes topics that are covered in more detail in dedicated reference pages. Where applicable, "See also" links point you to the authoritative source for deeper reading. This guide is not a replacement for those docs.

Tips for New Team Members

  1. Start with the CRDs: Understanding HostedCluster, HostedControlPlane, and NodePool is 80% of the work
  2. Follow the data flow: HC -> HCP -> Components. NP -> CAPI -> Cloud -> Node
  3. Conditions are your friend: Always check .status.conditions to understand what's happening
  4. make verify before pushing: Always
  5. The CP namespace is where the magic happens: kubectl get pods -n clusters-<name> shows you everything
  6. Read the tests: Unit tests and E2E tests are the best living documentation
  7. Use hypershift dump: The diagnostic tool at cmd/dump/ captures full cluster state for debugging
  8. Don't read 5000-line files end-to-end: Follow function calls from the Reconcile entry point
  9. The API module is separate: Remember to run make update after any change in api/
  10. Ask about invariants: When in doubt about a design decision, check if it violates any of the architectural invariants
graph TD subgraph "Week 1-2: Foundations" S1A[Read this guide end-to-end] S1B[Install HyperShift locally
make hypershift-install-aws-dev] S1C[Create a test HostedCluster
bin/hypershift create cluster] S1D[Explore the CRDs:
HostedCluster, HCP, NodePool
Read the API type files] S1E[Observe pods in the
CP namespace with kubectl] end subgraph "Week 3-4: Architecture" S2A[Read hostedcluster_controller.go
Understand the reconcile loop] S2B[Read hostedcontrolplane_controller.go
Understand how the CPO
deploys components] S2C[Read nodepool_controller.go
Understand the node flow] S2D[Study the CPOv2 framework
support/controlplane-component/] S2E[Read a simple v2 component
e.g., kube-scheduler] end subgraph "Week 5-6: Deep Dive" S3A[Study the Platform interface
and one implementation
e.g., AWS or KubeVirt] S3B[Understand the ignition flow
Token -> Ignition Server -> Node] S3C[Study PKI and certificates] S3D[Make a real change:
bug fix or small feature] S3E[Run make verify
and create your first PR] end subgraph "Week 7+: Specialization" S4A[Choose area of focus:
- Control Plane
- Data Plane / NodePool
- Platform specific
- API Design] S4B[Read E2E tests
test/e2e/] S4C[Contribute features
and PR reviews] end S1A --> S1B --> S1C --> S1D --> S1E S1E --> S2A S2A --> S2B --> S2C --> S2D --> S2E S2E --> S3A S3A --> S3B --> S3C --> S3D --> S3E S3E --> S4A --> S4B --> S4C

Suggested Reading Order for Code

For each area, follow this order to build understanding incrementally:

Control Plane path:

  1. api/hypershift/v1beta1/hostedcluster_types.go (skim the Spec, focus on key fields)
  2. api/hypershift/v1beta1/hosted_controlplane.go (note the similarity to HC)
  3. hypershift-operator/controllers/hostedcluster/hostedcluster_controller.go (Reconcile method only)
  4. control-plane-operator/controllers/hostedcontrolplane/hostedcontrolplane_controller.go (Reconcile and registerComponents)
  5. support/controlplane-component/controlplane-component.go (core framework)
  6. control-plane-operator/controllers/hostedcontrolplane/v2/kube_scheduler/ (simple component)

Data Plane path:

  1. api/hypershift/v1beta1/nodepool_types.go
  2. hypershift-operator/controllers/nodepool/nodepool_controller.go (Reconcile entry point)
  3. hypershift-operator/controllers/nodepool/config.go (hash-based rollout)
  4. hypershift-operator/controllers/nodepool/token.go (ignition tokens)
  5. hypershift-operator/controllers/nodepool/capi.go (CAPI resource creation)
  6. ignition-server/cmd/start.go (how nodes fetch their config)

Platform path (pick one):

  1. hypershift-operator/controllers/hostedcluster/internal/platform/platform.go (interface)
  2. hypershift-operator/controllers/hostedcluster/internal/platform/<your-platform>/ (implementation)
  3. hypershift-operator/controllers/nodepool/<your-platform>.go (machine template)
  4. control-plane-operator/controllers/hostedcontrolplane/v2/cloud_controller_manager/<your-platform>/ (CCM)
  5. api/hypershift/v1beta1/<your-platform>.go (API types)

Guide Contents

Section What you'll learn
What is HyperShift? The problem HyperShift solves and how it works
Key Concepts Core resources, glossary, and terminology
Architecture Overall architecture, namespace layout, and main components
Cluster Lifecycle Creation, upgrades, deletion, and the CPO reconciliation flow
Data Plane NodePool management, node lifecycle, ClusterAPI, auto-scaling
Cloud Platforms Supported platforms, comparison, and infrastructure details
Development APIs, code structure, development workflow, and patterns
Reference Architectural invariants and key file reference