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

Author: dfitzmau

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

@@ -6,21 +6,22 @@ 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"]
@@ -32,30 +33,38 @@ include::modules/hcp-ibm-power-prereqs.adoc[leveloffset=+1]
 * 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]
+
+// Defining a custom DNS name
 include::modules/hcp-custom-dns.adoc[leveloffset=+2]
 
+// Creating a hosted cluster on bare metal
 include::modules/hcp-bm-hc.adoc[leveloffset=+1]
 
-[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.
-
-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,15 +8,17 @@
 [id="hcp-bm-hc_{context}"]
 = Creating a hosted cluster on bare metal
 
-When you create a hosted cluster with the Agent platform, HyperShift installs the Agent Cluster API provider in the hosted control plane namespace. You can create a hosted cluster on bare metal or import one.
+When you create a hosted cluster with the Agent platform, HyperShift Opertor 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.
 
 As you create a hosted cluster, keep the following guidelines in mind:
 
 - 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 {mce-short} to manage it.
 
 - Do not use `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.
 
 - The most common service publishing strategy is to expose services through a load balancer. That strategy is the preferred method for exposing the Kubernetes API server. 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.
 
@@ -49,17 +51,17 @@ $ hcp create cluster agent \
     --node-pool-replicas <node_pool_replica_count> <11>
 ----
 +
-<1> Specify the name of your hosted cluster, for instance, `example`.
-<2> Specify the path to your pull secret, for example, `/user/name/pullsecret`.
+<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, for example, `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, 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`.
+<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 {product-title} 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.
+<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.
 
 +
 . After a few moments, verify that your hosted control plane pods are up and running by entering the following command:

modules/hcp-create-heterogeneous-nodepools.adoc

@@ -6,7 +6,7 @@
 [id="hcp-create-heterogeneous-nodepools_{context}"]
 = Creating heterogeneous node pools
 
-You create heterogeneous node pools by using the `NodePool` custom resource (CR).
+You create heterogeneous node pools by using the `NodePool` custom resource (CR), so that you can optimize costs and performance by associating different workloads to specific hardware.
 
 .Procedure
 
@@ -40,4 +40,4 @@ spec:
 EOF
 ----
 +
-<1> This selector block is selects the agents that match the specified label. To create a node pool of architecture `ppc64le` with zero replicas, specify `ppc64le`. This ensures that it selects only agents from `ppc64le` architecture when it scales.
+<1> The selector block selects the agents that match the specified label. To create a node pool of architecture `ppc64le` with zero replicas, specify `ppc64le`. This ensures that it selects only agents from `ppc64le` architecture when it scales.

modules/hcp-create-infraenv.adoc

@@ -6,11 +6,11 @@
 [id="hcp-create-infraenv_{context}"]
 = Creating infrastructure environment resources
 
-For heterogeneous node pools, you must create an `infraEnv` custom resource (CR) for each architecture. For example, for node pools with `x86_64` and `ppc64le` architectures, create an `InfraEnv` CR for `x86_64` and `ppc64le`.
+For heterogeneous node pools, you must create an `infraEnv` custom resource (CR) for each architecture. This configuration ensures that the correct architecture-specific operating system and boot artifacts get uses during the node provisioning process. For example, for node pools with `x86_64` and `ppc64le` architectures, create an `InfraEnv` CR for `x86_64` and `ppc64le`.
 
 [NOTE]
 ====
-Before proceeding, make sure that the operating system (OS) images for both `x86_64` and `ppc64le` architectures are added to the `AgentServiceConfig` resource. After this, you can use the `InfraEnv` resources to get the minimal ISO image.
+Before proceeding, make sure that you add the operating system (OS) images for both `x86_64` and `ppc64le` architectures to the `AgentServiceConfig` resource. After this, you can use the `InfraEnv` resources to get the minimal ISO image.
 ====
 
 .Procedure
@@ -36,7 +36,7 @@ EOF
 <1> The hosted cluster name.
 <2> The `x86_64` architecture.
 <3> The hosted control plane namespace.
-<4> The ssh public key.
+<4> The SSH public key.
 
 . Create the `InfraEnv` resource with `ppc64le` architecture for heterogeneous node pools by running the following command:
 +
@@ -59,18 +59,18 @@ EOF
 <1> The hosted cluster name.
 <2> The `ppc64le` architecture.
 <3> The hosted control plane namespace.
-<4> The ssh public key.
+<4> The SSH public key.
 
-. To verify that the `InfraEnv` resources are created successfully run the following commands:
+. Verify the successful creation of the `InfraEnv` resources run the following commands:
 
-** Verify that the `x86_64` `InfraEnv` resource is created successfully:
+** Verify the successful creation of the `x86_64` `InfraEnv` resource:
 +
 [source,terminal]
 ----
 $ oc describe InfraEnv <hosted_cluster_name>-<arch_x86>
 ----
 +
-** Verify that the `ppc64le` `InfraEnv` resource is created successfully:
+** Verify the successful creation of the `ppc64le` `InfraEnv` resource:
 +
 [source,terminal]
 ----