This file provides guidance to AI coding agents when working with code in this repository. CLAUDE.md is a symlink to this file so that Claude Code auto-loads it; the AGENTS.md name is canonical.
HyperShift is middleware for hosting OpenShift control planes at scale, decoupling control planes (running as pods on a management cluster) from worker nodes (running in separate infrastructure).
This file is intentionally minimal — detailed guidance lives in the referenced files below and should be updated there, not here.
For architecture, components, and platform support, see ARCHITECTURE.md.
Project documentation is published via MkDocs. The site structure and navigation are defined in docs/mkdocs.yml, with content under docs/content/. When adding or reorganizing documentation pages, update the nav section in mkdocs.yml to keep the site navigation in sync.
| Topic | Where to look |
|---|---|
| Development commands and patterns | DEVELOPMENT.md |
| API types and CRD machinery | api/AGENTS.md |
| Control plane components (CPOv2) | support/controlplane-component/AGENTS.md and support/controlplane-component/README.md |
| Control plane operator | control-plane-operator/AGENTS.md |
| HC/HCP status patching | control-plane-operator/AGENTS.md — never Status().Update()/unguarded MergeFrom() on HC/HCP; actively enforced by hcpstatuspatch; use support/statuspatching |
| E2E v2 test framework | test/e2e/v2/AGENTS.md |
| Envtest (CEL validation tests) | test/envtest/README.md — YAML-driven, runs across k8s 1.31–1.37, supports feature gate filtering |
| CEL over webhooks | .claude/rules/webhook-validation.md |
| Code formatting | DEVELOPMENT.md — code quality commands and conventions |
| Unit test conventions | TESTING.md — naming, placement, and creation requirements |
| Design invariants | docs/content/reference/goals-and-design-invariants.md |
| Versioning and support | docs/content/reference/versioning-support.md |
| Upgrades lifecycle | docs/content/how-to/upgrades.md |
| Contributing and PR workflow | CONTRIBUTING.md |
| Agentic SDLC framework | docs/content/how-to/agentic-sdlc.md |
| Feature gates | docs/content/how-to/feature-gates.md — two separate systems: management cluster gates vs hosted cluster gates |
| Pre-commit hooks | docs/content/contribute/precommit-hook-help.md |
When changing how workers and the hosted cluster authenticate to registries, treat HostedCluster spec.pullSecret, management-cluster Secret data, HCCO reconciliation into the data plane, and optional Global Pull Secret (kube-system/additional-pull-secret) as one system. Changing only the Secret bytes in place does not change spec.pullSecret and therefore does not drive a NodePool rollout, but controllers can still propagate credentials into the control plane namespace, guest openshift-config, kube-system/original-pull-secret, and (where the Global Pull Secret DaemonSet is scheduled) kubelet configuration.
See docs/content/how-to/common/global-pull-secret.md for behavior, platform and NodePool eligibility (AWS/Azure Replace vs InPlace and other platforms), merge semantics, and operational guidance.
Changes to config data, secrets, or any value that feeds into a NodePool config hash will trigger a rollout across all HostedClusters. Before adding new data to ignition configs, MachineConfigs, or any resource reconciled into the data plane, check whether the change affects the NodePool config hash (search for hashStruct / configHash). If it does, the PR must pass e2e-aws-upgrade-hypershift-operator to prove the rollout is safe.
Additionally, consider the deployment-time migration impact on existing NodePools: if the hash was previously computed with different inputs (e.g., an image resolved from a different source), deploying the change will cause a one-time hash change and rollout across all affected NodePools — even when HC and NodePool are at the same version. Reviewers must ask: "what happens to clusters that already exist when this operator version is deployed?"