Merge pull request #90216 from jeana-redhat/OSDOCS-10635-cluster-api-openstack-docs-4.15

jeana-redhat · web-flow · commit 62a587d0a0b7 · 2025-03-13T14:21:41.000-04:00
[enterprise-4.15] OSDOCS-10635: Docs for Cluster API Provider OpenStack pre-4.18
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -2356,6 +2356,8 @@ Topics:
       File: cluster-api-config-options-aws
     - Name: Cluster API configuration options for Google Cloud Platform
       File: cluster-api-config-options-gcp
+    - Name: Cluster API configuration options for Red Hat OpenStack Platform
+      File: cluster-api-config-options-rhosp
 #  - Name: Cluster API resiliency and recovery
 #    File: cluster-api-resiliency
   - Name: Troubleshooting Cluster API clusters
diff --git a/machine_management/cluster_api_machine_management/cluster-api-about.adoc b/machine_management/cluster_api_machine_management/cluster-api-about.adoc
@@ -9,7 +9,7 @@ toc::[]
 :FeatureName: Managing machines with the Cluster API
 include::snippets/technology-preview.adoc[]
 
-The link:https://cluster-api.sigs.k8s.io/[Cluster API] is an upstream project that is integrated into {product-title} as a Technology Preview for Amazon Web Services (AWS) and Google Cloud Platform (GCP).
+The link:https://cluster-api.sigs.k8s.io/[Cluster API] is an upstream project that is integrated into {product-title} as a Technology Preview for {aws-first}, {gcp-first}, and {rh-openstack-first}.
 
 //Cluster API overview
 include::modules/capi-overview.adoc[leveloffset=+1]
diff --git a/machine_management/cluster_api_machine_management/cluster-api-configuration.adoc b/machine_management/cluster_api_machine_management/cluster-api-configuration.adoc
@@ -22,4 +22,6 @@ For provider-specific configuration options for your cluster, see the following
 
 * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-aws.adoc#cluster-api-config-options-aws[Cluster API configuration options for {aws-full}]
 
-* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-gcp.adoc#cluster-api-config-options-gcp[Cluster API configuration options for {gcp-full}]
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-gcp.adoc#cluster-api-config-options-gcp[Cluster API configuration options for {gcp-full}]
+
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-rhosp.adoc#cluster-api-config-options-rhosp[Cluster API configuration options for {rh-openstack}]
diff --git a/machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc b/machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc
@@ -33,17 +33,20 @@ include::modules/capi-creating-infrastructure-resource.adoc[leveloffset=+2]
 .Additional resources
 * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-aws.adoc#capi-yaml-infrastructure-aws_cluster-api-config-options-aws[Sample YAML for a Cluster API infrastructure resource on {aws-full}]
 * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-gcp.adoc#capi-yaml-infrastructure-gcp_cluster-api-config-options-gcp[Sample YAML for a Cluster API infrastructure resource on {gcp-full}]
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-rhosp.adoc#capi-yaml-infrastructure-rhosp_cluster-api-config-options-rhosp[Sample YAML for a Cluster API infrastructure resource on {rh-openstack}]
 
 //Creating a Cluster API machine template
 include::modules/capi-creating-machine-template.adoc[leveloffset=+2]
 [role="_additional-resources"]
 .Additional resources
 * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-aws.adoc#capi-yaml-machine-template-aws_cluster-api-config-options-aws[Sample YAML for a Cluster API machine template resource on {aws-full}]
 * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-gcp.adoc#capi-yaml-machine-template-gcp_cluster-api-config-options-gcp[Sample YAML for a Cluster API machine template resource on {gcp-full}]
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-rhosp.adoc#capi-yaml-machine-template-rhosp_cluster-api-config-options-rhosp[Sample YAML for a Cluster API machine template resource on {rh-openstack}]
 
 //Creating a Cluster API compute machine set
 include::modules/capi-creating-machine-set.adoc[leveloffset=+2]
 [role="_additional-resources"]
 .Additional resources
 * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-aws.adoc#capi-yaml-machine-set-aws_cluster-api-config-options-aws[Sample YAML for a Cluster API compute machine set resource on {aws-full}]
-* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-gcp.adoc#capi-yaml-machine-set-gcp_cluster-api-config-options-gcp[Sample YAML for a Cluster API compute machine set resource on {gcp-full}]
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-gcp.adoc#capi-yaml-machine-set-gcp_cluster-api-config-options-gcp[Sample YAML for a Cluster API compute machine set resource on {gcp-full}]
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-rhosp.adoc#capi-yaml-machine-set-rhosp_cluster-api-config-options-rhosp[Sample YAML for a Cluster API compute machine set resource on {rh-openstack}]
diff --git a/machine_management/cluster_api_machine_management/cluster-api-managing-machines.adoc b/machine_management/cluster_api_machine_management/cluster-api-managing-machines.adoc
@@ -15,6 +15,7 @@ include::modules/capi-modifying-machine-template.adoc[leveloffset=+1]
 .Additional resources
 * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-aws.adoc#capi-yaml-machine-template-aws_cluster-api-config-options-aws[Sample YAML for a Cluster API machine template resource on {aws-full}]
 * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-gcp.adoc#capi-yaml-machine-template-gcp_cluster-api-config-options-gcp[Sample YAML for a Cluster API machine template resource on {gcp-full}]
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-rhosp.adoc#capi-yaml-machine-template-rhosp_cluster-api-config-options-rhosp[Sample YAML for a Cluster API machine template resource on {rh-openstack}]
 * xref:../../machine_management/cluster_api_machine_management/cluster-api-managing-machines.adoc#machineset-modifying_cluster-api-managing-machines[Modifying a compute machine set by using the CLI]
 
 //Modifying a compute machine set by using the CLI
@@ -23,4 +24,5 @@ include::modules/machineset-modifying.adoc[leveloffset=+1,tag=!MAPI]
 [role="_additional-resources"]
 .Additional resources
 * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-aws.adoc#capi-yaml-machine-set-aws_cluster-api-config-options-aws[Sample YAML for a Cluster API compute machine set resource on {aws-full}]
-* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-gcp.adoc#capi-yaml-machine-set-gcp_cluster-api-config-options-gcp[Sample YAML for a Cluster API compute machine set resource on {gcp-full}]
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-gcp.adoc#capi-yaml-machine-set-gcp_cluster-api-config-options-gcp[Sample YAML for a Cluster API compute machine set resource on {gcp-full}]
+* xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-rhosp.adoc#capi-yaml-machine-set-rhosp_cluster-api-config-options-rhosp[Sample YAML for a Cluster API compute machine set resource on {rh-openstack}]
diff --git a/machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-rhosp.adoc b/machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-rhosp.adoc
@@ -0,0 +1,33 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cluster-api-config-options-rhosp"]
+= Cluster API configuration options for Red{nbsp}Hat OpenStack Platform
+include::_attributes/common-attributes.adoc[]
+:context: cluster-api-config-options-rhosp
+
+toc::[]
+
+:FeatureName: Managing machines with the Cluster API
+include::snippets/technology-preview.adoc[]
+
+You can change the configuration of your {rh-openstack-first} Cluster API machines by updating values in the Cluster API custom resource manifests.
+
+[id="cluster-api-sample-yaml-rhosp_{context}"]
+== Sample YAML for configuring {rh-openstack} clusters
+
+The following example YAML files show configurations for a {rh-openstack} cluster.
+
+//Sample YAML for a CAPI RHOSP infrastructure resource
+include::modules/capi-yaml-infrastructure-rhosp.adoc[leveloffset=+2]
+
+//Sample YAML for CAPI RHOSP machine template resource
+include::modules/capi-yaml-machine-template-rhosp.adoc[leveloffset=+2]
+
+//Sample YAML for a CAPI RHOSP compute machine set resource
+include::modules/capi-yaml-machine-set-rhosp.adoc[leveloffset=+2]
+
+// [id="cluster-api-supported-features-rhosp_{context}"]
+// == Enabling {rh-openstack} features with the Cluster API
+
+// You can enable the following features by updating values in the Cluster API custom resource manifests.
+
+//Not sure what, if anything, we can add here at this time.
diff --git a/modules/capi-arch-resources.adoc b/modules/capi-arch-resources.adoc
@@ -10,7 +10,7 @@ The Cluster API consists of the following primary resources. For the Technology
 
 Cluster:: A fundamental unit that represents a cluster that is managed by the Cluster API.
 
