[PKO-351] Added documentation for HostedClusterPackage API

[Ankit152]

Jira: PKO-351

[eqrx]

@CodeRabbit full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[coderabbitai]

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 file 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 (e.g., 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 to reflect 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 indicates the addition of documentation for the HostedClusterPackage API, which aligns with the primary change in the changeset.
Description check	✅ Passed	The description references a Jira ticket (PKO-351) that relates to adding documentation for the HostedClusterPackage API, matching the changeset content.
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

---

_{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]

⚠️ Potential issue | 🟡 Minor

Avoid bare URL in table description.

The PackageTemplateSpec metadata description uses a bare URL; markdownlint flags this. Please wrap it as a link.

✏️ Suggested edit

-| `metadata` <br>metav1.ObjectMeta | Standard object's metadata.<br>More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata |
+| `metadata` <br>metav1.ObjectMeta | Standard object's metadata.<br>More info: [Kubernetes API conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata) |

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	| `metadata` <br>metav1.ObjectMeta | Standard object's metadata.<br>More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata |
	| `metadata` <br>metav1.ObjectMeta | Standard object's metadata.<br>More info: [Kubernetes API conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata) |

🧰 Tools

🪛 markdownlint-cli2 (0.20.0)

1406-1406: Bare URL used

(MD034, no-bare-urls)

🤖 Prompt for AI Agents

In `@content/en/docs/api_reference/package-operator-api.md` at 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]

⚠️ Potential issue | 🟠 Major

Missing type definitions were not actually added.

A previous review comment flagged that HostedClusterPackagePartitionOrderAlphanumericAsc (referenced at line 982) and HostedClusterPackageStrategyInstant (referenced at line 1082) lacked documentation sections, and was marked as "✅ Addressed in commit 5055570." However, searching the current document reveals these type definition sections are still missing. Users need dedicated documentation blocks explaining what these types do.

Each missing type should have:

• A heading (e.g., ### HostedClusterPackagePartitionOrderAlphanumericAsc)
• A description explaining the type's purpose
• A field table (or note that it has no fields if it's a marker type)
• A "Used in:" section linking back to parent types

🤖 Prompt for AI Agents

In `@content/en/docs/api_reference/package-operator-api.md` around lines 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.

[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.