AGENT-1330: machineconfiguration/v1alpha1: add InternalReleaseImage

[andfasano]

This patch adds the new InternalReleaseImage CRD. See openshift/enhancements#1821 for additional details

[openshift-ci-robot]

@andfasano: This pull request references AGENT-1330 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "4.21.0" version, but no target version was set.

In response to this:

This patch adds the new InternalReleaseImage CRD. See openshift/enhancements#1821 for additional details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[openshift-ci]

Hello @andfasano! Some important instructions when contributing to openshift/api:
API design plays an important part in the user experience of OpenShift and as such API PRs are subject to a high level of scrutiny to ensure they follow our best practices. If you haven't already done so, please review the OpenShift API Conventions and ensure that your proposed changes are compliant. Following these conventions will help expedite the api review process for your PR.

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign joelspeed for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[andfasano]

/retest-required

[JoelSpeed]

I'm currently experimenting with AI for API review, hopefully some of the content it is generating is helpful for you to improve your API

The following code blocks were generated by Claude

⏺ I'll run a comprehensive API review for PR #2510. Let me start by setting up the environment and checking out the PR.

⏺ Bash(CURRENT_BRANCH=$(git branch --show-current); echo "📍 Current branch: $CURRENT_BRANCH"; if ! git diff --quiet || ! git diff --cached --quiet; then echo "❌ ERROR…)
  ⎿  📍 Current branch: agents                           
     ✅ No uncommitted changes detected. Safe to proceed.

⏺ Bash(echo "🔍 Reviewing PR #2510"; echo "🔄 Checking out PR #2510..."; gh pr checkout "2510")
  ⎿  🔍 Reviewing PR #2510                
     🔄 Checking out PR #2510...
     From https://github.com/openshift/api
     … +2 lines (ctrl+o to expand)

⏺ Bash(echo "📁 Analyzing changed files..."; gh pr view "2510" --json files --jq '.files[].path' | grep '\.go$' | grep -E '/(v1|v1alpha1|v1beta1)/')
  ⎿  📁 Analyzing changed files...                              
     machineconfiguration/v1alpha1/register.go
     machineconfiguration/v1alpha1/types_internalreleaseimage.go
     … +2 lines (ctrl+o to expand)

⏺ Bash(echo "⏳ Running linting checks on PR changes..."; make lint)
  ⎿  Error: make: *** [lint] Error 1

     ⏳ Running linting checks on PR changes...
     hack/golangci-lint.sh run --new-from-rev=master 
     Tools vendor version mismatch, removing old utils
     Writing tools vendor version 206d340a14a3ede2d30e25b37757397aacac6799
     go build -mod=vendor -o /Users/jspeed/go/src/github.com/openshift/api/tools/_output/bin/darwin/arm64/golangci-lint ./vendor/github.com/golangci/golangci-lint/v2/cmd/golangci-lint
     go build -mod=vendor -buildmode=plugin -o /Users/jspeed/go/src/github.com/openshift/api/tools/_output/bin/darwin/arm64/kube-api-linter.so ./vendor/sigs.k8s.io/kube-api-linter/pkg/plugin
     ln -fs /Users/jspeed/go/src/github.com/openshift/api/tools/_output/bin/darwin/arm64/kube-api-linter.so /Users/jspeed/go/src/github.com/openshift/api/tools/_output/bin/kube-api-linter.so
     machineconfiguration/v1alpha1/types_internalreleaseimage.go:35:2: requiredfields: field Spec has a valid zero value ({}), but the validation is not complete (e.g. min properties/adding required fields). The field should be a pointer to allow the zero value to be set. If the zero value is not a valid use case, complete the validation and remove the 
     pointer. (kubeapilinter)
     … +7 lines (ctrl+o to see all)

⏺ Now let me analyze the main API file for documentation requirements:

⏺ Read(machineconfiguration/v1alpha1/types_internalreleaseimage.go)
  ⎿  Read 111 lines (ctrl+o to expand)

⏺ Let me also check the PR diff to understand exactly what changed:

⏺ Bash(gh pr diff "2510")
  ⎿  diff --git a/machineconfiguration/v1alpha1/register.go b/machineconfiguration/v1alpha1/register.go
     index c60f521f940..451be959977 100644
     --- a/machineconfiguration/v1alpha1/register.go
     … +601 lines (ctrl+o to expand)

⏺ API Review Report for PR #2510

  ❌ REVIEW FAILED - Issues Found

  The API review has identified several critical issues that must be addressed before this PR can be approved.

  🚨 Linting Errors (CRITICAL)

  The make lint command failed with kubeapilinter errors:

  +35: Spec field validation issue
  Current (problematic) code:
  Spec InternalReleaseImageSpec `json:"spec,omitzero"`

  Suggested change:
  - Spec InternalReleaseImageSpec `json:"spec,omitzero"`
  + Spec *InternalReleaseImageSpec `json:"spec,omitzero"`

  Explanation: The field has a valid zero value ({}) but incomplete validation. Since it's marked as +required, it should be a pointer to allow the zero value to be set, or the validation should be completed to make the zero value invalid.

  +39: Status field validation issue
  Current (problematic) code:
  Status InternalReleaseImageStatus `json:"status"`

  Suggested change:
  - Status InternalReleaseImageStatus `json:"status"`
  + Status *InternalReleaseImageStatus `json:"status"`

  Explanation: The field has a valid zero value ({}) but incomplete validation. Since status subresources typically allow empty initial states, this should be a pointer to allow the zero value to be set.

  📚 Documentation Issues (MODERATE)

  +48: Missing optional field behavior documentation
  Current (problematic) code:
  // conditions represent the observations of an internal release image current state.
  // +listType=map
  // +listMapKey=type
  // +kubebuilder:validation:MaxItems=20
  // +optional
  Conditions []metav1.Condition `json:"conditions,omitempty"`

  Suggested change:
  - // conditions represent the observations of an internal release image current state.
  + // conditions represent the observations of an internal release image current state.
  + // When omitted, the resource has no status conditions to report.

  Explanation: Optional fields must explain what happens when they are omitted. The field comment should state the behavior when the field is not present.

  +57: Missing optional field behavior documentation
  Current (problematic) code:
  // availableReleases is a list of release bundle identifiers currently detected
  // from the attached ISO.
  // +listType=map
  // +listMapKey=name
  // +kubebuilder:validation:MinItems=1
  // +kubebuilder:validation:MaxItems=64
  // +optional
  AvailableReleases []InternalReleaseImageRef `json:"availableReleases,omitempty"`

  Suggested change:
  - // availableReleases is a list of release bundle identifiers currently detected
  - // from the attached ISO.
  + // availableReleases is a list of release bundle identifiers currently detected
  + // from the attached ISO.
  + // When omitted or empty, no release bundles have been detected from the attached ISO.

  Explanation: Optional fields must explain what happens when they are omitted. Also, the validation constraints (MinItems=1, MaxItems=64) should be documented.

  +66: Missing optional field behavior documentation
  Current (problematic) code:
  // releases is a list of the currently managed release bundles.
  // +listType=map
  // +listMapKey=name
  // +kubebuilder:validation:MinItems=1
  // +kubebuilder:validation:MaxItems=64
  // +optional
  Releases []InternalReleaseImageRef `json:"releases,omitempty"`

  Suggested change:
  - // releases is a list of the currently managed release bundles.
  + // releases is a list of the currently managed release bundles.
  + // When omitted or empty, no release bundles are currently being managed.

  Explanation: Optional fields must explain what happens when they are omitted. Also, the validation constraints (MinItems=1, MaxItems=64) should be documented.

  +78: Missing optional field behavior documentation
  Current (problematic) code:
  // releases is a list of release bundle identifiers that the user wants to
  // add/remove to/from the control plane nodes.
  // +optional
  // +kubebuilder:validation:MinItems=1
  // +kubebuilder:validation:MaxItems=20
  // +listType=map
  // +listMapKey=name
  Releases []InternalReleaseImageRef `json:"releases,omitempty"`

  Suggested change:
  - // releases is a list of release bundle identifiers that the user wants to
  - // add/remove to/from the control plane nodes.
  + // releases is a list of release bundle identifiers that the user wants to
  + // add/remove to/from the control plane nodes.
  + // When omitted or empty, no release bundle operations are requested.
  + // Must contain between 1 and 20 items when specified.

  Explanation: Optional fields must explain what happens when they are omitted. The validation constraints (MinItems=1, MaxItems=20) must also be documented in the field comment.

  +93: Missing optional field behavior documentation
  Current (problematic) code:
  // image is an OCP release imaged referenced by digest.
  // The format of the image pull spec is: host[:port][/namespace]/name@sha256:<digest>,
  // where the digest must be 64 characters long, and consist only of lowercase hexadecimal characters, a-f and 0-9.
  // The length of the whole spec must be between 1 to 447 characters.
  // +optional
  Image machineosconfig.ImageDigestFormat `json:"image,omitempty"`

  Suggested change:
  - // image is an OCP release imaged referenced by digest.
  - // The format of the image pull spec is: host[:port][/namespace]/name@sha256:<digest>,
  - // where the digest must be 64 characters long, and consist only of lowercase hexadecimal characters, a-f and 0-9.
  - // The length of the whole spec must be between 1 to 447 characters.
  + // image is an OCP release imaged referenced by digest.
  + // The format of the image pull spec is: host[:port][/namespace]/name@sha256:<digest>,
  + // where the digest must be 64 characters long, and consist only of lowercase hexadecimal characters, a-f and 0-9.
  + // The length of the whole spec must be between 1 to 447 characters.
  + // When omitted, the release bundle identifier refers to the name only without an associated image.

  Explanation: Optional fields must explain what happens when they are omitted. This field needs to clarify what happens when no image is specified for a release bundle.

  ✅ Positive Findings

  - API Structure: Well-organized with appropriate separation between spec and status
  - Feature Gate: Properly gated behind NoRegistryClusterOperations feature gate
  - Validation Rules: Comprehensive validation using kubebuilder markers and CEL expressions
  - Generated Files: All required generated files (deepcopy, CRDs, swagger docs) are present and properly updated
  - List Support: Proper list type and map key annotations for array fields
  - Compatibility: Correctly marked as compatibility level 4 for alpha API

  📋 Action Required

  1. CRITICAL: Fix the linting errors by addressing the pointer vs value type issues for Spec and Status fields
  2. REQUIRED: Add proper documentation for all optional fields explaining behavior when omitted
  3. RECOMMENDED: Document validation constraints in field comments for better developer experience

  The PR cannot be approved until the critical linting errors are resolved and all optional fields have proper behavior documentation.

I think the linting issues are actually not the response I'd like. Instead lets try and make the zero values not valid (required fields or MinProperties markers. The linter should be prompting you on these already

For the comments, it has highlighted that you haven't explained what happens when the optional fields are omitted, though I'm not sure its suggestions are super helpful, please review and think about what you'd actually like to put in. If it has identified something where you can't think of a reason why it wouldn't be present, then maybe the field should actually be required

---

Quizzing specifically about whether all validations were documented, some further output

⏺ You're absolutely right. Looking more carefully at the validation markers, I missed several undocumented validation markers:

  Additional Undocumented Validation Markers I Missed:

  +47: MaxItems validation not documented
  // +kubebuilder:validation:MaxItems=20
  The comment doesn't mention the maximum of 20 items for conditions.

  +55-56: MinItems and MaxItems validation not documented
  // +kubebuilder:validation:MinItems=1
  // +kubebuilder:validation:MaxItems=64
  The comment doesn't mention the 1-64 item range for availableReleases.

  +63-64: MinItems and MaxItems validation not documented
  // +kubebuilder:validation:MinItems=1  
  // +kubebuilder:validation:MaxItems=64
  The comment doesn't mention the 1-64 item range for releases in status.

  +84-85: MinLength and MaxLength validation not documented
  // +kubebuilder:validation:MinLength=1
  // +kubebuilder:validation:MaxLength=64
  The comment doesn't mention the 1-64 character length constraints for the name field.

  So no, my original review was incomplete. I identified the optional field behavior issues but missed documenting several validation constraints that should be included in the field comments according to OpenShift API documentation standards.

[andfasano]

/api-review

[andfasano]

/test verify

[andfasano]

/retest

[andfasano]

/retest

[yuqi-zhang]

Overall the structure makes more sense to me. A few questions/comments on the new MCN fields (and the previous question on the conditions)

[yuqi-zhang]

Just thinking out loud, maybe we should have this be required (if the IRI status exists) so at it would always reflect what the daemon is currently detecting? And if we don't detect anything we just have an empty list?

[yuqi-zhang]

The conditions looks good, some more comments inline:

And also, running claude again via #2548 to see what it suggests:

Summary

  ✅ Linting checks PASSED - No issues found with make lint

  Detailed Analysis

  I've reviewed the PR against both Kubernetes and OpenShift API conventions. The changes introduce a new v1alpha1 API
  (InternalReleaseImage) and add corresponding status fields to the existing v1 MachineConfigNode API.

  Critical Issues Found

  1. Missing Optional Field Behavior Documentation

  Line 161-166 in machineconfiguration/v1/types_machineconfignode.go:

  Current (problematic) code:
  // internalReleaseImage describes the status of the release payloads stored in the node.
  // When specified, an internalReleaseImage custom resource exists on the cluster, and the specified images will be made 
  available on the control plane nodes.
  // This field will reflect the actual on-disk state of those release images.
  // +openshift:enable:FeatureGate=NoRegistryClusterOperations
  // +optional
  InternalReleaseImage MachineConfigNodeStatusInternalReleaseImage `json:"internalReleaseImage,omitzero,omitempty"`

  Suggested change:
  - // internalReleaseImage describes the status of the release payloads stored in the node.
  - // When specified, an internalReleaseImage custom resource exists on the cluster, and the specified images will be 
  made available on the control plane nodes.
  - // This field will reflect the actual on-disk state of those release images.
  + // internalReleaseImage describes the status of the release payloads stored in the node.
  + // When specified, an internalReleaseImage custom resource exists on the cluster, and the specified images will be 
  made available on the control plane nodes.
  + // This field will reflect the actual on-disk state of those release images.
  + // When omitted, no internalReleaseImage custom resource exists on the cluster, or the NoRegistryClusterOperations 
  feature gate is disabled.

  Explanation: According to OpenShift API conventions, optional fields must explicitly document what happens when they are
   omitted. The current documentation only explains when the field is specified, but doesn't clarify the omitted behavior.

  ---
  2. Missing Validation Marker Documentation (MinItems/MaxItems)

  Line 42-52 in machineconfiguration/v1alpha1/types_internalreleaseimage.go:

  Current (problematic) code:
  // releases is a list of release bundle identifiers that the user wants to
  // add/remove to/from the control plane nodes.
  // Entries must be unique, keyed on the name field.
  // This field can contain between 1 and 5 entries.
  // +kubebuilder:validation:MinItems=1
  // +kubebuilder:validation:MaxItems=5
  // +listType=map
  // +listMapKey=name
  // +required
  Releases []InternalReleaseImageRef `json:"releases,omitempty"`

  Suggested change:
   // releases is a list of release bundle identifiers that the user wants to
   // add/remove to/from the control plane nodes.
   // Entries must be unique, keyed on the name field.
  - // This field can contain between 1 and 5 entries.
  + // This field is required and must contain between 1 and 5 entries.

  Explanation: While the documentation mentions the range constraint, it should also clarify that the field is required
  (not just via the marker). However, this is borderline acceptable as the constraint is documented. The main improvement
  is making it clearer that this is a required field in the prose.

  ---
  3. Inconsistent Required Field Marking

  Line 172-183 in machineconfiguration/v1/types_machineconfignode.go:

  Current (problematic) code:
  // MachineConfigNodeStatusInternalReleaseImage holds information about the current and discovered release bundles for 
  the observed machine
  // config node.
  type MachineConfigNodeStatusInternalReleaseImage struct {
  	// releases is a list of the release bundles currently owned and managed by the
  	// cluster, indicating that their images can be safely pulled by any cluster entity
  	// requiring them.
  	// Entries must be unique, keyed on the name field.
  	// This field can contain between 1 and 5 entries.
  	// +listType=map
  	// +listMapKey=name
  	// +kubebuilder:validation:MinItems=1
  	// +kubebuilder:validation:MaxItems=5
  	// +required
  	Releases []MachineConfigNodeStatusInternalReleaseImageRef `json:"releases,omitempty"`
  }

  Suggested change:
   // releases is a list of the release bundles currently owned and managed by the
   // cluster, indicating that their images can be safely pulled by any cluster entity
   // requiring them.
   // Entries must be unique, keyed on the name field.
  - // This field can contain between 1 and 5 entries.
  + // This field is required and must contain between 1 and 5 entries.

  Explanation: The field is marked as +required but the documentation says "can contain" which is ambiguous. It should
  explicitly state "is required and must contain" to match the validation marker.

  ---
  4. Optional Field in Status Missing Omitted Behavior

  Line 66-77 in machineconfiguration/v1alpha1/types_internalreleaseimage.go:

  Current (problematic) code:
  // releases is a list of the release bundles currently owned and managed by the
  // cluster, indicating that their images can be safely pulled by any cluster entity
  // requiring them.
  // Entries must be unique, keyed on the name field.
  // This field can contain between 1 and 5 entries.
  // +listType=map
  // +listMapKey=name
  // +kubebuilder:validation:MinItems=1
  // +kubebuilder:validation:MaxItems=5
  // +optional
  Releases []InternalReleaseImageStatusRef `json:"releases,omitempty"`

  Suggested change:
   // releases is a list of the release bundles currently owned and managed by the
   // cluster, indicating that their images can be safely pulled by any cluster entity
   // requiring them.
   // Entries must be unique, keyed on the name field.
  - // This field can contain between 1 and 5 entries.
  + // When specified, this field must contain between 1 and 5 entries.
  + // When omitted, no release bundles have been observed or managed yet.

  Explanation: This optional field doesn't explain what it means when it's omitted. According to the API review
  requirements, optional fields must document their omitted behavior.

  ---
  5. Spelling Error in Documentation

  Line 116 and Line 224 in both files:

  Current (problematic) code:
  // InternalReleaseImageConditionTypeInstalling describes a new release that is getting installed on the current node. 
  Due the size of the data
  // transfered, the operation could take several minutes

  Suggested change:
  - // InternalReleaseImageConditionTypeInstalling describes a new release that is getting installed on the current node. 
  Due the size of the data
  - // transfered, the operation could take several minutes
  + // InternalReleaseImageConditionTypeInstalling describes a new release that is getting installed on the current node. 
  Due to the size of the data
  + // transferred, the operation could take several minutes

  Explanation: Two errors: "Due the" should be "Due to the" and "transfered" should be "transferred" (two r's).

  ---
  Positive Observations

  ✅ Strong validation coverage - The API includes comprehensive CEL validation rules for the image field format
  ✅ Good documentation structure - Field purposes are generally well-documented
  ✅ Proper feature gating - Both APIs are properly gated behind the NoRegistryClusterOperations feature gate
  ✅ Consistent naming - Field names follow Kubernetes/OpenShift conventions (camelCase in JSON, PascalCase in Go)
  ✅ List type annotations - Proper use of +listType=map with +listMapKey for uniqueness constraints
  ✅ Validation markers documented - MinLength/MaxLength constraints are documented in prose

  ---
  Recommendations

  MUST FIX:
  1. Document omitted behavior for all optional fields (Issues #1 and #4)
  2. Fix spelling errors in condition type documentation (Issue #5)

  SHOULD FIX:
  3. Clarify required field documentation to explicitly state "required" in prose (Issues #2 and #3)

  ---
  Conclusion

  The PR demonstrates good API design practices but has critical documentation gaps around optional field behavior that
  must be addressed before merging. These gaps violate the OpenShift API convention requirement that optional fields must
  explain what happens when omitted.

  Once the optional field documentation is updated, this API will be compliant with both Kubernetes and OpenShift API
  conventions.

Also ran the same review command from the master branch, it had the same suggestions, but a couple more things:

API Review Report for PR #2510

 ...

  Issue 7: Duplicate InternalReleaseImageConditionType in wrong package

  Line 217: The InternalReleaseImageConditionType enum is defined in the v1 package but the comment references
  MachineConfigNodeStatusInternalReleaseImageRef, suggesting this might be used across both v1 and v1alpha1.

  Current (problematic) code:
  // InternalReleaseImageConditionType is each possible state for each possible 
  MachineConfigNodeStatusInternalReleaseImageRef
  // conditions type.
  // +enum
  type InternalReleaseImageConditionType string

  Status: ⚠️ DESIGN CONCERN - This same enum type is defined in both machineconfiguration/v1/types_machineconfignode.go
  and machineconfiguration/v1alpha1/types_internalreleaseimage.go. While not strictly a documentation issue, this creates
  type duplication between API versions. Consider if one should reference the other or if they should be in a shared
  package.

  ---

● 📊 SUMMARY

  Critical Issues (Must Fix): 2

  1. machineconfiguration/v1alpha1/types_internalreleaseimage.go:47 - Releases field: Missing clear statement that field
  is required (should say "must contain" not "can contain")
  2. machineconfiguration/v1alpha1/types_internalreleaseimage.go:87 - Conditions field: Missing omitted behavior
  documentation and MinItems/MaxItems documentation

  Medium Issues (Should Fix): 2

  3. machineconfiguration/v1/types_machineconfignode.go:166 - InternalReleaseImage field: Missing omitted behavior
  documentation
  4. machineconfiguration/v1/types_machineconfignode.go:182 - Releases field: Inconsistent wording ("can contain" vs "must
   contain")

  Design Concerns: 1

  5. Type Duplication: InternalReleaseImageConditionType is defined identically in both v1 and v1alpha1 packages

  ---
  ✅ What's Done Well

  1. Comprehensive validation rules: The XValidation rules for image references are well-designed and thoroughly enforce
  the OCI image format
  2. Length constraints documented: MinLength and MaxLength constraints are clearly documented for most fields
  3. Field purpose clear: Most fields have clear descriptions of their purpose and use
  4. Feature gate usage: Proper use of feature gates for tech preview functionality

  ---
  🔧 Recommended Actions

  Before Merge:

  1. Fix the two critical documentation issues for optional fields and required fields
  2. Address the medium issues for consistency
  3. Consider refactoring the duplicated InternalReleaseImageConditionType to a shared location

  Post-Review:

  - Run make update-codegen-crds 
  API_GROUP_VERSIONS=machineconfiguration.openshift.io/v1,machineconfiguration.openshift.io/v1alpha1 after making
  documentation changes
  - Re-run make lint to ensure no new issues are introduced

  ---

So it somewhat caught that the crd isn't being deployed, also comment on that inline

[andfasano]

/retest

[openshift-ci]

@andfasano: all tests passed!

Full PR test history. Your PR dashboard.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

[yuqi-zhang]

Thanks for the updates, going to mark this shadow review completed, barring some minor nits and typos below

[yuqi-zhang]

(minor): since we are making it a singleton cluster object, I wonder if we still need to define this list object

[yuqi-zhang]

nit: typo transfered -> transferred

[yuqi-zhang]

nit: typo transfered -> transferred

[yuqi-zhang]

I think this should also have omitempty per https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#serialization-of-optionalrequired-fields ? Although I'm not 100% sure on this