OSDOCS-15427: Completed CQA for Deploying HCP on IBM Power

Author: dfitzmau

hosted_control_planes/hcp-deploy/hcp-deploy-ibm-power.adoc

@@ -6,66 +6,73 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-You can deploy {hcp} by configuring a cluster to function as a hosting cluster. The hosting cluster is an {product-title} cluster where the control planes are hosted. The hosting cluster is also known as the _management_ cluster.
+You can deploy {hcp} by configuring a cluster to function as a hosting cluster. This configuration provides an efficient and scalable solution for managing many clusters. The hosting cluster is an {product-title} cluster that hosts control planes. The hosting cluster is also known as the _management_ cluster.
 
 [NOTE]
 ====
 The _management_ cluster is not the _managed_ cluster. A managed cluster is a cluster that the hub cluster manages.
 ====
 
-The {mce-short} supports only the default `local-cluster`, which is a hub cluster that is managed, and the hub cluster as the hosting cluster.
+The {mce-short} supports only the default `local-cluster`, which is a managed hub cluster, and the hub cluster as the hosting cluster.
 
-To provision {hcp} on bare metal, you can use the Agent platform. The Agent platform uses the central infrastructure management service to add worker nodes to a hosted cluster. For more information, see "Enabling the central infrastructure management service".
+To provision {hcp} on bare-metal infrastructure, you can use the Agent platform. The Agent platform uses the central infrastructure management service to add compute nodes to a hosted cluster. For more information, see "Enabling the central infrastructure management service".
 
-Each {ibm-power-title} host must be started with a Discovery Image that the central infrastructure management provides. After each host starts, it runs an Agent process to discover the details of the host and completes the installation. An Agent custom resource represents each host.
+You must start each {ibm-power-title} host with a Discovery image that the central infrastructure management provides. After each host starts, it runs an Agent process to discover the details of the host and completes the installation. An Agent custom resource represents each host.
 
 When you create a hosted cluster with the Agent platform, HyperShift installs the Agent Cluster API provider in the hosted control plane namespace.
 
+// Prerequisites to configure HCP on IBM Power
 include::modules/hcp-ibm-power-prereqs.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
 
 * link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.14/html/clusters/cluster_mce_overview#advanced-config-engine[Advanced configuration]
 * link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.14/html/clusters/cluster_mce_overview#enable-cim[Enabling the central infrastructure management service]
-* xref:../../hosted_control_planes/hcp-prepare/hcp-cli.adoc#hcp-cli-terminal_hcp-cli[Installing the {hcp} command-line interface]
+* xref:../../hosted_control_planes/hcp-prepare/hcp-cli.adoc#hcp-cli-terminal_hcp-cli[Installing the hosted control plane command-line interface]
 * xref:../../hosted_control_planes/hcp-prepare/hcp-enable-disable.adoc#hcp-enable-manual_hcp-enable-disable[Manually enabling the {hcp} feature]
 * xref:../../hosted_control_planes/hcp-prepare/hcp-enable-disable.adoc#hcp-disable_hcp-enable-disable[Disabling the {hcp} feature]
 
+// IBM Power infrastructure requirements
 include::modules/hcp-ibm-power-infra-reqs.adoc[leveloffset=+1]
 
+// DNS configuration for {hcp} on {ibm-power-title}
 include::modules/hcp-ibm-power-dns.adoc[leveloffset=+1]
-include::modules/hcp-custom-dns.adoc[leveloffset=+2]
-
-[id="hcp-bm-create-hc-ibm-power"]
-== Creating a hosted cluster on bare metal
 
-You can create a hosted cluster or import one. When the Assisted Installer is enabled as an add-on to {mce-short} and you create a hosted cluster with the Agent platform, the HyperShift Operator installs the Agent Cluster API provider in the hosted control plane namespace.
+// Defining a custom DNS name
+include::modules/hcp-custom-dns.adoc[leveloffset=+2]
 
