OpenStackCluster: improve doctext

Author: mdbooth

api/v1beta1/openstackcluster_types.go

@@ -152,7 +152,7 @@ type OpenStackClusterSpec struct {
 	// +optional
 	DisablePortSecurity optional.Bool `json:"disablePortSecurity,omitempty"`
 
-	// Tags for all resources in cluster
+	// Tags to set on all resources in cluster which support tags
 	// +listType=set
 	// +optional
 	Tags []string `json:"tags,omitempty"`
@@ -161,7 +161,8 @@ type OpenStackClusterSpec struct {
 	// +optional
 	ControlPlaneEndpoint clusterv1.APIEndpoint `json:"controlPlaneEndpoint"`
 
-	// ControlPlaneAvailabilityZones is the az to deploy control plane to
+	// ControlPlaneAvailabilityZones is the set of availability zones which
+	// control plane machines may be deployed to.
 	// +listType=set
 	// +optional
 	ControlPlaneAvailabilityZones []string `json:"controlPlaneAvailabilityZones,omitempty"`
@@ -198,7 +199,7 @@ type OpenStackClusterStatus struct {
 	// +optional
 	Network *NetworkStatusWithSubnets `json:"network,omitempty"`
 
-	// externalNetwork contains information about the external network used for default ingress and egress traffic.
+	// ExternalNetwork contains information about the external network used for default ingress and egress traffic.
 	// +optional
 	ExternalNetwork *NetworkStatus `json:"externalNetwork,omitempty"`
 
@@ -213,20 +214,23 @@ type OpenStackClusterStatus struct {
 	// FailureDomains represent OpenStack availability zones
 	FailureDomains clusterv1.FailureDomains `json:"failureDomains,omitempty"`
 
-	// ControlPlaneSecurityGroups contains all the information about the OpenStack
-	// Security Group that needs to be applied to control plane nodes.
-	// TODO: Maybe instead of two properties, we add a property to the group?
+	// ControlPlaneSecurityGroup contains the information about the
+	// OpenStack Security Group that needs to be applied to control plane
+	// nodes.
 	// +optional
 	ControlPlaneSecurityGroup *SecurityGroupStatus `json:"controlPlaneSecurityGroup,omitempty"`
 
-	// WorkerSecurityGroup contains all the information about the OpenStack Security
-	// Group that needs to be applied to worker nodes.
+	// WorkerSecurityGroup contains the information about the OpenStack
+	// Security Group that needs to be applied to worker nodes.
 	// +optional
 	WorkerSecurityGroup *SecurityGroupStatus `json:"workerSecurityGroup,omitempty"`
 
+	// BastionSecurityGroup contains the information about the OpenStack
+	// Security Group that needs to be applied to worker nodes.
 	// +optional
 	BastionSecurityGroup *SecurityGroupStatus `json:"bastionSecurityGroup,omitempty"`
 
+	// Bastion contains the information about the deployed bastion host
 	// +optional
 	Bastion *BastionStatus `json:"bastion,omitempty"`
 

config/crd/bases/infrastructure.cluster.x-k8s.io_openstackclusters.yaml

@@ -5529,8 +5529,9 @@ spec:
                     type: object
                 type: object
               controlPlaneAvailabilityZones:
-                description: ControlPlaneAvailabilityZones is the az to deploy control
-                  plane to
+                description: |-
+                  ControlPlaneAvailabilityZones is the set of availability zones which
+                  control plane machines may be deployed to.
                 items:
                   type: string
                 type: array
@@ -6137,7 +6138,8 @@ spec:
                 type: array
                 x-kubernetes-list-type: atomic
               tags:
-                description: Tags for all resources in cluster
+                description: Tags to set on all resources in cluster which support
+                  tags
                 items:
                   type: string
                 type: array
@@ -6175,6 +6177,8 @@ spec:
                 - name
                 type: object
               bastion:
+                description: Bastion contains the information about the deployed bastion
+                  host
                 properties:
                   dependentResources:
                     properties:
@@ -6588,8 +6592,8 @@ spec:
                 type: object
               bastionSecurityGroup:
                 description: |-
-                  SecurityGroupStatus represents the basic information of the associated
-                  OpenStack Neutron Security Group.
+                  BastionSecurityGroup contains the information about the OpenStack
+                  Security Group that needs to be applied to worker nodes.
                 properties:
                   id:
                     description: id of the security group
@@ -6655,9 +6659,9 @@ spec:
                 type: object
               controlPlaneSecurityGroup:
                 description: |-
-                  ControlPlaneSecurityGroups contains all the information about the OpenStack
-                  Security Group that needs to be applied to control plane nodes.
-                  TODO: Maybe instead of two properties, we add a property to the group?
+                  ControlPlaneSecurityGroup contains the information about the
+                  OpenStack Security Group that needs to be applied to control plane
+                  nodes.
                 properties:
                   id:
                     description: id of the security group
@@ -6722,7 +6726,7 @@ spec:
                 - name
                 type: object
               externalNetwork:
-                description: externalNetwork contains information about the external
+                description: ExternalNetwork contains information about the external
                   network used for default ingress and egress traffic.
                 properties:
                   id:
@@ -6863,8 +6867,8 @@ spec:
                 type: object
               workerSecurityGroup:
                 description: |-
-                  WorkerSecurityGroup contains all the information about the OpenStack Security
-                  Group that needs to be applied to worker nodes.
+                  WorkerSecurityGroup contains the information about the OpenStack
+                  Security Group that needs to be applied to worker nodes.
                 properties:
                   id:
                     description: id of the security group

config/crd/bases/infrastructure.cluster.x-k8s.io_openstackclustertemplates.yaml

@@ -2961,8 +2961,9 @@ spec:
                             type: object
                         type: object
                       controlPlaneAvailabilityZones:
-                        description: ControlPlaneAvailabilityZones is the az to deploy
-                          control plane to
+                        description: |-
+                          ControlPlaneAvailabilityZones is the set of availability zones which
+                          control plane machines may be deployed to.
                         items:
                           type: string
                         type: array
@@ -3571,7 +3572,8 @@ spec:
                         type: array
                         x-kubernetes-list-type: atomic
                       tags:
-                        description: Tags for all resources in cluster
+                        description: Tags to set on all resources in cluster which
+                          support tags
                         items:
                           type: string
                         type: array

docs/book/src/api/v1beta1/api.md

@@ -324,7 +324,7 @@ Kubernetes cluster, which also disables SecurityGroups</p>
 </td>
 <td>
 <em>(Optional)</em>
-<p>Tags for all resources in cluster</p>
+<p>Tags to set on all resources in cluster which support tags</p>
 </td>
 </tr>
 <tr>
@@ -350,7 +350,8 @@ sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
 </td>
 <td>
 <em>(Optional)</em>
-<p>ControlPlaneAvailabilityZones is the az to deploy control plane to</p>
+<p>ControlPlaneAvailabilityZones is the set of availability zones which
+control plane machines may be deployed to.</p>
 </td>
 </tr>
 <tr>
@@ -2218,7 +2219,7 @@ Kubernetes cluster, which also disables SecurityGroups</p>
 </td>
 <td>
 <em>(Optional)</em>
-<p>Tags for all resources in cluster</p>
+<p>Tags to set on all resources in cluster which support tags</p>
 </td>
 </tr>
 <tr>
@@ -2244,7 +2245,8 @@ sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
 </td>
 <td>
 <em>(Optional)</em>
-<p>ControlPlaneAvailabilityZones is the az to deploy control plane to</p>
+<p>ControlPlaneAvailabilityZones is the set of availability zones which
+control plane machines may be deployed to.</p>
 </td>
 </tr>
 <tr>
@@ -2349,7 +2351,7 @@ NetworkStatus
 </td>
 <td>
 <em>(Optional)</em>
-<p>externalNetwork contains information about the external network used for default ingress and egress traffic.</p>
+<p>ExternalNetwork contains information about the external network used for default ingress and egress traffic.</p>
 </td>
 </tr>
 <tr>
@@ -2404,9 +2406,9 @@ SecurityGroupStatus
 </td>
 <td>
 <em>(Optional)</em>
-<p>ControlPlaneSecurityGroups contains all the information about the OpenStack
-Security Group that needs to be applied to control plane nodes.
-TODO: Maybe instead of two properties, we add a property to the group?</p>
+<p>ControlPlaneSecurityGroup contains the information about the
+OpenStack Security Group that needs to be applied to control plane
+nodes.</p>
 </td>
 </tr>
 <tr>
@@ -2420,8 +2422,8 @@ SecurityGroupStatus
 </td>
 <td>
 <em>(Optional)</em>
-<p>WorkerSecurityGroup contains all the information about the OpenStack Security
-Group that needs to be applied to worker nodes.</p>
+<p>WorkerSecurityGroup contains the information about the OpenStack
+Security Group that needs to be applied to worker nodes.</p>
 </td>
 </tr>
 <tr>
@@ -2435,6 +2437,8 @@ SecurityGroupStatus
 </td>
 <td>
 <em>(Optional)</em>
+<p>BastionSecurityGroup contains the information about the OpenStack
+Security Group that needs to be applied to worker nodes.</p>
 </td>
 </tr>
 <tr>
@@ -2448,6 +2452,7 @@ BastionStatus
 </td>
 <td>
 <em>(Optional)</em>
+<p>Bastion contains the information about the deployed bastion host</p>
 </td>
 </tr>
 <tr>
@@ -2791,7 +2796,7 @@ Kubernetes cluster, which also disables SecurityGroups</p>
 </td>
 <td>
 <em>(Optional)</em>
-<p>Tags for all resources in cluster</p>
+<p>Tags to set on all resources in cluster which support tags</p>
 </td>
 </tr>
 <tr>
@@ -2817,7 +2822,8 @@ sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
 </td>
 <td>
 <em>(Optional)</em>
-<p>ControlPlaneAvailabilityZones is the az to deploy control plane to</p>
+<p>ControlPlaneAvailabilityZones is the set of availability zones which
+control plane machines may be deployed to.</p>
 </td>
 </tr>
 <tr>