api updates

enhancements/installer/vsphere-ipi-zonal.md

@@ -13,7 +13,7 @@ api-approvers:
   - "@JoelSpeed"
   - "@deads2k"
 creation-date: 2021-09-21
-last-updated: 2024-09-05
+last-updated: 2024-09-23
 status: implementable
 see-also:
   - "/enhancements/"
@@ -57,7 +57,11 @@ of the concept of regions and zoning that this type of deployment would
 offer.
 
 - https://issues.redhat.com/browse/RFE-845
+- https://issues.redhat.com/browse/RFE-4540
+- https://issues.redhat.com/browse/RFE-4803
+- https://issues.redhat.com/browse/RFE-5527
 - https://issues.redhat.com/browse/OCPPLAN-4927
+- https://issues.redhat.com/browse/OCPSTRAT-1577
 
 ### Goals
 
@@ -70,7 +74,7 @@ To be able to install OpenShift on vSphere with a set topology. This includes:
 ## Existing and Proposal
 
 Modification of the installer to support:
-- the provisioning of masters in defined datacenters and clusters.
+- the provisioning of control plane nodes in defined datacenters and clusters.
 - provisioning in a stretched vSphere cluster using a cluster as a region and hosts as zones
 
 ### Workflow Description
@@ -365,30 +369,29 @@ type VSpherePlatformSpec struct {
 type VSphereFailureDomainType string
 
 const (
-	// HostGroupFailureDomain is a failure domain for a host group.
+	// HostGroupFailureDomain is a failure domain for a vCenter vm-host group.
 	HostGroupFailureDomain VSphereFailureDomainType = "HostGroup"
-	// ComputeClusterFailureDomain is a failure domain for a compute cluster.
+	// ComputeClusterFailureDomain is a failure domain for a vCenter compute cluster.
 	ComputeClusterFailureDomain VSphereFailureDomainType = "ComputeCluster"
-	// DatacenterFailureDomain is a failure domain for a datacenter.
+	// DatacenterFailureDomain is a failure domain for a vCenter datacenter.
 	DatacenterFailureDomain VSphereFailureDomainType = "Datacenter"
 )
 
-// VSpherePlatformFailureDomainSpec holds the region and zone failure domain and
-// the vCenter topology of that failure domain.
-// +kubebuilder:validation:XValidation:rule=" self.ZoneType !has(oldSelf.vcenters) && has(self.vcenters) ? size(self.vcenters) < 2 : true",message="vcenters can have at most 1 item when configured post-install"
+// VSpherePlatformFailureDomainSpec holds the region and zone failure domain and the vCenter topology of that failure domain.
+// +kubebuilder:validation:XValidation:rule="has(self.zoneType) && self.zoneType == 'HostGroup' ? self.topology.affinity.vmGroup != '' && self.topology.affinity.hostGroup != '' && self.topology.affinity.vmHostRule != '' : true",message="when zoneType is HostGroup, failuredomain topology affinity vmGroup, hostGroup and vmHostRule fields must be defined"
+// +kubebuilder:validation:XValidation:rule="has(self.topology.affinity) && (self.topology.affinity.vmGroup != '' || self.topology.affinity.hostGroup != '' || self.topology.affinity.vmHostRule != '') ? has(self.zoneType) && self.zoneType == 'HostGroup' : true",message="when failuredomain topology affinity vmGroup, hostGroup and vmHostRule fields are defined failuredomain zoneType must be HostGroup"
 type VSpherePlatformFailureDomainSpec struct {
 	// regionType defines the type of region that is used for this failure domain. The current available options
-	// are "", ComputeCluster and Datacenter.
+	// are ComputeCluster and Datacenter.
 	// +openshift:validation:FeatureGateAwareEnum:featureGate=VSphereHostVMGroupZonal,enum=ComputeCluster;Datacenter
 	// +kubebuilder:validation:MinLength=9
 	// +kubebuilder:validation:MaxLength=14
 	// +kubebuilder:validation:Optional
 	// +optional
 	RegionType string `json:"regionType,omitempty"`
 
-
 	// zoneType defines the type of zone that is used for this failure domain. The current available options
-	// are "", HostGroup and ComputeCluster.
+	// are HostGroup and ComputeCluster.
 	// +kubebuilder:validation:MinLength=9
 	// +kubebuilder:validation:MaxLength=14
 	// +kubebuilder:validation:Optional
@@ -401,16 +404,15 @@ type VSpherePlatformFailureDomainSpec struct {
 // computeCluster, networks, datastore and resourcePool - to provision virtual machines.
 type VSpherePlatformTopology struct {
 	// affinity holds the VMGroup and the HostGroup names in vCenter corresponds to 
-	// a vm-host group of type Virtual Machine and Host respectiviely. Is also
-	// contains the VMHostRule which is a affinity vm-host rule in vCenter
-	//
+	// a vm-host group of type Virtual Machine and Host respectively. Is also
+	// contains the VMHostRule which is an affinity vm-host rule in vCenter.
 	// +openshift:validation:featureGate=VSphereHostVMGroupZonal
 	// +kubebuilder:validation:Optional
 	// +optional
 	Affinity VSphereFailureDomainAffinity `json:"affinity,omitempty"`
 }
 
-// VSphereFailureDomainAffinity contains the vSphere vm-host group (virtual machine and host types) 
+// VSphereFailureDomainAffinity contains the vCenter cluster vm-host group (virtual machine and host types) 
 // and the vm-host affinity rule that together creates a affinity configuration for vm-host based zonal. 
 // This configuration within vCenter creates the required association between a failure domain, virtual machines
 // and ESXi hosts to create a vm-host based zone.
@@ -793,32 +795,38 @@ func (h *Host) IsBootstrap() bool {
 ##### Changes and additions to platform spec for host-based zonal
 
 ```golang
+// The FailureDomainType is a string representation of a failure domain
+// type. There are three supportable types: HostGroup, ComputeCluster and Datacenter
+type VSphereFailureDomainType string
+
 const (
-	// HostGroupFailureDomain is a failure domain for a host group.
+	// HostGroupFailureDomain is a failure domain for a vCenter vm-host group.
 	HostGroupFailureDomain FailureDomainType = "HostGroup"
-	// ComputeClusterFailureDomain is a failure domain for a compute cluster.
+	// ComputeClusterFailureDomain is a failure domain for a vCenter compute cluster.
 	ComputeClusterFailureDomain FailureDomainType = "ComputeCluster"
-	// DatacenterFailureDomain is a failure domain for a datacenter.
+	// DatacenterFailureDomain is a failure domain for a vCenter datacenter.
 	DatacenterFailureDomain FailureDomainType = "Datacenter"
 )
 
 type FailureDomain struct {
-	// Type is the type of failure domain, the current values are "Datacenter", "ComputeCluster" and "HostGroup"
-	// +kubebuilder:validation:Enum=Datacenter;ComputeCluster;HostGroup
+	// regionType defines the type of region that is used for this failure domain. The current available options
+	// are "ComputeCluster" and "HostGroup"
+	// +kubebuilder:validation:Enum=Datacenter;ComputeCluster
 	// +optional
 	RegionType FailureDomainType `json:"regionType,omitempty"`
-	// Type is the type of failure domain, the current values are "Datacenter", "ComputeCluster" and "HostGroup"
-	// +kubebuilder:validation:Enum=Datacenter;ComputeCluster;HostGroup
+	// zoneType defines the type of zone that is used for this failure domain. The current available options
+	// are HostGroup and ComputeCluster.
+	// +kubebuilder:validation:Enum=ComputeCluster;HostGroup
 	// +optional
 	ZoneType FailureDomainType `json:"zoneType,omitempty"`
 }
 
 
 type Topology struct {
-    // HostGroup is the name of the pre-existing VM-Host (host) group that contains the 
-    // ESXi hosts for this zone. This field is required when ZoneType is HostGroup. 
+    // HostGroup is the name of the vCenter Cluster vm-host group of type host for this failure domain.
+	// This field is required when the VSphereFailureDomain ZoneType is HostGroup
 	// +kubebuilder:validation:MinLength=1
-	// +kubebuilder:validation:MaxLength=2048
+	// +kubebuilder:validation:MaxLength=80
 	// +optional
 	HostGroup string `json:"hostGroup,omitempty"`
 }
@@ -917,8 +925,6 @@ for _, failureDomain := range installConfig.Config.VSphere.FailureDomains {
 
 ```
 
-
-
 #### Cloud Config
 
 The external CCM is required for this change. The out-of-tree CCM also updates