-include::modules/hcp-bm-hc.adoc[leveloffset=+2]
+// Creating a hosted cluster by using the CLI
+include::modules/hcp-bm-hc.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
-* xref:../../hosted_control_planes/hcp-import.adoc[Manually importing a hosted cluster]
-* xref:../../hosted_control_planes/hcp-disconnected/hcp-deploy-dc-bm.adoc#hcp-dc-extract_hcp-deploy-dc-bm[Extracting the release image digest]
-
-[id="hcp-ibm-power-heterogeneous-nodepools_{context}"]
-== Creating heterogeneous node pools on agent hosted clusters
 
-On the agent platform, you can create heterogeneous node pools so that your clusters can run diverse machine types, such as `x86_64` or `ppc64le`, within a single hosted cluster.
+* xref:../../hosted_control_planes/hcp-prepare/hcp-requirements.adoc#hcp-requirements[Requirements for hosted control planes]
+* xref:../../hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc#hcp-bm-dns_hcp-deploy-bm[DNS configurations on bare metal]
+* xref:../../hosted_control_planes/hcp-import.adoc#hcp-import[Manually importing a hosted cluster]
+* xref:../../hosted_control_planes/hcp-disconnected/hcp-deploy-dc-bm.adoc#hcp-dc-extract_hcp-deploy-dc-bm[Extracting the release image digest]
 
-include::modules/hcp-ibm-power-create-heterogeneous-nodepools-agent-hc-con.adoc[leveloffset=+2]
+// About creating heterogeneous node pools on agent hosted clusters
+include::modules/hcp-ibm-power-create-heterogeneous-nodepools-agent-hc-con.adoc[leveloffset=+1]
 
+// Creating the AgentServiceConfig custom resource
 include::modules/hcp-ibm-power-create-heterogeneous-nodepools-agent-hc.adoc[leveloffset=+2]
 
+// Create an agent cluster
 include::modules/hcp-ibm-power-heterogeneous-nodepools-create-agent-cluster.adoc[leveloffset=+2]
 
+// Creating heterogeneous node pools
 include::modules/hcp-create-heterogeneous-nodepools.adoc[leveloffset=+2]
 
+// DNS configuration for hosted control planes
 include::modules/hcp-ibm-power-heterogeneous-nodepools-agent-hc-dns.adoc[leveloffset=+2]
 
+// Creating infrastructure environment resources
 include::modules/hcp-create-infraenv.adoc[leveloffset=+2]
 
+// Adding agents to the heterogeneous cluster
 include::modules/hcp-adding-agents.adoc[leveloffset=+2]
 
+// Scaling the node pool
 include::modules/hcp-scale-the-nodepool.adoc[leveloffset=+2]

modules/hcp-adding-agents.adoc

@@ -6,15 +6,15 @@
 [id="hcp-adding-agents_{context}"]
 = Adding agents to the heterogeneous cluster
 
-You add agents by manually configuring the machine to boot with a live ISO. You can download the live ISO and use it to boot a bare-metal node or a virtual machine. On boot, the node communicates with the `assisted-service` and registers as an agent in the same namespace as the `InfraEnv` resource. When each agent is created, you can optionally set its `installation_disk_id` and `hostname` parameters in the specifications. When you are done, approve it to indicate that the agent is ready for use.
+You add agents by manually configuring the machine to boot with a live ISO. You can download the live ISO and use it to boot a bare-metal node or a virtual machine. On boot, the node communicates with the `assisted-service` and registers as an agent in the same namespace as the `InfraEnv` resource. After the creation of each agent, you can optionally set its `installation_disk_id` and `hostname` parameters in the specifications. You can then approve the agent to indicate the agent as ready for use.
 
 .Procedure
 
 . Obtain a list of agents by running the following command:
 +
 [source,terminal]
 ----
-oc -n <hosted_control_plane_namespace> get agents
+$ oc -n <hosted_control_plane_namespace> get agents
 ----
 +
 .Example output
