Merge pull request #93726 from maxwelldb/hypershiftstack-osdocs14600

[OSDOCS-14600] HCP for Openstack

Author: maxwelldb

_topic_maps/_topic_map.yml

@@ -2492,6 +2492,8 @@ Topics:
     File: hcp-deploy-ibmz
   - Name: Deploying hosted control planes on IBM Power
     File: hcp-deploy-ibm-power
+  - Name: Deploying hosted control planes on OpenStack
+    File: hcp-deploy-openstack
 - Name: Managing hosted control planes
   Dir: hcp-manage
   Topics:
@@ -2505,6 +2507,8 @@ Topics:
     File: hcp-manage-non-bm
   - Name: Managing hosted control planes on IBM Power
     File: hcp-manage-ibm-power
+  - Name: Managing hosted control planes on OpenStack
+    File: hcp-manage-openstack
 - Name: Deploying hosted control planes in a disconnected environment
   Dir: hcp-disconnected
   Topics:
@@ -2562,6 +2566,8 @@ Topics:
     File: hcp-destroy-ibmz
   - Name: Destroying a hosted cluster on IBM Power
     File: hcp-destroy-ibm-power
+  - Name: Destroying a hosted cluster on OpenStack
+    File: hcp-destroy-openstack
   - Name: Destroying a hosted cluster on non-bare-metal agent machines
     File: hcp-destroy-non-bm
 - Name: Manually importing a hosted cluster

hosted_control_planes/hcp-deploy/hcp-deploy-openstack.adoc

@@ -0,0 +1,26 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="hcp-deploy-openstack"]
+include::_attributes/common-attributes.adoc[]
+= Deploying {hcp} on OpenStack
+:context: hcp-deploy-openstack
+
+toc::[]
+
+:FeatureName: Deploying {hcp} clusters on {rh-openstack-first}
+include::snippets/technology-preview.adoc[]
+
+You can deploy {hcp} with hosted clusters that run on {rh-openstack-first} 17.1.
+
+A _hosted cluster_ is an {product-title} cluster with its API endpoint and control plane that are hosted on a management cluster. With {hcp}, control planes exist as pods on a management cluster without the need for dedicated virtual or physical machines for each control plane.
+
+include::modules/hosted-clusters-openstack-prerequisites.adoc[leveloffset=+1]
+
+include::modules/hosted-clusters-openstack-prepare-etcd.adoc[leveloffset=+1]
+
+include::modules/hosted-clusters-openstack-create-floating-ip.adoc[leveloffset=+1]
+
+include::modules/hosted-clusters-openstack-upload-rhcos.adoc[leveloffset=+1]
+
+include::modules/hcp-deploy-openstack-create.adoc[leveloffset=+1]
+
+include::modules/hcp-deploy-openstack-parameters.adoc[leveloffset=+2]

hosted_control_planes/hcp-destroy/hcp-destroy-openstack.adoc

@@ -0,0 +1,9 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="hcp-destroy-openstack"]
+include::_attributes/common-attributes.adoc[]
+= Destroying a hosted control plane on OpenStack
+:context: hcp-destroy-openstack
+
+toc::[]
+
+include::modules/hosted-clusters-openstack-destroy.adoc[leveloffset=+1]

hosted_control_planes/hcp-manage/hcp-manage-openstack.adoc

@@ -0,0 +1,43 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="hcp-manage-openstack"]
+include::_attributes/common-attributes.adoc[]
+= Managing {hcp} on OpenStack
+:context: hcp-manage-openstack
+
+toc::[]
+
+After you deploy {hcp} on {rh-openstack-first} agent machines, you can manage a hosted cluster by completing the
+following tasks.
+
+include::modules/hcp-openstack-accessing.adoc[leveloffset=+1]
+
+include::modules/hcp-openstack-autoscale.adoc[leveloffset=+1]
+
+include::modules/hcp-manage-openstack-az.adoc[leveloffset=+1]
+
+[id="hosted-clusters-openstack-additional-ports"]
+== Configuring additional ports for node pools
+
+You can configure additional ports for node pools to support advanced networking scenarios, such as SR-IOV or multiple networks.
+
+include::modules/hosted-clusters-openstack-addl-ports-cases.adoc[leveloffset=+2]
+
+include::modules/hosted-clusters-openstack-addl-ports-options.adoc[leveloffset=+2]
+
+include::modules/hosted-clusters-openstack-addl-ports-creating.adoc[leveloffset=+2]
+
+[id="hosted-clusters-openstack-performance"]
+== Configuring additional ports for node pools
+
+You can tune hosted cluster node performance on {rh-openstack} for high-performance workloads, such as cloud-native network functions (CNFs). Performance tuning includes configuring {rh-openstack} resources, creating a performance profile, deploying a tuned `NodePool` resource, and enabling SR-IOV device support.
+
+CNFs are designed to run in cloud-native environments. They can provide network services such as routing, firewalling, and load balancing. You can configure the node pool to use high-performance computing and networking devices to run CNFs.
+
+include::modules/hosted-clusters-openstack-performance-tuning.adoc[leveloffset=+2]
+
+include::modules/hosted-clusters-openstack-performance-enabling.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../networking/networking_operators/sr-iov-operator/installing-sriov-operator.adoc#installing-sr-iov-operator_installing-sriov-operator[Installing the SR-IOV Network Operator]

