Merge pull request #108046 from lahinson/osdocs-18554-cqa-hcp-aws-prereqs

[OSDOCS-18554]: CQA: Preparing to deploy HCP on AWS

Author: lahinson

hosted_control_planes/hcp-deploy/hcp-deploy-aws.adoc

@@ -17,12 +17,13 @@ include::modules/hcp-aws-prepare.adoc[leveloffset=+1]
 
 include::modules/hcp-aws-prereqs.adoc[leveloffset=+2]
 
-include::modules/hcp-access-hc-aws-hcpcli.adoc[leveloffset=+1]
-
 [role="_additional-resources"]
 .Additional resources
+
 * link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.16/html/clusters/cluster_mce_overview#ansible-config-hosted-cluster[Configuring Ansible Automation Platform jobs to run on hosted clusters]
+
 * link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.16/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.16/html/clusters/cluster_mce_overview#enable-cim[Enabling the central infrastructure management service]
 
 * xref:../../hosted_control_planes/hcp-prepare/hcp-enable-disable.adoc#hcp-enable-manual_hcp-enable-disable[Manually enabling the {hcp} feature]
@@ -31,13 +32,13 @@ include::modules/hcp-access-hc-aws-hcpcli.adoc[leveloffset=+1]
 
 * xref:../../networking/networking_operators/sr-iov-operator/configuring-sriov-operator.adoc#sriov-operator-hosted-control-planes_configuring-sriov-operator[Deploying the SR-IOV Operator for {hcp}]
 
-include::modules/hcp-aws-create-secret-s3.adoc[leveloffset=+1]
+include::modules/hcp-aws-create-secret-s3.adoc[leveloffset=+2]
 
-include::modules/hcp-aws-create-public-zone.adoc[leveloffset=+1]
+include::modules/hcp-aws-create-public-zone.adoc[leveloffset=+2]
 
-include::modules/hcp-aws-create-role-sts-creds.adoc[leveloffset=+1]
+include::modules/hcp-aws-create-role-sts-creds.adoc[leveloffset=+2]
 
-include::modules/hcp-aws-enable-private-link.adoc[leveloffset=+1]
+include::modules/hcp-aws-enable-private-link.adoc[leveloffset=+2]
 
 include::modules/hcp-aws-enable-ext-dns.adoc[leveloffset=+1]
 
@@ -57,7 +58,7 @@ include::modules/hcp-aws-deploy-hc.adoc[leveloffset=+1]
 .Additional resources
 * xref:../../hosted_control_planes/hcp-deploy/hcp-deploy-aws.adoc#hcp-enable-arm-amd_hcp-deploy-aws[Running hosted clusters on an ARM64 architecture]
 
-include::modules/hcp-access-hc-aws.adoc[leveloffset=+2]
+include::modules/hcp-access-hc-aws.adoc[leveloffset=+1]
 
 include::modules/hcp-access-pub-hc-aws.adoc[leveloffset=+2]
 

modules/hcp-aws-create-public-zone.adoc

@@ -6,7 +6,10 @@
 [id="hcp-aws-create-public-zone_{context}"]
 = Creating a routable public zone for hosted clusters
 
-To access applications in your hosted clusters, you must configure the routable public zone. If the public zone exists, skip this step. Otherwise, the public zone affects the existing functions.
+[role="_abstract"]
+In order to access applications in your hosted clusters, you must configure the routable public zone. 
+
+If the public zone exists, skip this step. Otherwise, the public zone affects the existing functions.
 
 .Procedure
 
@@ -15,8 +18,8 @@ To access applications in your hosted clusters, you must configure the routable
 [source,terminal]
 ----
 $ aws route53 create-hosted-zone \
-  --name <basedomain> \// <1>
+  --name <basedomain> \
   --caller-reference $(whoami)-$(date --rfc-3339=date)
 ----
 +
-<1> Replace `<basedomain>` with your base domain, for example, `www.example.com`.
+Replace `<basedomain>` with your base domain, for example, `www.example.com`.

modules/hcp-aws-create-role-sts-creds.adoc

@@ -6,7 +6,8 @@
 [id="hcp-aws-create-role-sts-creds_{context}"]
 = Creating an {aws-short} IAM role and STS credentials
 
-Before creating a hosted cluster on {aws-first}, you must create an {aws-short} IAM role and STS credentials.
+[role="_abstract"]
+Before you create a hosted cluster on {aws-first}, you must create an {aws-short} IAM role and STS credentials.
 
 .Procedure
 
