NO-JIRA: remove TODO comments from generated API documentation

[tuxerrante]

Summary

• Developer TODO comments in API type godoc blocks (e.g. TODO(alberto):, TODO(dan):, TODO(csrwng):) were being rendered in the public API reference documentation at hypershift.pages.dev
• Moved 20 TODO comments out of godoc blocks by placing them above with a blank line separator, so gen-crd-api-reference-docs no longer picks them up while the comments are preserved in source for developer reference
• Affected files: hostedcluster_types.go (13), azure.go (5), aws.go (1), nodepool_types.go (1), hosted_controlplane.go (1)
• Regenerated CRDs, API docs, vendor, and clients via make update

Approach

Rather than deleting the TODO comments, each one is moved above the godoc block with a blank line separator. In Go's AST, a blank line breaks the comment group association — gen-crd-api-reference-docs only renders comments that are part of a field/type's Doc group. This pattern is already used in the codebase (e.g., hostedcluster_types.go:502).

Test plan

• make update — regeneration pipeline passes
• make lint-fix — 0 lint issues
• make test — all unit tests pass
• grep -c 'TODO' docs/content/reference/api.md — returns 0 (was 30+ before)
• make run-gitlint — commit message validates
• make verify-docs-nav — pre-existing failure unrelated to this change

🤖 Generated with Claude Code

Summary by CodeRabbit

• Chores
  • Reorganized and repositioned TODO/documentation comments across AWS, Azure, HostedControlPlane, HostedCluster, and NodePool API specs so notes sit adjacent to their related fields; added a few targeted TODOs for future improvements and signaling. All edits are comment-only; no public APIs, validation rules, struct fields, or runtime behavior were changed.

[openshift-merge-bot]

Pipeline controller notification
This repo is configured to use the pipeline controller. Second-stage tests will be triggered either automatically or after lgtm label is added, depending on the repository configuration. The pipeline controller will automatically detect which contexts are required and will utilize /test Prow commands to trigger the second stage.

For optional jobs, comment /test ? to see a list of all defined jobs. To trigger manually all jobs from second stage use /pipeline required command.

This repository is configured in: LGTM mode

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited)

Review profile: CHILL

Plan: Enterprise

Run ID: 13c645a8-e043-4320-acf5-3bf020860525

📥 Commits

Reviewing files that changed from the base of the PR and between 2fb07b0 and 18b5f9c.

⛔ Files ignored due to path filters (13)

