HyperShift API Module

This module (github.com/openshift/hypershift/api) is consumed by external Go clients that vendor it directly. Changes to types in this module affect not only the HyperShift operator but also downstream consumers that embed, serialize, and deserialize these types independently of the Kubernetes API server.

CRD API Machinery Fundamentals

These are non-obvious behaviors of the Kubernetes API machinery that affect how CRD types in api/ must be written. These are not style preferences or conventions — they are fundamental facts and reasoning about how the system works.

For conventions, always trust the kube-api-linter (make api-lint-fix). Do not question its findings and do not add exclusions unless explicitly told to by a human reviewer. The linter encodes the OpenShift API conventions (authoritative) and upstream Kubernetes API conventions (informational, downstream wins on conflicts). Do not fetch or read those documents — the linter already enforces them, and the actionable rules are captured in this file.

API Versioning

• APIs primarily in v1beta1
• Any new API should GA as v1
• Use feature gates for experimental functionality
• CRD generation via controller-gen with OpenShift-specific tooling

Serialization

• Always set omitempty or omitzero on every field, regardless of whether it is +required or +optional. omitempty/omitzero tags control serialization, not validation. +required is a schema constraint enforced at admission time; the serialization tag controls what goes on the wire. Without a tag, a zero-value field serializes as an explicit value (e.g., "pullSecret": {"name": ""}), which makes the API server unable to distinguish "not set" from "explicitly set to empty." This breaks defaulting, server-side apply field ownership, and strategic merge patch — all of which rely on field absence to mean "don't touch this." Additionally, without omission a structured client serializes the empty object, which passes the +required check (based on key presence) without validating the value — so a user can forget to set a required field, it passes admission, and the reader sees a required field with an unexpected empty value.
• omitempty does nothing for non-pointer structs. Only omitzero correctly omits a struct field when it equals its zero value. This is a Go encoding/json behavior, not a Kubernetes convention. Use omitempty for scalar fields (string, int, bool) and slices/maps. Use omitzero for struct fields (available since Go 1.24; this repo requires Go 1.25+).
• The only reason to use a pointer in a CRD is when the zero value is a valid, distinct user choice. If the struct has a required field, {} can never be valid user input, so there is no ambiguity to resolve and no pointer is needed. omitzero on a non-pointer struct will correctly omit the key from serialized output. MinProperties/MaxProperties on the parent counts serialized keys — it has no concept of whether the Go field is a pointer.
• // +default must be paired with // +optional because the required check runs before defaulting. A required field with a default will be rejected before the default is ever applied.

Validation Execution

• OpenAPI schema validation only runs when a key is present in the serialized object. if a field is omitted, the validation never executes. This is why MinLength=1 on an optional field is safe: the constraint only fires when the user actually provides a value.
• Optionality and min constraints are independent concerns. An optional field with MinLength=1 means "you don't have to set this, but if you do, it can't be empty." These do not conflict.
• Admission-time validation rejects the write immediately. Controller-time validation accepts the write, the user assumes success, and discovers the problem later via conditions or logs. Always prefer admission-time via CEL over controller-time validation.
• Use CEL rules, not webhooks, for new validation. HyperShift deliberately avoids admission webhooks because they add latency (especially in hosted-on-hosted topologies like IBM Cloud where requests traverse konnectivity), require TLS cert management, and couple resource availability to a running webhook service. The existing webhook is scoped to KubeVirt platform defaults and is not a general extension point. Add new validation as CEL markers on the API types in this module.

Immutability

• Immutable + optional creates a two-step bypass. A user can (1) remove the optional field, then (2) re-add it with a different value. To prevent this, add a CEL rule at the parent level that forbids removing the field once set: oldSelf.has(field) ? self.has(field) : true.
• "Once set, cannot be removed" and "once set, cannot be changed" are separate constraints. You typically need both together, and they require separate CEL rules.

Defaulting and Transitions

• Ratcheting validation: when adding new validation to existing fields, verify that existing clusters with values that predate the new validation can still be updated. CRD validation ratchets (allows unchanged invalid values through), but only for fields that are literally unchanged in the update.

KubeletConfiguration Field Graduation (Karpenter)

The KubeletConfiguration type in api/karpenter/v1/kubelet_config.go accepts arbitrary kubelet configuration fields via a PreserveUnknownFields schema and a runtime.RawExtension overflow mechanism. A subset of these fields are promoted to explicitly typed struct fields with CEL validation.