@@ -23,7 +24,7 @@ $ aws sts get-caller-identity --query "Arn" --output text
 arn:aws:iam::1234567890:user/<aws_username>
 ----
 +
-Use this output as the value for `<arn>` in the next step.
+Use this output as the value for the `<arn>` value in the next step.
 
 . Create a JSON file that contains the trust relationship configuration for your role. See the following example:
 +
@@ -35,26 +36,32 @@ Use this output as the value for `<arn>` in the next step.
         {
             "Effect": "Allow",
             "Principal": {
-                "AWS": "<arn>" <1>
+                "AWS": "<arn>"
             },
             "Action": "sts:AssumeRole"
         }
     ]
 }
 ----
-<1> Replace `<arn>` with the ARN of your user that you noted in the previous step.
++
+Replace `<arn>` with the ARN of your user that you noted in the previous step.
 
 . Create the Identity and Access Management (IAM) role by running the following command:
 +
 [source,terminal]
 ----
 $ aws iam create-role \
-  --role-name <name> \// <1>
-  --assume-role-policy-document file://<file_name>.json \// <2>
+  --role-name <name> \
+  --assume-role-policy-document file://<file_name>.json \
   --query "Role.Arn"
 ----
-<1> Replace `<name>` with the role name, for example, `hcp-cli-role`.
-<2> Replace `<file_name>` with the name of the JSON file you created in the previous step.
++
+where:
++
+--
+`<name>`:: Specifies the role name, for example, `hcp-cli-role`.
+`<file_name>`:: Specifies the name of the JSON file you created in the previous step.
+--
 +
 .Example output
 [source,terminal]
@@ -197,18 +204,22 @@ arn:aws:iam::820196288204:role/myrole
 }
 ----
 
-. Attach the `policy.json` file to your role by running the following command:
+. Attach the `policy.json` file that contains the permissions policies for your role by running the following command:
 +
 [source,terminal]
 ----
 $ aws iam put-role-policy \
-  --role-name <role_name> \// <1>
-  --policy-name <policy_name> \// <2>
-  --policy-document file://policy.json <3>
+  --role-name <role_name> \
+  --policy-name <policy_name> \
+  --policy-document file://policy.json
 ----
-<1> Replace `<role_name>` with the name of your role.
-<2> Replace `<policy_name>` with your policy name.
-<3> The `policy.json` file contains the permission policies for your role.
++
+where:
++
+--
+`<role_name>`:: Specifies the name of your role.
+`<policy_name>`:: Specifies your policy name.
+--
 
 . Retrieve STS credentials in a JSON file named `sts-creds.json` by running the following command:
 +

modules/hcp-aws-create-secret-s3.adoc

@@ -6,28 +6,39 @@
 [id="hcp-aws-create-secret-s3_{context}"]
 = Creating the {aws-full} S3 bucket and S3 OIDC secret
 
-Before you can create and manage hosted clusters on {aws-first}, you must create the S3 bucket and S3 OIDC secret.
+[role="_abstract"]
+Before you can create and manage a hosted cluster on {aws-first}, you must create the S3 bucket and S3 OIDC secret. These resources provide a place for the cluster to store information about itself and a way for the cluster to prove its identity to {aws-short}. 
 
 .Procedure
 
-. Create an S3 bucket that has public access to host OIDC discovery documents for your clusters by running the following commands:
+. Create an S3 bucket that has public access to host OIDC discovery documents for your clusters.
+
+.. Enter the following command:
 +
 [source,terminal]
 ----
-$ aws s3api create-bucket --bucket <bucket_name> \// <1>
-  --create-bucket-configuration LocationConstraint=<region> \// <2>
+$ aws s3api create-bucket --bucket <bucket_name> \
+  --create-bucket-configuration LocationConstraint=<region> \
   --region <region> <2>
 ----
-<1> Replace `<bucket_name>` with the name of the S3 bucket you are creating.
-<2> To create the bucket in a region other than the `us-east-1` region, include this line and replace `<region>` with the region you want to use. To create a bucket in the `us-east-1` region, omit this line.
++
+where:
++
+--
+`<bucket_name>`:: Specifies the name of the S3 bucket you are creating.
+`<region>`:: Specifies that you want to create the bucket in a region other than the `us-east-1` region. Include this line and replace `<region>` with the region you want to use. To create a bucket in the `us-east-1` region, omit this line.
+--
 
+.. Enter the following command:
 +
 [source,terminal]
 ----
-$ aws s3api delete-public-access-block --bucket <bucket_name> <1>
+$ aws s3api delete-public-access-block --bucket <bucket_name>
 ----