-Infrastructure:: A provider-specific resource that defines properties that are shared by all the compute machine sets in the cluster, such as the region and subnets.
+Infrastructure cluster:: A provider-specific resource that defines properties that are shared by all the compute machine sets in the cluster, such as the region and subnets.
 
 Machine template:: A provider-specific template that defines the properties of the machines that a compute machine set creates.
 
diff --git a/modules/capi-creating-cluster-resource.adoc b/modules/capi-creating-cluster-resource.adoc
@@ -45,6 +45,19 @@ The following values are valid:
 +
 * `AWSCluster`: The cluster is running on {aws-first}.
 * `GCPCluster`: The cluster is running on {gcp-first}.
+|====
+|Cluster cloud provider |Value
+
+|{aws-first}
+|`AWSCluster`
+
+|{gcp-first}
+|`GCPCluster`
+
+|{rh-openstack-first}
+|`OpenStackCluster`
+
+|====
 --
 
 . Create the cluster CR by running the following command:
diff --git a/modules/capi-creating-infrastructure-resource.adoc b/modules/capi-creating-infrastructure-resource.adoc
@@ -39,13 +39,24 @@ spec: # <4>
 <1> The `apiVersion` varies by platform.
 For more information, see the sample Cluster API infrastructure resource YAML for your provider.
 The following values are valid:
-* `infrastructure.cluster.x-k8s.io/v1beta1`: The version that {gcp-first} clusters use.
-* `infrastructure.cluster.x-k8s.io/v1beta1`: The version that {aws-first} clusters use.
+* `infrastructure.cluster.x-k8s.io/v1beta1`: The version that {aws-first}, {gcp-first}, and {rh-openstack-first} clusters use.
 <2> Specify the infrastructure kind for the cluster.
 This value must match the value for your platform.
 The following values are valid:
-* `AWSCluster`: The cluster is running on {aws-short}.
-* `GCPCluster`: The cluster is running on {gcp-short}.
++
+|====
+|Cluster cloud provider |Value
+
+|{aws-first}
+|`AWSCluster`
+
+|{gcp-first}
+|`GCPCluster`
+
+|{rh-openstack-first}
+|`OpenStackCluster`
+
+|====
 <3> Specify the name of the cluster.
 <4> Specify the details for your environment.
 These parameters are provider specific.
diff --git a/modules/capi-creating-machine-template.adoc b/modules/capi-creating-machine-template.adoc
@@ -36,9 +36,23 @@ spec:
   template:
     spec: # <3>
 ----
-<1> Specify the machine template kind. This value must match the value for your platform. The following values are valid:
-* `AWSMachineTemplate`: The cluster is running on {aws-first}.
-* `GCPMachineTemplate`: The cluster is running on {gcp-first}.
+<1> Specify the machine template kind. 
+This value must match the value for your platform.
+The following values are valid:
++
+|====
+|Cluster cloud provider |Value
+
+|{aws-first}
+|`AWSMachineTemplate`
+
+|{gcp-first}
+|`GCPMachineTemplate`
+
+|{rh-openstack-first}
+|`OpenStackMachineTemplate`
+
+|====
 <2> Specify a name for the machine template.
 <3> Specify the details for your environment. These parameters are provider specific. For more information, see the sample Cluster API machine template YAML for your provider.
 --
