Address review feedback for ARO HCP proposal

Updates based on willie-yao's review comments:

- Update metadata: add reviewers, fix dates, change status to implementable
- Fix API versions: v1beta2 → v1beta1 throughout examples
- Add "Alternatives Considered" section explaining why separate CRDs are needed
- Add "Maintenance and Ownership" section clarifying ARO team ownership
- Document ASO migration plan with dependency chain
- Add references to ARO-HCP repository and API specifications
- Note API versions: 2024-06-10-preview (private) vs 2025-12-23-preview (public)
- Add ASO issue reference for key management gap
- Update graduation criteria with ownership and migration commitments

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: marek-veber

docs/proposals/20250425-aro-hcp.md

@@ -4,10 +4,11 @@ authors:
  - "@serngawy"
  - "@marek-veber"
 reviewers:
- - ""
-creation-date: 2025-04-23
-last-updated: 2026-02-20
-status: implemented
+ - "@willie-yao"
+ - "@jackfrancis"
+creation-date: 2025-04-25
+last-updated: 2026-03-11
+status: implementable
 ---
 
 
@@ -23,6 +24,8 @@ status: implemented
 - [Proposal](#proposal)
 - [User Stories](#user-stories)
 - [Implementation Details](#implementation-details)
+- [Alternatives Considered](#alternatives-considered)
+- [Maintenance and Ownership](#maintenance-and-ownership)
 - [Risks and Mitigations](#risks-and-mitigations)
 - [Graduation Criteria](#graduation-criteria)
 - [Implementation History](#implementation-history)
@@ -33,6 +36,8 @@ status: implemented
 
 The Cluster API Provider for Azure (CAPZ) extends Kubernetes Cluster API functionality to Microsoft Azure environments, facilitating the management and lifecycle of Kubernetes clusters on Azure. This proposal outlines the integration of Azure Red Hat OpenShift (ARO) Hosted Control Plane (HCP) clusters within CAPZ using Azure Service Operator (ASO) for resource provisioning.
 
+ARO HCP is an evolution of Azure Red Hat OpenShift that uses a hosted control plane architecture. For more information about ARO HCP, see the [ARO-HCP repository](https://github.com/Azure/ARO-HCP).
+
 The implementation leverages ASO resources embedded directly in Custom Resource specifications, providing a declarative, Kubernetes-native approach to managing ARO HCP infrastructure.
 
 
@@ -115,9 +120,13 @@ type AROControlPlaneSpec struct {
  // - HcpOpenShiftCluster resource
  // - HcpOpenShiftClustersExternalAuth resource (if external auth is needed)
  //
- // Example resources:
+ // Example resources (using private preview API v1api20240610preview):
  // - redhatopenshift.azure.com/v1api20240610preview/HcpOpenShiftCluster
  // - redhatopenshift.azure.com/v1api20240610preview/HcpOpenShiftClustersExternalAuth
+ //
+ // Note: v1api20240610preview is the private preview API. Migration to public preview
+ // API (v1api20251223preview) is planned. See API specs at:
+ // https://github.com/Azure/ARO-HCP/tree/main/api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/hcpclusters/preview
  Resources []runtime.RawExtension `json:"resources,omitempty"`
 
  // IdentityRef is a reference to an identity to be used when reconciling the ARO control plane.
@@ -203,7 +212,7 @@ type ResourceStatus struct {
 An example of AROControlPlane CR using resources mode:
 
 ```yaml
-apiVersion: controlplane.cluster.x-k8s.io/v1beta2
+apiVersion: controlplane.cluster.x-k8s.io/v1beta1
 kind: AROControlPlane
 metadata:
   name: my-cluster
@@ -343,7 +352,7 @@ status:
 This example shows AROControlPlane using ASO credentials instead of identityRef:
 
 ```yaml
-apiVersion: controlplane.cluster.x-k8s.io/v1beta2
+apiVersion: controlplane.cluster.x-k8s.io/v1beta1
 kind: AROControlPlane
 metadata:
   name: hcp-cluster
@@ -471,7 +480,7 @@ type AROMachinePoolSpec struct {
  // Resources are embedded ASO resources to be managed by this AROMachinePool.
  // Must include HcpOpenShiftClustersNodePool resource.
  //
- // Example:
+ // Example (using private preview API v1api20240610preview):
  // - redhatopenshift.azure.com/v1api20240610preview/HcpOpenShiftClustersNodePool
  Resources []runtime.RawExtension `json:"resources"`
 }
@@ -498,7 +507,7 @@ type AROMachinePoolStatus struct {
 An example of AROMachinePool CR:
 
 ```yaml
-apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
 kind: AROMachinePool
 metadata:
   name: my-cluster-mp1
@@ -620,7 +629,7 @@ type AROClusterInitializationStatus struct {
 An example of AROCluster CR:
 
 ```yaml
-apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
 kind: AROCluster
 metadata:
   name: my-cluster
@@ -1066,7 +1075,7 @@ spec.properties.etcd.dataEncryption.customerManaged.kms.activeKey.version
 **Solution**: Add the Vault resource to **AROCluster.spec.resources[]** (not AROControlPlane):
 
 ```yaml
-apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
 kind: AROCluster
 metadata:
   name: my-cluster
@@ -1148,6 +1157,10 @@ spec:
 
 - **Azure SDK**: Used only for encryption key management (when identityRef is set)
   - KeyVault keys (create/retrieve key versions within existing vault)
+  - **Note**: This is a temporary gap in ASO coverage. ASO supports Vault CRDs but not key management. See upstream tracking: [Azure/azure-service-operator#4481](https://github.com/Azure/azure-service-operator/issues/4481)
+  - This SDK dependency will be removed once ASO adds key version retrieval support
+  - **Note**: This is a temporary gap in ASO's coverage. ASO currently supports Vault CRDs but not Key management within vaults. There is an upstream ASO issue tracking this: [Azure/azure-service-operator#4481](https://github.com/Azure/azure-service-operator/issues/4481)
+  - **Future**: Once ASO adds support for key version retrieval, the keyvaults SDK service can be removed entirely
 
 ### Validation and Testing
 
@@ -1193,6 +1206,40 @@ Resource Deployment
 - Testing of error conditions and recovery
 - Testing of both authentication modes (CAPZ managed vs ASO credential-based)
 
+## Alternatives Considered
+
+### Using AzureASOManagedControlPlane
+
+AzureASOManagedControlPlane is designed for AKS managed clusters using `containerservice.azure.com` resources. ARO HCP uses fundamentally different Azure resource types (`redhatopenshift.azure.com/HcpOpenShiftCluster`) with ARO-specific requirements including ETCD encryption with Key Vault integration, external authentication resources, and different node pool APIs. The architectural differences are significant enough that separate CRDs provide clearer API boundaries and simpler controller logic than trying to unify both platforms under a single type.
+
+### Pure ASO Without CAPZ Controllers
+
+While ASO provides Azure resource management, CAPZ controllers add Cluster API integration (lifecycle management, dependency orchestration, status aggregation) and automation features like encryption key version injection. Users who don't need CAPI integration can use ASO directly with `identityRef: nil` mode.
+
+## Maintenance and Ownership
+
+The ARO HCP integration is **owned and maintained by the Azure Red Hat OpenShift (ARO) team at Red Hat**. This includes the AROControlPlane, AROMachinePool, and AROCluster CRDs, controllers, webhooks, and ARO-specific documentation.
+
+**CAPZ core team responsibilities** are limited to maintaining shared infrastructure (ASO integration patterns, common libraries) and reviewing ARO pull requests for CAPZ architectural alignment. The CAPZ core team is **not expected to own or maintain ARO-specific logic**.
+
+### Azure SDK Usage and ASO Migration Plan
+
+The keyvaults service currently uses Azure SDK for key version retrieval because ASO doesn't yet support Key Vault key management CRDs (only Vault resources). This SDK usage is temporary and will be removed once ASO coverage is available.
+
+**ARO HCP API Versions**:
+- **2024-06-10-preview**: Private preview API version (currently used in this implementation)
+- **2025-12-23-preview**: Public preview API version (planned migration target)
+
+API specifications are maintained in the [ARO-HCP repository](https://github.com/Azure/ARO-HCP/tree/main/api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/hcpclusters/preview).
+
+**Dependency chain for full ASO migration**:
+1. ARO HCP public preview completion (pending Microsoft release formalities)
+2. ARO HCP API specification merged into Azure REST API specs repository
+3. ASO generation of ARO HCP CRDs from updated specs
+4. Backporting ASO changes to the release version used by CAPZ
+
+Once these dependencies are resolved and ASO supports key management, the keyvaults SDK service will be removed entirely. The ARO team commits to migrating to pure ASO-native implementation at that time.
+
 ## Risks and Mitigations
 
 - **ASO API Changes**: Monitor ASO releases and update resource definitions accordingly
@@ -1209,6 +1256,9 @@ Resource Deployment
 - ✅ Encryption key management working correctly
 - ✅ ExternalAuth configuration functioning properly
 - ✅ Clean code with field-based mode removed (~5,400 lines removed)
+- ✅ Maintenance ownership documented and agreed upon
+- ✅ Plan documented to remove keyvaults SDK service when ASO supports key version retrieval
+- ✅ Acknowledgment that CAPZ's long-term direction is toward pure ASO-native controllers
 
 ## Implementation History