[PKO-351] Added documentation for HostedClusterPackage API

[Ankit152]

Jira: PKO-351

[eqrx]

@CodeRabbit full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Adds a cluster-scoped HostedClusterPackage API (spec/status/partitioning/order/ref types), introduces PackageTemplateSpec, and updates package-operator API fields with revision/version metadata; includes new documentation and examples. No runtime behavior changes beyond API/type additions.

Changes

Cohort / File(s)	Summary
HostedClusterPackage documentation content/en/docs/advanced_features/hostedclusterpackage-api.md	New documentation describing the HostedClusterPackage API: overview, targeting/partitioning, progression, status/monitoring, examples, and a Mermaid diagram.
Package operator API reference & types content/en/docs/api_reference/package-operator-api.md	Adds HostedClusterPackage types (HostedClusterPackage, HostedClusterPackageSpec, HostedClusterPackageStatus, partition/order/ref/status types); introduces PackageTemplateSpec; adds revision fields to ClusterObjectSetSpec and ObjectSetSpec, deprecates ObjectSetStatus.revision description; adds version fields to controller/controlled references; updates examples and API reference text for partitioned rollouts and versioning.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: adding documentation for the HostedClusterPackage API, which matches the file additions and API reference updates in the changeset.
Description check	✅ Passed	The description references the Jira ticket (PKO-351) related to the changes, and while minimal, it is directly related to the PR's objective of adding HostedClusterPackage API documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

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

[coderabbitai]

Actionable comments posted: 5

🤖 Fix all issues with AI agents

In `@content/en/docs/advanced_features/hostedclusterpackage-api.md`:
- Around line 8-9: Update the note sentence that currently reads "**Note**: The
`HostedClusterPackage` API is experimental and subject to change in future." to
use US English by inserting "the" so it reads "...subject to change in the
future." — locate the string containing `HostedClusterPackage` and replace
"change in future" with "change in the future".
- Around line 13-15: The text incorrectly refers to the resource as "the
Package" which is ambiguous; update the wording to consistently use the correct
resource name HostedClusterPackage (e.g., change "the Package" to "the
HostedClusterPackage") and scan the surrounding lines in this section to replace
any other occurrences of the generic "Package" with HostedClusterPackage to
avoid confusion.
- Around line 103-110: Check the CRD for HostedClusterPackage (spec and
strategy) to confirm whether the field minReadySeconds is defined; if
minReadySeconds exists, add it to the API reference under
HostedClusterPackageSpec or HostedClusterPackageStrategyRollingUpgrade with its
type and semantics, otherwise remove all mentions of minReadySeconds from the
rolling upgrade guide and the YAML example in the guide; update the docs to keep
the API reference and guide consistent and ensure the YAML example uses only
documented fields.

In `@content/en/docs/api_reference/package-operator-api.md`:
- Around line 428-435: The example is invalid because partition.order mixes two
mutually exclusive strategies (partition.order.alphanumericAsc and
partition.order.static) and strategy is a quoted string instead of a mapping;
fix by choosing one ordering strategy under partition.order (remove either
alphanumericAsc or static so only one remains) while keeping partition.labelKey
unchanged, and change strategy from a quoted string to a YAML mapping (e.g.,
replace the quoted 'strategy' value with a mapping form like strategy: {instant:
{}}) so the example is valid and consistent; reference
partition.order.alphanumericAsc, partition.order.static, partition.labelKey, and
strategy to locate the fixes.
- Line 1406: The table cell for `metadata` (the PackageTemplateSpec `metadata`
description row containing "More info: https://git.k8s.io/...") uses a bare URL;
update that markdown to use a link instead (for example, replace the bare URL
with a markdown link like "More info: [Kubernetes API
conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata)")
so the URL is not bare and markdownlint will pass. Target the table row that
contains `metadata` and `metav1.ObjectMeta` and modify only the description
string.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@content/en/docs/advanced_features/hostedclusterpackage-api.md`:
- Around line 118-120: Replace the typo "arollout" with "a rollout" in the
sentence that describes the HostedClusterPackage API status (the line containing
"The `HostedClusterPackage` API exposes status information to help you track the
progress of arollout and the health of the fleet."); keep the rest of the
sentence unchanged so it reads "track the progress of a rollout and the health
of the fleet."
- Around line 20-21: Fix the typo and spacing in the sentence containing
"controll rollout strategies,significantly reducing the \"blast radius\"" by
changing "controll" to "control" and adding a space after the comma so it reads
"control rollout strategies, significantly reducing the \"blast radius\"".
Ensure the corrected sentence preserves the surrounding wording and punctuation.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@content/en/docs/api_reference/package-operator-api.md`:
- Around line 975-1102: The docs reference two missing type
sections—HostedClusterPackagePartitionOrderAlphanumericAsc and
HostedClusterPackageStrategyInstant—so add dedicated documentation blocks for
each with a heading matching the type name, a short description of the type, a
field table listing all fields and their descriptions (matching the style used
for HostedClusterPackagePartitionOrderSpec and
HostedClusterPackageStrategyRollingUpgrade), and a "Used in:" list linking back
to the parent types (ensure links point to
HostedClusterPackagePartitionOrderSpec and HostedClusterPackageStrategy
respectively); implement these new sections so the references at
HostedClusterPackagePartitionOrderSpec and HostedClusterPackageStrategy resolve
and the API surface is complete.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@content/en/docs/api_reference/package-operator-api.md`:
- Around line 975-1102: The docs are missing definition sections for the types
referenced: HostedClusterPackagePartitionOrderAlphanumericAsc and
HostedClusterPackageStrategyInstant; add a new heading for each (e.g., "###
HostedClusterPackagePartitionOrderAlphanumericAsc" and "###
HostedClusterPackageStrategyInstant"), provide a short description of the type's
purpose, include either a field table (if the type has fields) or a one-line
note stating it is a marker/empty spec (no fields), and add a "Used in:" line
linking back to the parent types that reference them
(HostedClusterPackagePartitionOrderSpec and HostedClusterPackageStrategy
respectively) so readers can find where they are used.

🧹 Nitpick comments (3)

content/en/docs/api_reference/package-operator-api.md (3)

982-982: Add description for alphanumericAsc field.

The alphanumericAsc field has no description. Even if the type it references has no fields, the table should explain what this ordering strategy does (e.g., "Orders partitions alphanumerically in ascending order.").

---

1082-1082: Add description for instant field.

The instant field has no description. Add an explanation of what the instant strategy does (e.g., "Updates all matching Packages instantly without waiting.").

---

1031-1033: Add descriptions for HostedClusterPackageRefStatus fields.

The uid, name, and namespace fields all lack descriptions. Provide meaningful descriptions for these reference fields (e.g., "UID of the referenced Package", "Name of the referenced Package", "Namespace of the referenced Package (empty for cluster-scoped)").

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@content/en/docs/advanced_features/hostedclusterpackage-api.md`:
- Line 162: Fix the spelling in the heading string "Example `Status` and
`Conditons` for a successful rollout:" by changing "Conditons" to "Conditions"
so the line reads "Example `Status` and `Conditions` for a successful rollout:";
update that exact heading text in the document (search for the literal "Example
`Status` and `Conditons` for a successful rollout:") to correct the typo.

f