diff --git a/modules/capi-limitations.adoc b/modules/capi-limitations.adoc
@@ -15,7 +15,7 @@ Using the Cluster API to manage machines is a Technology Preview feature and has
 Enabling this feature set cannot be undone and prevents minor version updates.
 ====
 
-* Only {aws-short} and {gcp-short} clusters can use the Cluster API.
+* Only {aws-short}, {gcp-first}, and {rh-openstack-first} clusters can use the Cluster API.
 
 * You must manually create the primary resources that the Cluster API requires.
 For more information, see "Getting started with the Cluster API".
diff --git a/modules/capi-modifying-machine-template.adoc b/modules/capi-modifying-machine-template.adoc
@@ -26,8 +26,20 @@ You can update the machine template resource for your cluster by modifying the Y
 $ oc get <machine_template_kind> <1>
 ----
 <1> Specify the value that corresponds to your platform. The following values are valid:
-* `AWSMachineTemplate`: The cluster is running on {aws-first}.
-* `GCPMachineTemplate`: The cluster is running on {gcp-first}.
++
+|====
+|Cluster cloud provider |Value
+
+|{aws-first}
+|`AWSMachineTemplate`
+
+|{gcp-first}
+|`GCPMachineTemplate`
+
+|{rh-openstack-first}
+|`OpenStackMachineTemplate`
+
+|====
 --
 +
 .Example output
diff --git a/modules/capi-yaml-cluster.adoc b/modules/capi-yaml-cluster.adoc
@@ -23,9 +23,19 @@ spec:
     namespace: openshift-cluster-api
 ----
 <1> Specify the name of the cluster.
-<2> Specify the infrastructure kind for the cluster. Valid values are:
+<2> Specify the infrastructure kind for the cluster.
+The following values are valid:
 +
