Update api specs to add Ignition (#1649)

docs/proposal/20231109-powervs-infra-creation.md

@@ -31,11 +31,18 @@ type IBMPowerVSClusterSpec struct {
 	ServiceInstanceID string `json:"serviceInstanceID"`
 
 	// Network is the reference to the Network to use for this cluster.
-	// when the field is omitted, A DHCP service will be created in the Power VS server workspace and its private network will be used.
+	// when the field is omitted, A DHCP service will be created in the Power VS workspace and its private network will be used.
+	// the DHCP service created network will have the following name format
+	// 1. in the case of DHCPServer.Name is not set the name will be DHCPSERVER<CLUSTER_NAME>_Private.
+	// 2. if DHCPServer.Name is set the name will be DHCPSERVER<DHCPServer.Name>_Private.
+	// when Network.ID is set, its expected that there exist a network in PowerVS workspace with id or else system will give error.
+	// when Network.Name is set, system will first check for network with Name in PowerVS workspace, if not exist network will be created by DHCP service.
+	// Network.RegEx is not yet supported and system will ignore the value.
 	Network IBMPowerVSResourceReference `json:"network"`
 
-	// DHCPServer is contains the configuration to be used while creating a new DHCP server in PowerVS workspace.
-	// when the field is omitted, a default name is constructed and DHCP server will be created.
+	// dhcpServer is contains the configuration to be used while creating a new DHCP server in PowerVS workspace.
+	// when the field is omitted, CLUSTER_NAME will be used as DHCPServer.Name and DHCP server will be created.
+	// it will automatically create network with name DHCPSERVER<DHCPServer.Name>_Private in PowerVS workspace.
 	// +optional
 	DHCPServer *DHCPServer `json:"dhcpServer,omitempty"`
 
@@ -49,46 +56,88 @@ type IBMPowerVSClusterSpec struct {
 	// supported serviceInstance identifier in PowerVSResource are Name and ID and that can be obtained from IBM Cloud UI or IBM Cloud cli.
 	// More detail about Power VS service instance.
 	// https://cloud.ibm.com/docs/power-iaas?topic=power-iaas-creating-power-virtual-server
-	// when omitted system will dynamically create the service instance
+	// when omitted system will dynamically create the service instance with name CLUSTER_NAME-serviceInstance.
+	// when ServiceInstance.ID is set, its expected that there exist a service instance in PowerVS workspace with id or else system will give error.
+	// when ServiceInstance.Name is set, system will first check for service instance with Name in PowerVS workspace, if not exist system will create new instance.
+	// ServiceInstance.Regex is not yet supported not yet supported and system will ignore the value.
 	// +optional
 	ServiceInstance *IBMPowerVSResourceReference `json:"serviceInstance,omitempty"`
 
 	// zone is the name of Power VS zone where the cluster will be created
 	// possible values can be found here https://cloud.ibm.com/docs/power-iaas?topic=power-iaas-creating-power-virtual-server.
+	// when powervs.cluster.x-k8s.io/create-infra=true annotation is set on IBMPowerVSCluster resource,
+	// 1. it is expected to set the zone, not setting will result in webhook error.
+	// 2. the zone should have PER capabilities, or else system will give error.
 	// +optional
 	Zone *string `json:"zone,omitempty"`
 
 	// resourceGroup name under which the resources will be created.
-	// when omitted default resource group of the account will be used.
+	// when powervs.cluster.x-k8s.io/create-infra=true annotation is set on IBMPowerVSCluster resource,
+	// 1. it is expected to set the ResourceGroup.Name, not setting will result in webhook error.
+	// ServiceInstance.ID and ServiceInstance.Regex is not yet supported and system will ignore the value.
 	// +optional
 	ResourceGroup *IBMPowerVSResourceReference `json:"resourceGroup,omitempty"`
 
 	// vpc contains information about IBM Cloud VPC resources.
+	// when omitted system will dynamically create the VPC with name CLUSTER_NAME-vpc.
+	// when VPC.ID is set, its expected that there exist a VPC with ID or else system will give error.
+	// when VPC.Name is set, system will first check for VPC with Name, if not exist system will create new VPC.
+	// when powervs.cluster.x-k8s.io/create-infra=true annotation is set on IBMPowerVSCluster resource,
+	// 1. it is expected to set the VPC.Region, not setting will result in webhook error.
 	// +optional
 	VPC *VPCResourceReference `json:"vpc,omitempty"`
 
 	// vpcSubnets contains information about IBM Cloud VPC Subnet resources.
+	// when omitted system will create the subnets in all the zone corresponding to VPC.Region, with name CLUSTER_NAME-vpcsubnet-ZONE_NAME.
+	// possible values can be found here https://cloud.ibm.com/docs/power-iaas?topic=power-iaas-creating-power-virtual-server.
+	// when VPCSubnets[].ID is set, its expected that there exist a subnet with ID or else system will give error.
+	// when VPCSubnets[].Zone is not set, a random zone is picked from available zones of VPC.Region.
+	// when VPCSubnets[].Name is not set, system will set name as CLUSTER_NAME-vpcsubnet-INDEX.
+	// if subnet with name VPCSubnets[].Name not found, system will create new subnet in VPCSubnets[].Zone.
 	// +optional
 	VPCSubnets []Subnet `json:"vpcSubnets,omitempty"`
 
 	// transitGateway contains information about IBM Cloud TransitGateway
 	// IBM Cloud TransitGateway helps in establishing network connectivity between IBM Cloud Power VS and VPC infrastructure
 	// more information about TransitGateway can be found here https://www.ibm.com/products/transit-gateway.
+	// when TransitGateway.ID is set, its expected that there exist a TransitGateway with ID or else system will give error.
+	// when TransitGateway.Name is set, system will first check for TransitGateway with Name, if not exist system will create new TransitGateway.
 	// +optional
 	TransitGateway *TransitGateway `json:"transitGateway,omitempty"`
 
-	// loadBalancers is optional configuration for configuring loadbalancers to control plane or data plane nodes
+	// loadBalancers is optional configuration for configuring loadbalancers to control plane or data plane nodes.
+	// when omitted system will create a public loadbalancer with name CLUSTER_NAME-loadbalancer.
 	// when specified a vpc loadbalancer will be created and controlPlaneEndpoint will be set with associated hostname of loadbalancer.
-	// when omitted user is expected to set controlPlaneEndpoint.
+	// ControlPlaneEndpoint will be set with associated hostname of public loadbalancer.
+	// when LoadBalancers[].ID is set, its expected that there exist a loadbalancer with ID or else system will give error.
+	// when LoadBalancers[].Name is set, system will first check for loadbalancer with Name, if not exist system will create new loadbalancer.
 	// +optional
 	LoadBalancers []VPCLoadBalancerSpec `json:"loadBalancers,omitempty"`
 
 	// cosInstance contains options to configure a supporting IBM Cloud COS bucket for this
 	// cluster - currently used for nodes requiring Ignition
 	// (https://coreos.github.io/ignition/) for bootstrapping (requires
 	// BootstrapFormatIgnition feature flag to be enabled).
+	// when powervs.cluster.x-k8s.io/create-infra=true annotation is set on IBMPowerVSCluster resource and Ignition is set, then
+	// 1. CosInstance.Name should be set not setting will result in webhook error.
+	// 2. CosInstance.BucketName should be set not setting will result in webhook error.
+	// 3. CosInstance.BucketRegion should be set not setting will result in webhook error.
 	// +optional
 	CosInstance *CosInstance `json:"cosInstance,omitempty"`
+
+	// Ignition defined options related to the bootstrapping systems where Ignition is used.
+	// +optional
+	Ignition *Ignition `json:"ignition,omitempty"`
+}
+
+// Ignition defines options related to the bootstrapping systems where Ignition is used.
+type Ignition struct {
+	// Version defines which version of Ignition will be used to generate bootstrap data.
+	//
+	// +optional
+	// +kubebuilder:default="2.3"
+	// +kubebuilder:validation:Enum="2.3";"2.4";"3.0";"3.1";"3.2";"3.3";"3.4"
+	Version string `json:"version,omitempty"`
 }
 
 // IBMPowerVSClusterStatus defines the observed state of IBMPowerVSCluster.