-<1> Replace `<bucket_name>` with the name of the S3 bucket you are creating.
++
+Replace `<bucket_name>` with the name of the S3 bucket you are creating.
 
+.. Enter the following command:
 +
 [source,terminal]
 ----
@@ -38,20 +49,23 @@ $ echo '{
             "Effect": "Allow",
             "Principal": "*",
             "Action": "s3:GetObject",
-            "Resource": "arn:aws:s3:::<bucket_name>/*" <1>
+            "Resource": "arn:aws:s3:::<bucket_name>/*"
         }
     ]
 }' | envsubst > policy.json
 ----
-<1> Replace `<bucket_name>` with the name of the S3 bucket you are creating.
++
+Replace `<bucket_name>` with the name of the S3 bucket you are creating.
 
+.. Enter the following command:
 +
 [source,terminal]
 ----
-$ aws s3api put-bucket-policy --bucket <bucket_name> \// <1>
+$ aws s3api put-bucket-policy --bucket <bucket_name> \
   --policy file://policy.json
 ----
-<1> Replace `<bucket_name>` with the name of the S3 bucket you are creating.
++
+Replace `<bucket_name>` with the name of the S3 bucket you are creating.
 +
 [NOTE]
 ====

modules/hcp-aws-enable-private-link.adoc

@@ -6,14 +6,15 @@
 [id="hcp-aws-enable-private-link_{context}"]
 = Enabling {aws-short} PrivateLink for {hcp}
 
-To provision {hcp} on the {aws-first} with PrivateLink, enable {aws-short} PrivateLink for {hcp}.
+[role="_abstract"]
+In order to provision {hcp} on the {aws-first} with PrivateLink, you need to enable {aws-short} PrivateLink for {hcp}.
 
 .Procedure
 
 . Create an {aws-short} credential secret for the HyperShift Operator and name it `hypershift-operator-private-link-credentials`. The secret must reside in the managed cluster namespace that is the namespace of the managed cluster being used as the management cluster. If you used `local-cluster`, create the secret in the `local-cluster` namespace.
 
 . See the following table to confirm that the secret contains the required fields:
-
++
 .Required fields for the {aws-short} secret
 [options="header"]
 |===
@@ -32,8 +33,8 @@ To provision {hcp} on the {aws-first} with PrivateLink, enable {aws-short} Priva
 |===
 
 
-To create an {aws-short} secret, run the following command:
-
+. To create an {aws-short} secret, run the following command:
++
 [source,terminal]
 ----
 $ oc create secret generic <secret_name> \
@@ -42,13 +43,12 @@ $ oc create secret generic <secret_name> \
   --from-literal=region=<region> -n local-cluster
 ----
 
-[NOTE]
-====
-Disaster recovery backup for the secret is not automatically enabled. Run the following command to add the label that enables the `hypershift-operator-private-link-credentials` secret to be backed up for disaster recovery:
+
+. Disaster recovery backup for the secret is not automatically enabled. Run the following command to add the label that enables the `hypershift-operator-private-link-credentials` secret to be backed up for disaster recovery:
++
 [source,terminal]
 ----
 $ oc label secret hypershift-operator-private-link-credentials \
   -n local-cluster \
   cluster.open-cluster-management.io/backup=""
 ----
-====

modules/hcp-aws-prepare.adoc

@@ -6,12 +6,5 @@
 [id="hcp-aws-prepare_{context}"]
 = Preparing to deploy {hcp} on {aws-short}
 
-As you prepare to deploy {hcp} on {aws-first}, consider the following information:
-
-- 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.
-
-- Run the management cluster and workers on the same platform for {hcp}.
-
-- A hosted cluster cannot be created in the namespace of a {mce-short} managed cluster.
+[role="_abstract"]
+Preparing to deploy {hcp} on {aws-first} involves meeting several prerequisites and creating resources, including an S3 bucket, an OIDC secret, a routable public zone, IAM role and STS credentials.

modules/hcp-aws-prereqs.adoc

@@ -4,11 +4,12 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="hcp-aws-prereqs_{context}"]
-= Prerequisites to configure a management cluster
+= Prerequisites to deploy {hcp} on {aws-short}
 
-You must have the following prerequisites to configure the management cluster:
+[role="_abstract"]
+To ensure successful deployment of {hcp} on {aws-first}, your environment must meet the following requirements.
 
