[Working] HyperShiftStack

_topic_maps/_topic_map.yml

@@ -2524,6 +2524,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:
@@ -2537,6 +2539,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:
@@ -2594,6 +2598,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,23 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="hcp-deploy-openstack"]
+include::_attributes/common-attributes.adoc[]
+= Deploying {hcp} on OpenStack
+:context: hcp-deploy-openstack
+
+toc::[]
+
+You can deploy {hcp} with hosted clusters that run on {rh-openstack-first}.
+
+A _hosted cluster_ is an {product-title} cluster with its API endpoint and control plane that are hosted on the hosting cluster. The hosted cluster includes the control plane and its corresponding data plane. You can use the {mce-short} console or the `hcp` command-line interface (CLI) to create a hosted cluster.
+
+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,34 @@
+:_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]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../networking/networking_operators/metallb-operator/about-metallb.adoc#about-metallb_about-metallb[About MetalLB and the MetalLB Operator]
+
+include::modules/hosted-clusters-openstack-performance.adoc[leveloffset=+1]

modules/hcp-deploy-openstack-create.adoc

@@ -0,0 +1,65 @@
+:_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 completed all prerequisite steps in "Prerequisites for OpenStack".
+* You have access to the management cluster.
+* You have access to the {rh-openstack} cloud.
+
+.Procedure
+
+* Create a hosted cluster by running the following command:
++
+[source,terminal]
+----
+$ hcp create cluster openstack --node-pool-flavor <node_pool_flavor>
+----
++
+--
+where:
+
+`<node_pool_flavor>`:: Specifies the flavor of the node pool of the cluster.
+--
+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
+----
+
+[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,53 @@
+// 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.
+|No
+
+|`--openstack-cloud`
+|Name of the cloud in `clouds.yaml`. The default value is `openstack`.
+|No
+
+|`--openstack-credentials-file`
+|Path to the OpenStack credentials file.
+|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,48 @@
+// 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 either getting the `kubeconfig` file and `kubeadmin`
+credential directly from
+resources, or by using the `hcp` command-line interface to generate a `kubeconfig` file.
+
+.Prerequisites
+
+To access the hosted cluster by getting the `kubeconfig` file and credentials directly from resources, you must be familiar with the access secrets for hosted clusters. 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, which you can decode and save into a file to use with the following command:
+
+[source,terminal]
+----
+$ oc --kubeconfig <hosted_cluster_name>.kubeconfig get nodes
+----
+
+The `kubeadmin` password secret is also Base64-encoded. You can decode it and use the password to log in to the API server or console of the hosted cluster.
+
+.Procedure
+
+* To access the hosted cluster by using the `hcp` CLI to generate the `kubeconfig` file, take the following steps:
+
+. Generate the `kubeconfig` file by entering the following command:
++
+[source,terminal]
+----
+$ hcp create kubeconfig --namespace <hosted_cluster_namespace> \
+  --name <hosted_cluster_name> > <hosted_cluster_name>.kubeconfig
+----
+
+. After you save the `kubeconfig` file, you can access the hosted cluster by entering the following example command:
++
+[source,terminal]
+----
+$ oc --kubeconfig <hosted_cluster_name>.kubeconfig get nodes
+----