@@ -28,21 +28,21 @@ e57a637f-745b-496e-971d-1abbf03341ba                        auto-assign
 +
 [source,terminal]
 ----
-oc -n <hosted_control_plane_namespace> patch agent 86f7ac75-4fc4-4b36-8130-40fa12602218 -p '{"spec":{"installation_disk_id":"/dev/sda","approved":true,"hostname":"worker-0.example.krnl.es"}}' --type merge
+$ oc -n <hosted_control_plane_namespace> patch agent 86f7ac75-4fc4-4b36-8130-40fa12602218 -p '{"spec":{"installation_disk_id":"/dev/sda","approved":true,"hostname":"worker-0.example.krnl.es"}}' --type merge
 ----
 
 . Patch the second agent by running the following command:
 +
 [source,terminal]
 ----
-oc -n <hosted_control_plane_namespace> patch agent 23d0c614-2caa-43f5-b7d3-0b3564688baa -p '{"spec":{"installation_disk_id":"/dev/sda","approved":true,"hostname":"worker-1.example.krnl.es"}}' --type merge
+$ oc -n <hosted_control_plane_namespace> patch agent 23d0c614-2caa-43f5-b7d3-0b3564688baa -p '{"spec":{"installation_disk_id":"/dev/sda","approved":true,"hostname":"worker-1.example.krnl.es"}}' --type merge
 ----
 
 . Check the agent approval status by running the following command:
 +
 [source,terminal]
 ----
-oc -n <hosted_control_plane_namespace> get agents
+$ oc -n <hosted_control_plane_namespace> get agents
 ----
 +
 .Example output

modules/hcp-bm-hc.adoc

@@ -8,21 +8,23 @@
 [id="hcp-bm-hc_{context}"]
 = Creating a hosted cluster by using the CLI
 
-To create a hosted cluster by using the command-line interface (CLI), complete the following steps.
+You can create a hosted cluster or import one. After you enable the Assisted Installer as an add-on to {mce-short} and you create a hosted cluster with the Agent platform, the HyperShift Operator installs the Agent Cluster API provider in the hosted control plane namespace. The Agent Cluster API provider connects a management cluster that hosts the control plane and a hosted cluster that consists of only the compute nodes. 
+
+You can create a hosted cluster on bare metal or import one.
 
 .Prerequisites
 
-- Each hosted cluster must have a cluster-wide unique name. A hosted cluster name cannot be the same as any existing managed cluster in order for the {mce-short} to manage it.
+- Each hosted cluster must have a cluster-wide unique name. A hosted cluster name cannot be the same as any existing managed cluster. Otherwise, the {mce-short} cannot manage the hosted cluster.
 
-- Do not use `clusters` as a hosted cluster name.
+- Do not use the word `clusters` as a hosted cluster name.
 
-- A hosted cluster cannot be created in the namespace of a {mce-short} managed cluster.
+- You cannot create a hosted cluster in the namespace of a {mce-short} managed cluster.
 
 - Verify that you have a default storage class configured for your cluster. Otherwise, you might see pending persistent volume claims (PVCs).
 
-- By default when you use the `hcp create cluster agent` command, the hosted cluster is created with node ports. However, the preferred publishing strategy for hosted clusters on bare metal is to expose services through a load balancer. If you create a hosted cluster by using the web console or by using {rh-rhacm-title}, to set a publishing strategy for a service besides the Kubernetes API server, you must manually specify the `servicePublishingStrategy` information in the `HostedCluster` custom resource. For more information, see step 4 in this procedure.
+- By default when you use the `hcp create cluster agent` command, the command creates a hosted cluster with configured node ports. The preferred publishing strategy for hosted clusters on bare metal exposes services through a load balancer. If you create a hosted cluster by using the web console or by using {rh-rhacm-title}, to set a publishing strategy for a service besides the Kubernetes API server, you must manually specify the `servicePublishingStrategy` information in the `HostedCluster` custom resource.
 