When graduating a field from overflow to a typed struct field:

• Match upstream kubelet's field name and JSON tag exactly. The primary compatibility target is k8s.io/kubelet/config/v1beta1.KubeletConfiguration. Users today set kubelet fields that land in our overflow using kubelet field names. Changing a name would be a breaking API change requiring a new API version, because existing serialized data (and user-supplied YAML) uses the kubelet name.
• Use upstream Karpenter as a secondary reference. Upstream Karpenter (github.com/aws/karpenter-provider-aws/pkg/apis/v1.KubeletConfiguration) currently mirrors kubelet field names. If Karpenter ever diverges from kubelet naming, follow kubelet and add a translation layer in karpenterKubeletConfigurationFromNodeClassSpec().
• Match the Go type from upstream kubelet/Karpenter. Use the same Go type (pointer vs value, map key/value types) to keep the mapping trivial and avoid serialization incompatibilities. Minor differences (e.g., bare int32 vs *int32) are acceptable only when they don't change the JSON representation.
• Add stricter CEL validation as needed. Admission-time validation does not affect serialization compatibility. We can add constraints beyond what upstream provides (e.g., Minimum=1 instead of Minimum=0, cross-field rules like imageGCHigh > imageGCLow) without breaking the API.
• Do not rename fields for OpenShift conventions. Normally OpenShift API conventions may prefer different naming. For KubeletConfiguration fields, upstream kubelet compatibility takes precedence over convention to avoid breaking changes.

API Type Change Guidelines

Best Practices and Patterns

Use api/karpenter/v1/karpenter_types.go and api/hypershift/v1beta1/etcdbackup_types.go as examples of best practices and patterns.

Don't use the other existing APIs as examples as they might have many legacy constraints.

Field Grouping

When multiple fields on a spec share a common prefix or relate to the same feature, they MUST be grouped into a dedicated struct. Top-level specs like HostedClusterSpec and NodePoolSpec should only contain fields that are independently meaningful. If removing one field would make another field meaningless, they belong together in a sub-struct. A common signal is fields that share a name prefix (e.g., BarEndpoint, BarConfig, BarID all relate to "Bar" and should be a single Bar field with a BarSpec struct).

N-1 and N+1 Compatibility

Every change to an API type must be safe for both:

• N+1 (forward): New code reading data written by old code
• N-1 (rollback): Old code reading data written by new code

This matters because consumers like ARO-HCP embed these types directly into their own structs and serialize them to storage (e.g., Cosmos DB) outside CRD validation. If a consumer must revert to a previous code level, they need to deserialize data that was written by the newer version without errors or data corruption.

Common Pitfalls

• Changing a value type to a pointer (e.g., int32 to *int32): Without omitempty, a nil pointer serializes as null, which cannot be deserialized back into the non-pointer type. Always pair pointer types with omitempty on required fields.
• Removing or renaming a field: Old code will fail to deserialize the new format if it expects the field.
• Changing a field's type: Ensure the JSON representation is compatible in both directions.

Required Tests

When modifying API types, add serialization compatibility tests that:

1. Define a struct matching the previous version of the type
2. Serialize the current type and verify the previous version can deserialize it
3. Serialize the previous type and verify the current version can deserialize it
4. Cover edge cases: zero values, nil pointers, omitted fields

See api/hypershift/v1beta1/nodepool_types_test.go for an example of this pattern.

All API CEL validations must be covered with envtests, see test/envtest/README.md for details

Key make targets for API work

make api               # Regenerate all CRDs, deepcopy, clients
make api-lint-fix      # Run API linter and auto-fix violations
make verify            # Full verification (includes api, fmt, vet, lint)
make update            # Full update (api-deps, workspace-sync, deps, api, api-docs, clients)
make test-envtest-ocp  # Run envtest for CEL validations
# To target a specific k8s version, check api/go.mod (e.g. k8s.io/api v0.35.1 → 1.35):
# ENVTEST_OCP_K8S_VERSIONS=1.35.0 make test-envtest-ocp

All these must pass for any change before creating a PR

Cluster Capabilities

The OptionalCapability type and Capabilities struct in api/hypershift/v1beta1/hostedcluster_types.go control which OpenShift operators are deployed in the hosted control plane. When adding a new capability constant or modifying CEL validation rules on the Capabilities struct, see Adding a New Cluster Capability for the full implementation checklist and reference PRs.