modules/hcp-deploy-openstack-create.adoc

@@ -0,0 +1,84 @@
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-deploy-openstack-create_{context}"]
+= Creating a hosted cluster on OpenStack
+
+You can create a hosted cluster on {rh-openstack-first} by using the `hcp` CLI.
+
+.Prerequisites
+
+* You completed all prerequisite steps in "Preparing to deploy hosted control planes".
+* You reviewed "Prerequisites for OpenStack".
+* You completed all steps in "Preparing the management cluster for etcd local storage".
+* You have access to the management cluster.
+* You have access to the {rh-openstack} cloud.
+
+.Procedure
+
+* Create a hosted cluster by running the `hcp create` command. For example, for a cluster that takes advantage of the performant etcd configuration detailed in "Preparing the management cluster for etcd local storage", enter:
++
+[source,terminal]
+----
+$ hcp create cluster openstack \
+  --name my-hcp-cluster \
+  --openstack-node-flavor m1.xlarge \
+  --base-domain example.com \
+  --pull-secret /path/to/pull-secret.json \
+  --release-image quay.io/openshift-release-dev/ocp-release:4.19.0-x86_64 \
+  --node-pool-replicas 3 \
+  --etcd-storage-class lvms-etcd-class
+----
+
+NOTE: Many options are available at cluster creation. For {rh-openstack}-specific options, see "Options for creating a Hosted Control Planes cluster on OpenStack". For general options, see the `hcp` documentation.
+
+.Verification
+. Verify that the hosted cluster is ready by running the following command on it:
++
+[source,terminal]
+----
+$ oc -n clusters-<cluster_name> get pods
+----
++
+--
+where:
+
+`<cluster_name>`:: Specifies the name of the cluster.
+--
++
+After several minutes, the output should show that the hosted control plane pods are running.
++
+.Example output
+[source,terminal]
+----
+NAME                                                  READY   STATUS    RESTARTS   AGE
+capi-provider-5cc7b74f47-n5gkr                        1/1     Running   0          3m
+catalog-operator-5f799567b7-fd6jw                     2/2     Running   0          69s
+certified-operators-catalog-784b9899f9-mrp6p          1/1     Running   0          66s
+cluster-api-6bbc867966-l4dwl                          1/1     Running   0          66s
+...
+...
+...
+redhat-operators-catalog-9d5fd4d44-z8qqk              1/1     Running   0
+----
+
+. To validate the etcd configuration of the cluster:
+
+.. Validate the etcd persistent volume claim (PVC) by running the following command:
++
+[source,terminal]
+----
+$ oc get pvc -A
+----
+
+.. Inside the {hcp} etcd pod, confirm the mount path and device by running the following command:
++
+[source,terminal]
+----
+$ df -h /var/lib
+----
+
+[NOTE]
+====
+The {rh-openstack} resources that the cluster API (CAPI) provider creates are tagged with the label `openshiftClusterID=<infraID>`. 
+
+You can define additional tags for the resources as values in the `HostedCluster.Spec.Platform.OpenStack.Tags` field of a YAML manifest that you use to create the hosted cluster. The tags are applied when you scale up the node pool.
+====

modules/hcp-deploy-openstack-parameters.adoc

@@ -0,0 +1,58 @@
+// Module included in the following assemblies:
+//
+// * hosted-control-planes/hcp-deploy/hcp-deploy-openstack.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="hcp-deploy-openstack-parameters_{context}"]
+= Options for creating a Hosted Control Planes cluster on OpenStack
+
+You can supply several options to the `hcp` CLI while deploying a Hosted Control Planes Cluster on {rh-openstack-first}.
+
+|===
+|Option|Description|Required
+
+|`--openstack-ca-cert-file`
+|Path to the OpenStack CA certificate file. If not provided, this will be automatically extracted from the cloud entry in `clouds.yaml`.
+|No
+
+|`--openstack-cloud`
+|Name of the cloud entry in `clouds.yaml`. The default value is `openstack`.
+|No
+
+|`--openstack-credentials-file`
+a|Path to the OpenStack credentials file. If not provided, `hcp` will search the following directories:
+
+* The current working directory
+* `$HOME/.config/openstack`
+* `/etc/openstack`
+
+|No
+
+|`--openstack-dns-nameservers`
+|List of DNS server addresses that are provided when creating the subnet.
+|No
+
+|`--openstack-external-network-id`
+|ID of the OpenStack external network.
+|No
+
+|`--openstack-ingress-floating-ip`
+|A floating IP for OpenShift ingress.
+|No
+
+|`--openstack-node-additional-port`
+|Additional ports to attach to nodes. Valid values are: `network-id`, `vnic-type`, `disable-port-security`, and `address-pairs`.
+|No
+
+|`--openstack-node-availability-zone`
+|Availability zone for the node pool.
+|No
+
+|`--openstack-node-flavor`
+|Flavor for the node pool.
+|Yes
+
+|`--openstack-node-image-name`
+|Image name for the node pool.
+|No
+|===

