|
| 1 | +This file provides guidance to AI agents when working with code in this repository. |
| 2 | + |
| 3 | +This is the OpenShift API repository - the canonical location of OpenShift API type definitions and serialization code. It contains: |
| 4 | + |
| 5 | +- API type definitions for OpenShift-specific resources (Custom Resource Definitions) |
| 6 | +- FeatureGate management system for controlling API availability across cluster profiles |
| 7 | +- Generated CRD manifests and validation schemas |
| 8 | +- Integration test suite for API validation |
| 9 | + |
| 10 | +## Key Architecture Components |
| 11 | + |
| 12 | +### FeatureGate System |
| 13 | +The FeatureGate system (`features/features.go`) controls API availability across different cluster profiles (Hypershift, SelfManaged) and feature sets (Default, TechPreview, DevPreview). Each API feature is gated behind a FeatureGate that can be enabled/disabled per cluster profile and feature set. |
| 14 | + |
| 15 | +### API Structure |
| 16 | +APIs are organized by group and version (e.g., `route/v1`, `config/v1`). Each API group contains: |
| 17 | +- `types.go` - Go type definitions |
| 18 | +- `zz_generated.*` files - Generated code (deepcopy, CRDs, etc.) |
| 19 | +- `tests/` directories - Integration test definitions |
| 20 | +- CRD manifest files |
| 21 | + |
| 22 | +## Common Development Commands |
| 23 | + |
| 24 | +### Building |
| 25 | +```bash |
| 26 | +make build # Build render and write-available-featuresets binaries |
| 27 | +make clean # Clean build artifacts |
| 28 | +``` |
| 29 | + |
| 30 | +### Code Generation |
| 31 | +```bash |
| 32 | +make update # Alias for update-codegen-crds |
| 33 | +``` |
| 34 | + |
| 35 | +### Testing |
| 36 | +```bash |
| 37 | +make test-unit # Run unit tests |
| 38 | +make integration # Run integration tests (in tests/ directory) |
| 39 | +go test -v ./... # Run tests for specific packages |
| 40 | +``` |
| 41 | + |
| 42 | +### Validation and Verification |
| 43 | +```bash |
| 44 | +make verify # Run all verification checks |
| 45 | +make verify-scripts # Verify generated code is up to date |
| 46 | +make verify-codegen-crds # Verify CRD generation is current |
| 47 | +make lint # Run golangci-lint (only on changes from master) |
| 48 | +make lint-fix # Auto-fix linting issues where possible |
| 49 | +``` |
| 50 | + |
| 51 | +## Adding New APIs |
| 52 | + |
| 53 | +All APIs should start as tech preview. |
| 54 | +New fields on stable APIs should be introduced behind a feature gate `+openshift:enable:FeatureGate=MyFeatureGate`. |
| 55 | + |
| 56 | + |
| 57 | +### For New Stable APIs (v1) |
| 58 | +1. Create the API type with proper kubebuilder annotations |
| 59 | +2. Include required markers like `+openshift:compatibility-gen:level=1` |
| 60 | +3. Add validation tests in `<group>/<version>/tests/<crd-name>/` |
| 61 | +4. Run `make update-codegen-crds` to generate CRDs |
| 62 | + |
| 63 | +### For New TechPreview APIs (v1alpha1) |
| 64 | +1. First add a FeatureGate in `features/features.go` |
| 65 | +2. Create the API type with `+openshift:enable:FeatureGate=MyFeatureGate` |
| 66 | +3. Add corresponding test files |
| 67 | +4. Run generation commands |
| 68 | + |
| 69 | +### Adding FeatureGates |
| 70 | +Add to `features/features.go` using the builder pattern: |
| 71 | +```go |
| 72 | +FeatureGateMyFeatureName = newFeatureGate("MyFeatureName"). |
| 73 | + reportProblemsToJiraComponent("my-jira-component"). |
| 74 | + contactPerson("my-team-lead"). |
| 75 | + productScope(ocpSpecific). |
| 76 | + enableIn(configv1.TechPreviewNoUpgrade). |
| 77 | + mustRegister() |
| 78 | +``` |
| 79 | + |
| 80 | +## Testing Framework |
| 81 | + |
| 82 | +The repository includes a comprehensive integration test suite in `tests/`. Test suites are defined in `*.testsuite.yaml` files alongside API definitions and support: |
| 83 | +- `onCreate` tests for validation during resource creation |
| 84 | +- `onUpdate` tests for update-specific validations and immutability |
| 85 | +- Status subresource testing |
| 86 | +- Validation ratcheting tests using `initialCRDPatches` |
| 87 | + |
| 88 | +Use `tests/hack/gen-minimal-test.sh $FOLDER $VERSION` to generate test suite templates. |
| 89 | + |
| 90 | +## Container-based Development |
| 91 | +```bash |
| 92 | +make verify-with-container # Run verification in container |
| 93 | +make generate-with-container # Run code generation in container |
| 94 | +``` |
| 95 | + |
| 96 | +Uses `podman` by default, set `RUNTIME=docker` or `USE_DOCKER=1` to use Docker instead. |
| 97 | + |
| 98 | +## Custom Claude Code Commands |
| 99 | + |
| 100 | +### API Review |
| 101 | +``` |
| 102 | +/api-review <pr-url> |
| 103 | +``` |
| 104 | +Runs comprehensive API review for OpenShift API changes in a GitHub PR: |
| 105 | +- Executes `make lint` to check for kube-api-linter issues |
| 106 | +- Validates that all API fields are properly documented |
| 107 | +- Ensures optional fields explain behavior when not present |
| 108 | +- Confirms validation rules and kubebuilder markers are documented in field comments |
| 109 | + |
| 110 | +#### Documentation Requirements |
| 111 | +All kubebuilder validation markers must be documented in the field's comment. For example: |
| 112 | + |
| 113 | +**Good:** |
| 114 | +```go |
| 115 | +// internalDNSRecords is an optional field that determines whether we deploy |
| 116 | +// with internal records enabled for api, api-int, and ingress. |
| 117 | +// Valid values are "Enabled" and "Disabled". |
| 118 | +// When set to Enabled, in cluster DNS resolution will be enabled for the api, api-int, and ingress endpoints. |
| 119 | +// When set to Disabled, in cluster DNS resolution will be disabled and an external DNS solution must be provided for these endpoints. |
| 120 | +// +optional |
| 121 | +// +kubebuilder:validation:Enum=Enabled;Disabled |
| 122 | +InternalDNSRecords InternalDNSRecordsType `json:"internalDNSRecords"` |
| 123 | +``` |
| 124 | + |
| 125 | +**Bad:** |
| 126 | +```go |
| 127 | +// internalDNSRecords determines whether we deploy with internal records enabled for |
| 128 | +// api, api-int, and ingress. |
| 129 | +// +optional // ❌ Optional nature not documented in comment |
| 130 | +// +kubebuilder:validation:Enum=Enabled;Disabled // ❌ Valid values not documented |
| 131 | +InternalDNSRecords InternalDNSRecordsType `json:"internalDNSRecords"` |
| 132 | +``` |
| 133 | + |
| 134 | +The comment must explicitly state: |
| 135 | +- When a field is optional (for `+kubebuilder:validation:Optional` or `+optional`) |
| 136 | +- Valid enum values (for `+kubebuilder:validation:Enum`) |
| 137 | +- Validation constraints (for min/max, patterns, etc.) |
| 138 | +- Default behavior when field is omitted |
| 139 | +- Any interactions with other fields, commonly implemented with `+kubebuilder:validation:XValidation` |
| 140 | + |
| 141 | +**CRITICAL**: When API documentation states field relationships or constraints (e.g., "cannot be used together with field X", "mutually exclusive with field Y"), these relationships MUST be enforced with appropriate validation rules. Use `+kubebuilder:validation:XValidation` with CEL expressions for cross-field constraints. Documentation without enforcement is insufficient and will fail review. |
| 142 | + |
| 143 | +Example: `/api-review https://github.com/openshift/api/pull/1234` |
0 commit comments