hypershift
AGENTS.md551 starsChanged 6 months agoApache-2.0View on GitHub
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.…
In this repository26 other files it gives its agents.
- api/AGENTS.mdAGENTS.md
- control-plane-operator/AGENTS.mdAGENTS.md
- .cursor/rules/100-go-mistakes.mdcCursor rule
- .cursor/rules/code-formatting.mdcCursor rule
- .cursor/rules/code-review.mdcCursor rule
- .cursor/rules/create-jira-items.mdcCursor rule
- .cursor/rules/debug-aro-hcp-e2e.mdcCursor rule
- .cursor/rules/git-commit-format.mdcCursor rule
- .cursor/rules/restructure-commits.mdcCursor rule
- create-cpo-overrideSkill
- Debug ClusterSkill
- e2e-analyzeSkill
- Effective GoSkill
- feature-developmentSkill
- fix-hypershift-repo-robot-prSkill
- Git Commit FormatSkill
- konflux-buildSkill
- Konflux Archived PipelineRunsSkill
- pr-reportSkill
- restructure-commitsSkill
- test-tag-pipelineSkill
- triage-leaked-infraSkill
- update-konflux-tasksSkill
- validate-pr-override-imagesSkill
- Git Commit FormatSkill
- restructure-commitsSkill
The file
Files
AGENTS.md
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.
Key References
| 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 authoring | Writing V2 Tests |
| 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 |
| Restructuring commits | skills/restructure-commits/SKILL.md — component-based commit layout; verify with make verify-commit-layout |
| 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 |
Pull Secret Cycling
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.
Fleet-Wide Rollout Impact
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?"
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.