• api/hypershift/v1beta1/zz_generated.featuregated-crd-manifests/nodepools.hypershift.openshift.io/AAA_ungated.yaml is excluded by !**/zz_generated.featuregated-crd-manifests/**
• api/hypershift/v1beta1/zz_generated.featuregated-crd-manifests/nodepools.hypershift.openshift.io/GCPPlatform.yaml is excluded by !**/zz_generated.featuregated-crd-manifests/**
• api/hypershift/v1beta1/zz_generated.featuregated-crd-manifests/nodepools.hypershift.openshift.io/OpenStack.yaml is excluded by !**/zz_generated.featuregated-crd-manifests/**
• cmd/install/assets/crds/hypershift-operator/zz_generated.crd-manifests/nodepools-CustomNoUpgrade.crd.yaml is excluded by !**/zz_generated.crd-manifests/**, !cmd/install/assets/**/*.yaml
• cmd/install/assets/crds/hypershift-operator/zz_generated.crd-manifests/nodepools-Default.crd.yaml is excluded by !**/zz_generated.crd-manifests/**, !cmd/install/assets/**/*.yaml
• cmd/install/assets/crds/hypershift-operator/zz_generated.crd-manifests/nodepools-TechPreviewNoUpgrade.crd.yaml is excluded by !**/zz_generated.crd-manifests/**, !cmd/install/assets/**/*.yaml
• docs/content/reference/aggregated-docs.md is excluded by !docs/content/reference/aggregated-docs.md
• docs/content/reference/api.md is excluded by !docs/content/reference/api.md
• vendor/github.com/openshift/hypershift/api/hypershift/v1beta1/aws.go is excluded by !vendor/**, !**/vendor/**
• vendor/github.com/openshift/hypershift/api/hypershift/v1beta1/azure.go is excluded by !vendor/**, !**/vendor/**
• vendor/github.com/openshift/hypershift/api/hypershift/v1beta1/hosted_controlplane.go is excluded by !vendor/**, !**/vendor/**
• vendor/github.com/openshift/hypershift/api/hypershift/v1beta1/hostedcluster_types.go is excluded by !vendor/**, !**/vendor/**
• vendor/github.com/openshift/hypershift/api/hypershift/v1beta1/nodepool_types.go is excluded by !vendor/**, !**/vendor/**

📒 Files selected for processing (5)

• api/hypershift/v1beta1/aws.go
• api/hypershift/v1beta1/azure.go
• api/hypershift/v1beta1/hosted_controlplane.go
• api/hypershift/v1beta1/hostedcluster_types.go
• api/hypershift/v1beta1/nodepool_types.go

✅ Files skipped from review due to trivial changes (5)

• api/hypershift/v1beta1/hosted_controlplane.go
• api/hypershift/v1beta1/nodepool_types.go
• api/hypershift/v1beta1/aws.go
• api/hypershift/v1beta1/azure.go
• api/hypershift/v1beta1/hostedcluster_types.go

---

📝 Walkthrough

Walkthrough

This pull request repositions TODO and field documentation comments within multiple API struct definitions in the HyperShift v1beta1 package: api/hypershift/v1beta1/aws.go, azure.go, hosted_controlplane.go, hostedcluster_types.go, and nodepool_types.go. Comments were moved to sit adjacent to the fields they reference (e.g., Region, imageID, encryptionSetID, Tolerations/labels, Services, arch, etc.). No struct fields, types, JSON/kubebuilder tags, validation markers, or exported API signatures were changed.

Sequence Diagram(s)

(Skipped — the changes are comment/documentation repositioning and do not introduce new control flow or multi-component interactions.)

Suggested reviewers

• enxebre

🚥 Pre-merge checks | ✅ 12

✅ Passed checks (12 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main objective—removing TODO comments from generated API documentation by relocating them outside godoc blocks.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Stable And Deterministic Test Names	✅ Passed	This repository does not use Ginkgo testing framework. The PR only modifies API definition comments, not test files. The check is not applicable to this PR.
Test Structure And Quality	✅ Passed	PR modifies only API spec files to reposition TODO comments. No Ginkgo test code was changed, making this check not applicable.
Microshift Test Compatibility	✅ Passed	No new Ginkgo e2e tests are added in this PR. The changes only reposition TODO comments in API type definition files without adding any test code.
Single Node Openshift (Sno) Test Compatibility	✅ Passed	PR adds no new Ginkgo e2e tests; it only repositions TODO comments in API type definition files to prevent their rendering in generated documentation.
Topology-Aware Scheduling Compatibility	✅ Passed	PR only modifies comments in API type definition files, not deployment code. No scheduling constraints, affinity rules, or controller logic are added.
Ote Binary Stdout Contract	✅ Passed	PR contains only comment repositioning in API type definition files with no stdout-writing code added to process-level functions or initialization logic.
Ipv6 And Disconnected Network Test Compatibility	✅ Passed	PR contains no Ginkgo e2e tests—only API type definition files with repositioned TODO comments. Custom check for e2e test IPv6/disconnected compatibility is not applicable.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 40.41%. Comparing base (6d994e4) to head (18b5f9c).
⚠️ Report is 564 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #8363   +/-   ##
=======================================
  Coverage   40.41%   40.41%           
=======================================
  Files         755      755           
  Lines       93235    93235           
=======================================
  Hits        37679    37679           
  Misses      52854    52854           
  Partials     2702     2702           

Flag	Coverage Δ
cmd-support	34.44% <ø> (ø)
cpo-hostedcontrolplane	41.76% <ø> (ø)
cpo-other	40.31% <ø> (ø)
hypershift-operator	50.72% <ø> (ø)
other	31.58% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[enxebre]

thanks! lgtm other than #8363 (comment)

[tuxerrante]

/pipeline required

[openshift-merge-bot]

Scheduling tests matching the pipeline_run_if_changed or not excluded by pipeline_skip_if_only_changed parameters:
/test e2e-aks
/test e2e-aws
/test e2e-aws-upgrade-hypershift-operator
/test e2e-azure-self-managed
/test e2e-kubevirt-aws-ovn-reduced
/test e2e-v2-aws

[cwbotbot]

Test Results

e2e-aws

• Status: ✅ PASS
• Started: 2026-04-30T12:24:45Z
• View Job
• View Job History

e2e-aks

• Status: ✅ PASS
• Started: 2026-04-30T12:24:46Z
• View Job
• View Job History

[tuxerrante]

@enxebre could you pls restart failed jobs? They seems unrelated to PR changes

[tuxerrante]

/retest

[jparrill]

Do you mind:

• Please squash to a single commit?
• Use conventional commits as we describe in the Contributors guide
• Execute make docs-aggregate amending the auto generated doc? (this will fix the verify test)

[jparrill]

/retitle NO-JIRA: remove TODO comments from generated API documentation

[openshift-ci-robot]

@tuxerrante: This pull request explicitly references no jira issue.

Details

In response to this:

Summary

• Developer TODO comments in API type godoc blocks (e.g. TODO(alberto):, TODO(dan):, TODO(csrwng):) were being rendered in the public API reference documentation at hypershift.pages.dev
• Moved 20 TODO comments out of godoc blocks by placing them above with a blank line separator, so gen-crd-api-reference-docs no longer picks them up while the comments are preserved in source for developer reference
• Affected files: hostedcluster_types.go (13), azure.go (5), aws.go (1), nodepool_types.go (1), hosted_controlplane.go (1)
• Regenerated CRDs, API docs, vendor, and clients via make update

Approach

Rather than deleting the TODO comments, each one is moved above the godoc block with a blank line separator. In Go's AST, a blank line breaks the comment group association — gen-crd-api-reference-docs only renders comments that are part of a field/type's Doc group. This pattern is already used in the codebase (e.g., hostedcluster_types.go:502).

Test plan

• make update — regeneration pipeline passes
• make lint-fix — 0 lint issues
• make test — all unit tests pass
• grep -c 'TODO' docs/content/reference/api.md — returns 0 (was 30+ before)
• make run-gitlint — commit message validates
• make verify-docs-nav — pre-existing failure unrelated to this change

🤖 Generated with Claude Code

Summary by CodeRabbit

• Chores
• Reorganized and repositioned TODO/documentation comments across AWS, Azure, HostedControlPlane, HostedCluster, and NodePool API specs to sit adjacent to related fields; added a few targeted TODOs for future enhancements and signaling. All changes are documentation-only and do not modify public APIs, validation, or runtime behavior.

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.

[JoelSpeed]

/approve
/lgtm

[openshift-merge-bot]

Scheduling tests matching the pipeline_run_if_changed or not excluded by pipeline_skip_if_only_changed parameters:
/test e2e-aks
/test e2e-aws
/test e2e-aws-upgrade-hypershift-operator
/test e2e-azure-self-managed
/test e2e-azure-v2-self-managed
/test e2e-kubevirt-aws-ovn-reduced
/test e2e-v2-aws
/test e2e-v2-gke

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: bryan-cox, JoelSpeed, tuxerrante

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

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [bryan-cox]
• api/OWNERS [JoelSpeed]

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

[openshift-ci]

Stale PRs are closed after 21d of inactivity.

If this PR is still relevant, comment to refresh it or remove the stale label.
Mark the PR as fresh by commenting /remove-lifecycle stale.

If this PR is safe to close now please do so with /close.

/lifecycle stale

[JoelSpeed]

/retest

[hypershift-jira-solve-ci]

I now have all the evidence I need. Let me compile the final analysis. The key findings are:

1. Primary failure: TestCreateCluster/Main/EnsureGlobalPullSecret/When_management-cluster_hostedCluster.Spec.PullSecret_is_updated_in-place_it_should_propagate_to_guest_without_rollout — the global-pull-secret-syncer DaemonSet was stuck at 2/3 pods ready for 20 minutes until timeout.

2. Secondary failure: TestCreateCluster/Main/EnsureGlobalPullSecret/Check_if_the_config.json_is_correct_in_all_of_the_nodes — failed because the kubelet-config-verifier DaemonSet from the first subtest still existed (AlreadyExists error), a cascading consequence of the first failure not cleaning up properly.

3. PR is unrelated: PR NO-JIRA: remove TODO comments from generated API documentation #8363 only changes API doc comments (moving TODO comments from within godoc blocks to before them). Zero functional code changes.

Test Failure Analysis Complete

Job Information

• Prow Job: pull-ci-openshift-hypershift-main-e2e-aws
• Build ID: 2076595288583180288
• Target: e2e-aws
• PR: NO-JIRA: remove TODO comments from generated API documentation #8363 (NO-JIRA: remove TODO comments from generated API documentation)

Test Failure Analysis

Error

TestCreateCluster/Main/EnsureGlobalPullSecret/When_management-cluster_hostedCluster.Spec.PullSecret_is_updated_in-place_it_should_propagate_to_guest_without_rollout (1205.07s):
  failed to wait for DaemonSet global-pull-secret-syncer to be ready: context deadline exceeded

TestCreateCluster/Main/EnsureGlobalPullSecret/Check_if_the_config.json_is_correct_in_all_of_the_nodes (0.03s):
  daemonsets.apps "kubelet-config-verifier" already exists

Summary

The EnsureGlobalPullSecret test failed because the global-pull-secret-syncer DaemonSet in the hosted cluster remained stuck at 2/3 pods ready for the entire 20-minute timeout. The hosted cluster had 3 nodes (one per AZ: us-east-1a, 1b, 1c) and one of the DaemonSet pods on these nodes never became ready after the management-cluster pull secret was patched with a dummy auth entry. This caused the first subtest to timeout, and the second subtest (Check_if_the_config.json_is_correct_in_all_of_the_nodes) failed with an AlreadyExists error because the kubelet-config-verifier DaemonSet created during the first subtest was never cleaned up. This failure is unrelated to PR #8363, which only moves TODO comments in API documentation — it touches zero functional code, zero test code, and zero pull-secret logic.

Root Cause

The global-pull-secret-syncer DaemonSet had 3 desired pods (one per node) but only 2 became ready after the management-cluster pull secret was modified with a dummy auth entry. The 3rd pod on one of the nodes never reached Ready status within the 20-minute polling timeout (polls every 10 seconds).

The test flow is:

1. Patch the management-cluster pull secret with a dummy auth entry
2. Wait for the change to propagate to the guest cluster's openshift-config/pull-secret
3. Wait for it to propagate to kube-system/original-pull-secret
4. Verify no NodePool rollout was triggered
5. Create a kubelet-config-verifier DaemonSet
6. Wait for ovnkube-node, global-pull-secret-syncer, konnectivity-agent, and kubelet-config-verifier DaemonSets to all be ready
7. The test stalled at step 6 waiting for global-pull-secret-syncer

The ovnkube-node DaemonSet was 3/3 ready immediately, confirming all 3 nodes were schedulable. The global-pull-secret-syncer was stuck at 2/3 — this is a flaky infrastructure condition where one pod on one node failed to become ready after the pull secret update, likely due to a transient issue with pull secret propagation to that node or the pod restarting after the config change and not recovering in time.

The secondary failure (Check_if_the_config.json_is_correct_in_all_of_the_nodes) is a cascading test bug: after the first subtest times out, it doesn't clean up the kubelet-config-verifier DaemonSet, so the second subtest tries to create it again and gets a 409 Conflict / AlreadyExists error.

This failure is entirely unrelated to PR #8363. The PR modifies only API documentation comments (moving TODO lines from within godoc comment blocks to before them). It changes files in api/hypershift/v1beta1/, docs/content/reference/, CRD manifests, and vendored copies. None of these changes affect pull secret handling, DaemonSet behavior, or test logic.

Recommendations

1. Retry the job — This is a pre-existing flake in the EnsureGlobalPullSecret test, not caused by this PR's changes. The PR only touches API documentation comments.

2. File a bug for the cascading test failure — The Check_if_the_config.json_is_correct_in_all_of_the_nodes subtest fails with AlreadyExists when the preceding subtest times out, because the kubelet-config-verifier DaemonSet isn't cleaned up. The test code in globalps.go:209 should use CreateOrUpdate semantics or clean up the DaemonSet in a t.Cleanup() registered before the timeout-prone wait.

3. Investigate the global-pull-secret-syncer DaemonSet readiness flake — The 2/3 readiness pattern suggests one node's pod consistently fails to become ready after pull secret changes. The test could benefit from additional logging of the individual pod statuses (which node's pod is not ready, pod conditions, container status) to help diagnose the root cause in future occurrences.

Evidence

Evidence	Detail
Failing test	TestCreateCluster/Main/EnsureGlobalPullSecret/When_management-cluster_hostedCluster.Spec.PullSecret_is_updated_in-place_it_should_propagate_to_guest_without_rollout
Error message	failed to wait for DaemonSet global-pull-secret-syncer to be ready: context deadline exceeded
Duration stuck	1205 seconds (~20 minutes), 362 repeated log lines of "DaemonSet global-pull-secret-syncer not ready: 2/3 pods ready"
DaemonSet status	ovnkube-node 3/3 ready ✓, global-pull-secret-syncer stuck at 2/3
Cluster nodes	3 nodes across AZs us-east-1a, us-east-1b, us-east-1c
Secondary failure	Check_if_the_config.json_is_correct_in_all_of_the_nodes — daemonsets.apps "kubelet-config-verifier" already exists (409 Conflict)
Test code location	test/e2e/util/globalps.go:209-220, test/e2e/util/util.go:2263-2302
PR #8363 changes	API doc comments only — api/hypershift/v1beta1/*.go, CRD YAMLs, docs/content/reference/*.md, vendored copies
PR relevance	None — zero functional code changes, zero test changes, zero pull-secret logic changes

---

[openshift-ci]

@tuxerrante: The following tests failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
ci/prow/e2e-azure-self-managed	18b5f9c	link	true	/test e2e-azure-self-managed
ci/prow/e2e-kubevirt-aws-ovn-reduced	18b5f9c	link	true	/test e2e-kubevirt-aws-ovn-reduced
ci/prow/e2e-aws	18b5f9c	link	true	/test e2e-aws

Full PR test history. Your PR dashboard.

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 kubernetes-sigs/prow repository. I understand the commands that are listed here.

[bryan-cox]

/verified bypass

We don't need to verify removed TODO comments here.

[openshift-ci-robot]

@bryan-cox: The verified label has been added.

Details

In response to this:

/verified bypass

We don't need to verify removed TODO comments here.

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.