---
-* `AWSCluster`: The cluster is running on Amazon Web Services (AWS).
-* `GCPCluster`: The cluster is running on Google Cloud Platform (GCP).
---
+|====
+|Cluster cloud provider |Value
+
+|{aws-full}
+|`AWSCluster`
+
+|{gcp-short}
+|`GCPCluster`
+
+|{rh-openstack}
+|`OpenStackCluster`
+
+|====
diff --git a/modules/capi-yaml-infrastructure-rhosp.adoc b/modules/capi-yaml-infrastructure-rhosp.adoc
@@ -0,0 +1,59 @@
+// Module included in the following assemblies:
+//
+// * machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-rhosp.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="capi-yaml-infrastructure-rhosp_{context}"]
+= Sample YAML for a Cluster API infrastructure cluster resource on {rh-openstack}
+
+The infrastructure cluster resource is provider-specific and defines properties that are shared by all the compute machine sets in the cluster, such as the region and subnets.
+The compute machine set references this resource when creating machines.
+
+[IMPORTANT]
+====
+Only the parameters in the following example are validated to be compatible with {product-title}.
+Other parameters, such as those documented in the upstream link:https://cluster-api-openstack.sigs.k8s.io/clusteropenstack/configuration#optional-configuration[{cap-openstack-first}] book, might cause undesired behavior.
+====
+
+[source,yaml]
+----
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+kind: OpenStackCluster # <1>
+metadata:
+  name: <cluster_name> # <2>
+  namespace: openshift-cluster-api
+  labels:
+    cluster.x-k8s.io/cluster-name: <cluster_name>
+spec:
+  controlPlaneEndpoint: <control_plane_endpoint_address> # <3>
+  disableAPIServerFloatingIP: true
+  tags:
+    - openshiftClusterID=<cluster_name>
+  network:
+    id: <api_service_network_id> # <4>
+  externalNetwork:
+    id: <floating_network_id> # <5>
+  identityRef:
+    cloudName: openstack
+    name: openstack-cloud-credentials
+----
+<1> Specify the infrastructure kind for the cluster.
+This value must match the value for your platform.
+<2> Specify the cluster ID as the name of the cluster.
+<3> Specify the IP address of the control plane endpoint and the port used to access it.
+<4> Specify the UUID of the default network to use for machines that do not specify ports.
++
+[NOTE]
+====
+This feature might be removed in a future release.
+To prevent issues due to the removal of this feature, specify at least one port in the machine specification instead of relying solely on this feature.
+====
+
+<5> Specify the UUID of an external network.
+You can specify the network used to assign external floating IP addresses or the network used for egress for this field.
++
+[NOTE]
+====
+The infrastructure cluster resource requires this field but does not currently use this value.
+This requirement is planned to be removed in a future release.
+====
diff --git a/modules/capi-yaml-machine-set-rhosp.adoc b/modules/capi-yaml-machine-set-rhosp.adoc
@@ -0,0 +1,51 @@
+// Module included in the following assemblies:
+//
+// * machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-rhosp.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="capi-yaml-machine-set-rhosp_{context}"]
+= Sample YAML for a Cluster API compute machine set resource on {rh-openstack}
+
+The compute machine set resource defines additional properties of the machines that it creates.
+The compute machine set also references the infrastructure resource and machine template when creating machines.
+
+[source,yaml]
+----
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: MachineSet
+metadata:
+  name: <machine_set_name> # <1>
+  namespace: openshift-cluster-api
+spec:
+  clusterName: <cluster_name> # <2>
+  replicas: 1
+  selector:
+    matchLabels:
+      test: example
+      cluster.x-k8s.io/cluster-name: <cluster_name>
+      cluster.x-k8s.io/set-name: <machine_set_name>
+  template:
+    metadata:
+      labels:
+        test: example
+        cluster.x-k8s.io/cluster-name: <cluster_name>
+        cluster.x-k8s.io/set-name: <machine_set_name>
+        node-role.kubernetes.io/<role>: ""
+    spec:
+      bootstrap:
+         dataSecretName: worker-user-data # <3>
+      clusterName: <cluster_name>
+      infrastructureRef:
+        apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+        kind: OpenStackMachineTemplate # <4>
+        name: <template_name> # <5>
+      failureDomain: <nova_availability_zone> # <6>
+----
+<1> Specify a name for the compute machine set.
+<2> Specify the cluster ID as the name of the cluster.
+<3> For the Cluster API Technology Preview, the Operator can use the worker user data secret from the `openshift-machine-api` namespace.
+<4> Specify the machine template kind.
+This value must match the value for your platform.
+<5> Specify the machine template name.
+<6> Optional: Specify the name of the Nova availability zone for the machine set to create machines in.
+If you do not specify a value, machines are not restricted to a specific availability zone.
diff --git a/modules/capi-yaml-machine-template-rhosp.adoc b/modules/capi-yaml-machine-template-rhosp.adoc
@@ -0,0 +1,34 @@
+// Module included in the following assemblies:
+//
+// * machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-rhosp.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="capi-yaml-machine-template-rhosp_{context}"]
+= Sample YAML for a Cluster API machine template resource on {rh-openstack}
+
+The machine template resource is provider-specific and defines the basic properties of the machines that a compute machine set creates.
+The compute machine set references this template when creating machines.
+
+[source,yaml]
+----
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+kind: OpenStackMachineTemplate # <1>
+metadata:
+  name: <template_name> # <2>
+  namespace: openshift-cluster-api
+spec:
+  template:
+    spec: # <3>
+      flavor: <openstack_node_machine_flavor> # <4>
+      image:
+        filter:
+          name: <openstack_image> # <5>
+----
+<1> Specify the machine template kind.
+This value must match the value for your platform.
+<2> Specify a name for the machine template.
+<3> Specify the details for your environment.
+The values here are examples.
+<4> Specify the {rh-openstack} flavor to use.
+For more information, see link:https://docs.redhat.com/en/documentation/red_hat_openstack_platform/17.1/html/configuring_the_compute_service_for_instance_creation/assembly_creating-flavors-for-launching-instances_instance-flavors[Creating flavors for launching instances].
+<5> Specify the image to use.
diff --git a/modules/cluster-capi-operator.adoc b/modules/cluster-capi-operator.adoc