-- Ensure that you meet the requirements described in "Preparing to deploy {hcp} on bare metal", which includes requirements related to infrastructure, firewalls, ports, and services. For example, those requirements describe how to add the appropriate zone labels to the bare-metal hosts in your management cluster, as shown in the following example commands:
+- Ensure that you meet the requirements described in "Requirements for {hcp} on bare metal", which includes requirements related to infrastructure, firewalls, ports, and services. For example, those requirements describe how to add the appropriate zone labels to the bare-metal hosts in your management cluster, as shown in the following example commands:
 +
 [source,terminal]
 ----
@@ -50,7 +52,7 @@ $ oc label node [compute-node-3] topology.kubernetes.io/zone=zone3
 $ oc create ns <hosted_cluster_namespace>
 ----
 +
-Replace `<hosted_cluster_namespace>` with an identifier for your hosted cluster namespace. Typically, the namespace is created by the HyperShift Operator, but during the hosted cluster creation process on bare metal, a Cluster API provider role is generated that needs the namespace to already exist.
+Replace `<hosted_cluster_namespace>` with an identifier for your hosted cluster namespace. The HyperShift Operator creates the namespace. During the hosted cluster creation process on bare-metal infrastructure, a generated Cluster API provider role requires that the namespace already exists.
 
 . Create the configuration file for your hosted cluster by entering the following command:
 +
@@ -73,28 +75,28 @@ $ hcp create cluster agent \
   --ssh-key <home_directory>/<path_to_ssh_key>/<ssh_key> > hosted-cluster-config.yaml <12>
 ----
 +
-<1> Specify the name of your hosted cluster.
-<2> Specify the path to your pull secret, for example, `/user/name/pullsecret`.
-<3> Specify your hosted control plane namespace. To ensure that agents are available in this namespace, enter the `oc get agent -n <hosted_control_plane_namespace>` command.
-<4> Specify your base domain, for example, `krnl.es`.
-<5> The `--api-server-address` flag defines the IP address that is used for the Kubernetes API communication in the hosted cluster. If you do not set the `--api-server-address` flag, you must log in to connect to the management cluster.
-<6> Specify the etcd storage class name, for example, `lvm-storageclass`.
+<1> Specify the name of your hosted cluster, such as `example`.
+<2> Specify the path to your pull secret, such as `/user/name/pullsecret`.
+<3> Specify your hosted control plane namespace, such as `clusters-example`. Ensure that agents are available in this namespace by using the `oc get agent -n <hosted_control_plane_namespace>` command.
+<4> Specify your base domain, such as `krnl.es`.
+<5> The `--api-server-address` flag defines the IP address that gets used for the Kubernetes API communication in the hosted cluster. If you do not set the `--api-server-address` flag, you must log in to connect to the management cluster.
+<6> Specify the etcd storage class name, such as `lvm-storageclass`.
 <7> Specify the path to your SSH public key. The default file path is `~/.ssh/id_rsa.pub`.
 <8> Specify your hosted cluster namespace.
 <9> Specify the availability policy for the hosted control plane components. Supported options are `SingleReplica` and `HighlyAvailable`. The default value is `HighlyAvailable`.
