feat: [pko-351] added documentation for HostedClusterPackage API

Signed-off-by: Ankit152 <[email protected]>

Author: Ankit152

content/en/docs/advanced_features/hostedclusterpackage-api.md

@@ -0,0 +1,169 @@
+---
+title: HostedClusterPackage API
+weight: 1200
+images: []
+mermaid: true
+---
+
+The `HostedClusterPackage` API extends Package Operator with progressive
+rollout capabilities for Packages targeting HyperShift Hosted Control Planes
+(HCP). It introduces a cluster-scoped custom resource, the Package, which
+governs the lifecycle and update process of Packages across all hosted control
+planes within a HyperShift Management Cluster.
+
+## Overview
+
+This API allows for the gradual rollout of updates to HostedClusters,
+significantly reducing the "blast radius" of failed upgrades compared to
+simultaneous updates. It also simplifies the configuration required to deliver
+objects into an HCP namespace by reducing the dependency on multiple systems
+(Hive, ACM) down to a single API.
+
+```mermaid
+flowchart LR
+  subgraph Hive
+    metrics-sss["metrics-forwarder<br><b>SelectorSyncSet</b>"]
+  end
+  subgraph HyperShift Management Cluster
+    metrics-hsp["metrics-forwarder<br><b>HyperShift Package</b>"]
+    subgraph Namespace: my-cluster-x
+      ns-c1["<b>Package</b>"]
+    end
+    subgraph Namespace: my-cluster-y
+      ns-c2["<b>Package</b>"]
+    end
+  end
+  metrics-sss--->metrics-hsp
+  metrics-hsp--->ns-c1
+  metrics-hsp--->ns-c2
+```
+
+### Key Features
+
+* **Progressive Rollout**: Updates are rolled out gradually to HostedClusters
+  rather than all at once.
+* **Lifecycle Automation**: Automatically creates Packages for new
+  HostedClusters and deletes them when the cluster is removed.
+* **Status & Monitoring**: Provides metrics and status updates on the number
+  of available, unavailable, or updated packages.
+* **Simplified Configuration**: Reduces the configuration surface from
+  multiple objects (SelectorSyncSet, Policy, PlacementRule, etc.) to just the
+  `HostedClusterPackage` API.
+
+## HostedClusterPackage Resource
+
+The `HostedClusterPackage` resource is the core configuration object for this API.
+It coordinates the rollout process and defines how updates traverse the fleet
+of HostedClusters.
+
+### Targeting Clusters
+
+The API includes an optional label selector to target specific HostedClusters
+within the Management cluster.
+
+### Partitioning
+
+To control the order of updates, you can attach an optional partition configuration
+to the Package API. This ensures that all items within a specific group are processed
+before the rollout moves to the next group.
+
+* **Grouping**: The configuration uses labels on the HostedCluster object to
+  assign groups (e.g., hypershift.openshift.io/risk-group).
+* **Ordering**: Groups can be ordered via a static list or by alphanumeric
+  ascending order.
+* **Implicit Handling**: HostedClusters without the specified label or with
+  unknown values are placed in an implicit "unknown" group and upgraded last.
+* **Dynamic Regrouping**: If a cluster's label changes to an earlier group
+  during an upgrade, the process will jump back to handle that group before
+  continuing.
+
+### Progression Strategies
+
+The API supports configurable progression strategies to control the speed and safety
+of the rollout.
+
+### Rolling Upgrade
+
+The `rollingUpgrade` strategy is designed to keep service disruptions to a minimum.
+
+* `maxUnavailable`: Configures the maximum number of Package instances that
+  can be updating or unavailable at the same time. If a Package is already
+  unavailable before the upgrade starts, it counts towards this limit. These
+  unavailable packages are prioritized for updates to prevent accumulating
+  faulty versions.
+* `minReadySeconds`: Specifies the minimum time to wait before considering a
+  package ready (e.g., 60 seconds).
+
+## Status & Observability
+
+The Package API exposes status information to help you track the progress of a
+rollout and the health of the fleet. This status is critical for understanding
+if an update is proceeding smoothly or if it has stalled due to errors.
+
+### Rollout State
+
+The status subresource provides high-level metrics regarding the rollout
+process. These fields allow you to quickly assess the distribution of package
+versions across your HostedClusters:
+
+* **Updated Packages**: The number of HostedClusters that have successfully
+  received the latest version of the Package.
+
+* **Available Packages**: The number of HostedClusters where the Package is
+  currently healthy and serving traffic.
+
+* **Unavailable Packages**: The number of HostedClusters where the Package is
+  currently degraded or updating. This count is used to enforce the
+  maxUnavailable limit defined in the progression strategy.
+
+### Progression Logic
+
+The operator uses the status of individual Packages to determine if the rollout can
+proceed to the next target.
+
+* **Success**: If a targeted HostedCluster successfully updates and becomes
+  available, the operator proceeds to select the next cluster in the partition.
+
+* **Failure**: If a Package update fails or becomes unavailable, the rollout
+  pauses for that specific rollout path. This prevents the propagation of errors
+  to the rest of the fleet.
+
+## Monitoring
+
+In addition to the resource status, the controller exports metrics that
+provide a fleet-wide overview of the rollout state. SREs can utilize these
+metrics to build dashboards that visualize the number of available versus
+unavailable packages over time.
+
+## Configuration Example
+
+The following YAML example demonstrates a Package configured with
+risk-based partitioning and a rolling upgrade strategy.
+
+```yaml
+apiVersion: package-operator.run/v1alpha1
+kind: HostedClusterPackage
+metadata:
+  name: example-hosted-cluster-package
+spec:
+  # Partition Configuration
+  partition:
+    labelKey: hypershift.openshift.io/risk-group
+    order:
+      # Static ordering example:
+      static:
+        - early
+        - normal
+        - late
+      # OR Alphanumeric ordering (mutually exclusive with static):
+      # alphanumericAsc: {}
+
+  # Progression Strategy
+  minReadySeconds: 60
+  strategy:
+    rollingUpgrade:
+      maxUnavailable: 1 # Max packages to update concurrently
+```
+
+**Note**: The `HostedClusterPackage` API is experimental and subject to
+change in future.