# 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](https://github.com/openshift/enhancements/blob/master/dev-guide/api-conventions.md) (authoritative) and [upstream Kubernetes API conventions](https://github.com/kubernetes/community/blob/main/contributors/devel/sig-architecture/api-conventions.md) (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

```bash
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](../docs/content/contribute/add-a-capability.md) for the full implementation checklist and reference PRs.