-<10> Specify the supported {product-title} version that you want to use, for example, `4.19.0-multi`. If you are using a disconnected environment, replace `<ocp_release_image>` with the digest image. To extract the {product-title} release image digest, see "Extracting the release image digest".
-<11> Specify the node pool replica count, for example, `3`. You must specify the replica count as `0` or greater to create the same number of replicas. Otherwise, no node pools are created.
-<12> After the `--ssh-key` flag, specify the path to the SSH key; for example, `user/.ssh/id_rsa`.
+<10> Specify the supported {product-title} version that you want to use, such as `4.19.0-multi`. If you are using a disconnected environment, replace `<ocp_release_image>` with the digest image. To extract the {product-title} release image digest, see _Extracting the {product-title} release image digest_.
+<11> Specify the node pool replica count, such as `3`. You must specify the replica count as `0` or greater to create the same number of replicas. Otherwise, you do not created node pools.
+<12> After the `--ssh-key` flag, specify the path to the SSH key, such as `user/.ssh/id_rsa`.
 
 . Configure the service publishing strategy. By default, hosted clusters use the NodePort service publishing strategy because node ports are always available without additional infrastructure. However, you can configure the service publishing strategy to use a load balancer.
 
 ** If you are using the default NodePort strategy, configure the DNS to point to the hosted cluster compute nodes, not the management cluster nodes. For more information, see "DNS configurations on bare metal".
 
-** For production environments, use the LoadBalancer strategy because it provides certificate handling and automatic DNS resolution. To change the service publishing strategy `LoadBalancer`, in your hosted cluster configuration file, edit the service publishing strategy details:
+** For production environments, use the LoadBalancer strategy because this strategy provides certificate handling and automatic DNS resolution. The following example demonstrates changing the service publishing `LoadBalancer` strategy in your hosted cluster configuration file:
 +
 [source,yaml]
 ----
-...
+# ...
 spec:
   services:
   - service: APIServer
@@ -114,7 +116,7 @@ spec:
       type: Route
   sshKey:
     name: <ssh_key>
-...
+# ...
 ----
 +
 <1> Specify `LoadBalancer` as the API Server type. For all other services, specify `Route` as the type.
@@ -126,7 +128,7 @@ spec:
 $ oc apply -f hosted_cluster_config.yaml
 ----
 
-. Monitor the creation of the hosted cluster, node pools, and pods by entering the following commands:
+. Check for the creation of the hosted cluster, node pools, and pods by entering the following commands:
 +
 [source,terminal]
 ----
@@ -149,7 +151,7 @@ $ oc get nodepool \
 $ oc get pods -n <hosted_cluster_namespace>
 ----
 
-. Confirm that the hosted cluster is ready. The cluster is ready when its status is `Available: True`, the node pool status shows `AllMachinesReady: True`, and all cluster Operators are healthy.
+. Confirm that the hosted cluster is ready. The status of `Available: True` indicates the readiness of the cluster and the node pool status shows `AllMachinesReady: True`. These statuses indicate the healthiness of all cluster Operators.
 
 . Install MetalLB in the hosted cluster:
 +
@@ -196,6 +198,7 @@ spec:
   source: redhat-operators
   sourceNamespace: openshift-marketplace
   installPlanApproval: Automatic
+# ...
 ----
 +
 .. Apply the file by entering the following command:
@@ -227,6 +230,7 @@ metadata:
 spec:
   ipAddressPools:
   - metallb
+# ...
 ----
 +
 .. Apply the configuration by entering the following command:
@@ -236,7 +240,7 @@ spec:
 $ oc apply -f deploy-metallb-ipaddresspool.yaml
 ----
 +
-.. Verify that MetalLB is installed by checking the Operator status, the IP address pool, and the L2Advertisement. Enter the following commands:
+.. Verify the installation of MetalLB by checking the Operator status, the IP address pool, and the `L2Advertisement` resource by entering the following commands:
 +
 [source,terminal]
 ----
@@ -279,6 +283,7 @@ spec:
   selector:
     ingresscontroller.operator.openshift.io/deployment-ingresscontroller: default
   type: LoadBalancer
+# ...
 ----
 +
 .. Apply the configuration by entering the following command:
@@ -343,7 +348,7 @@ Ensure that all Operators show `AVAILABLE: True`, `PROGRESSING: False`, and `DEG
 $ oc get nodes
 ----
 +
-Ensure that the status of all nodes is `READY`.
+Ensure that each node has the `READY` status.
 
 . Test access to the console by entering the following URL in a web browser:
 +