-* You have installed the {mce} 2.5 and later on an {product-title} cluster. The {mce-short} is automatically installed when you install {rh-rhacm-first}. The {mce-short} can also be installed without {rh-rhacm} as an Operator from the {product-title} software catalog.
+* You installed the {mce} 2.5 and later on an {product-title} cluster. The {mce-short} is automatically installed when you install {rh-rhacm-first}. The {mce-short} can also be installed without {rh-rhacm} as an Operator from the {product-title} software catalog.
 
 * You have at least one managed {product-title} cluster for the {mce-short}. The `local-cluster` is automatically imported in the {mce-short} version 2.5 and later. You can check the status of your hub cluster by running the following command:
 +
@@ -17,6 +18,17 @@ You must have the following prerequisites to configure the management cluster:
 $ oc get managedclusters local-cluster
 ----
 
-* You have installed the link:https://aws.amazon.com/cli/[`aws` command-line interface (CLI)].
+* You installed the link:https://aws.amazon.com/cli/[`aws` command-line interface (CLI)].
 
-* You have installed the hosted control plane CLI, `hcp`.
+* You installed the hosted control plane CLI, `hcp`.
+
+[IMPORTANT]
+====
+* Run the management cluster and compute nodes on the same platform.
+
+* For each hosted cluster, provide 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.
+
+* Do not create a hosted cluster in the namespace of a {mce-short} managed cluster.
+====

modules/hcp-create-private-hc-aws.adoc

@@ -6,7 +6,8 @@
 [id="hcp-create-private-hc-aws_{context}"]
 = Creating a private hosted cluster on {aws-short}
 
-After you enable the `local-cluster` as the hosting cluster, you can deploy a hosted cluster or a private hosted cluster on {aws-first}.
+[role="_abstract"]
+After you enable the `local-cluster` as the management cluster, you can deploy a hosted cluster or a private hosted cluster on {aws-first}.
 
 By default, hosted clusters are publicly accessible through public DNS and the default router for the management cluster.
 
@@ -27,27 +28,30 @@ For private clusters on {aws-short}, all communication with the hosted cluster o
 [source,terminal]
 ----
 $ hcp create cluster aws \
-  --name <hosted_cluster_name> \// <1>
-  --node-pool-replicas=<node_pool_replica_count> \// <2>
-  --base-domain <basedomain> \// <3>
-  --pull-secret <path_to_pull_secret> \// <4>
-  --sts-creds <path_to_sts_credential_file> \// <5>
-  --region <region> \// <6>
-  --endpoint-access Private \// <7>
-  --role-arn <role_name> <8>
+  --name <hosted_cluster_name> \
+  --node-pool-replicas=<node_pool_replica_count> \
+  --base-domain <basedomain> \
+  --pull-secret <path_to_pull_secret> \
+  --sts-creds <path_to_sts_credential_file> \
+  --region <region> \
+  --endpoint-access Private \
+  --role-arn <role_name>
 ----
-<1> Specify the name of your hosted cluster, for instance, `example`.
-<2> Specify the node pool replica count, for example, `3`.
-<3> Specify your base domain, for example, `example.com`.
-<4> Specify the path to your pull secret, for example, `/user/name/pullsecret`.
-<5> Specify the path to your {aws-short} STS credentials file, for example, `/home/user/sts-creds/sts-creds.json`.
-<6> Specify the {aws-short} region name, for example, `us-east-1`.
-<7> Defines whether a cluster is public or private.
-<8> Specify the Amazon Resource Name (ARN), for example, `arn:aws:iam::820196288204:role/myrole`. For more information about ARN roles, see "Identity and Access Management (IAM) permissions".
 +
-The following API endpoints for the hosted cluster are accessible through a private DNS zone:
+where:
 +
 --
+`<hosted_cluster_name>`:: Specifies the name of your hosted cluster, such as, `example`.
+`<node_pool_replica_count>`:: Specifies the node pool replica count, for example, `3`.
+`<basedomain>`:: Specifies your base domain, for example, `example.com`.
+`<path_to_pull_secret>`:: Specifies the path to your pull secret, for example, `/user/name/pullsecret`.
+`<path_to_sts_credential_file>`:: Specifies the path to your {aws-short} STS credentials file, for example, `/home/user/sts-creds/sts-creds.json`.
+`<region>`:: Specifies the {aws-short} region name, for example, `us-east-1`.
+`Private`:: Specifies that the cluster is private.
+`<role_name>`:: Specifies the Amazon Resource Name (ARN), for example, `arn:aws:iam::820196288204:role/myrole`. For more information about ARN roles, see "Identity and Access Management (IAM) permissions".
+--
++
+The following API endpoints for the hosted cluster are accessible through a private DNS zone:
+
 * `api.<hosted_cluster_name>.hypershift.local`
 * `*.apps.<hosted_cluster_name>.hypershift.local`
---