modules/hcp-manage-openstack-az.adoc

@@ -0,0 +1,93 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-manage/hcp-manage-openstack.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-manage-openstack-az_{context}"]
+= Configuring node pools for availability zones
+
+You can distribute node pools across multiple {rh-openstack-first} Nova availability zones to improve the high availability of your hosted cluster.
+
+NOTE: Availability zones do not necessarily correspond to fault domains and do not inherently provide high availability benefits.
+
+.Prerequisites
+
+* You created a hosted cluster.
+* You have access to the management cluster.
+* The `hcp` and `oc` CLIs are installed.
+
+.Procedure
+
+. Set environment variables that are appropriate for your needs. For example, if you want to create two additional machines in the `az1` availability zone, you could enter:
++
+[source,terminal]
+----
+$ export NODEPOOL_NAME="${CLUSTER_NAME}-az1" \
+  && export WORKER_COUNT="2" \
+  && export FLAVOR="m1.xlarge" \
+  && export AZ="az1"
+----
+
+. Create the node pool by using your environment variables by entering the following command:
++
+[source,terminal]
+----
+$ hcp create nodepool openstack \
+  --cluster-name <cluster_name> \
+  --name $NODEPOOL_NAME \
+  --replicas $WORKER_COUNT \
+  --openstack-node-flavor $FLAVOR \
+  --openstack-node-availability-zone $AZ
+----
++
+--
+where:
+
+`<cluster_name>`:: Specifies the name of your hosted cluster.
+--
+
+. Check the status of the node pool by listing `nodepool` resources in the clusters namespace by running the following command:
++
+[source,terminal]
+----
+$ oc get nodepools --namespace clusters
+----
++
+.Example output
+[source,terminal]
+----
+NAME                      CLUSTER         DESIRED NODES   CURRENT NODES   AUTOSCALING   AUTOREPAIR   VERSION   UPDATINGVERSION   UPDATINGCONFIG   MESSAGE
+example                   example         5               5               False         False        4.17.0
+example-az1               example         2                               False         False                  True              True             Minimum availability requires 2 replicas, current 0 available
+----
+
+. Observe the notes as they start on your hosted cluster by running the following command:
++
+[source,terminal]
+----
+$ oc --kubeconfig $CLUSTER_NAME-kubeconfig get nodes
+----
++
+.Example output
+[source,terminal]
+----
+NAME                      STATUS   ROLES    AGE     VERSION
+...
+example-extra-az-zh9l5    Ready    worker   2m6s    v1.27.4+18eadca
+example-extra-az-zr8mj    Ready    worker   102s    v1.27.4+18eadca
+...
+----
+
+. Verify that the node pool is created by running the following command:
++
+[source,terminal]
+----
+$ oc get nodepools --namespace clusters
+----
++
+.Example output
+[source,terminal]
+----
+NAME              CLUSTER         DESIRED   CURRENT   AVAILABLE   PROGRESSING   MESSAGE
+<node_pool_name>  <cluster_name>  2         2         2           False         All replicas are available
+----

modules/hcp-openstack-accessing.adoc

@@ -0,0 +1,45 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-manage/hcp-manage-openstack.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-openstack-accessing_{context}"]
+= Accessing the hosted cluster
+
+You can access hosted clusters on {rh-openstack-first} by extracting the kubeconfig secret directly from resources by using the `oc` CLI.
+
+The _hosted cluster (hosting)_ namespace contains hosted cluster resources and the access secrets. The _hosted control plane_ namespace is where the hosted control plane runs.
+
+The secret name formats are as follows:
+
+** `kubeconfig` secret: `<hosted_cluster_namespace>-<name>-admin-kubeconfig`. For example, `clusters-hypershift-demo-admin-kubeconfig`.
+** `kubeadmin` password secret: `<hosted_cluster_namespace>-<name>-kubeadmin-password`. For example, `clusters-hypershift-demo-kubeadmin-password`.
+
+The `kubeconfig` secret contains a Base64-encoded `kubeconfig` field. The `kubeadmin` password secret is also Base64-encoded; you can extract it and then use the password to log in to the API server or console of the hosted cluster.
+
+.Prerequisites
+
+* The `oc` CLI is installed.
+
+.Procedure
+
+. Extract the `admin-kubeconfig` secret by entering the following command:
++
+[source,terminal]
+----
+$ oc extract -n <hosted_cluster_namespace> \
+  secret/<hosted_cluster_name>-admin-kubeconfig \
+  --to=./hostedcluster-secrets --confirm
+----
++
+.Example output
+----
+hostedcluster-secrets/kubeconfig
+----
+
+. View a list of nodes of the hosted cluster to verify your access by entering the following command:
++
+[source,terminal]
+----
+$ oc --kubeconfig ./hostedcluster-secrets/kubeconfig get nodes
+----