Merge pull request #85097 from lahinson/osdocs-12355-hcp-aws

[OSDOCS-12355: Improvements to docs about creating hosted clusters on AWS

Author: lahinson

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

@@ -25,7 +25,7 @@ arn:aws:iam::1234567890:user/<aws_username>
 +
 Use this output as the value for `<arn>` in the next step.
 
-. Create a JSON file named `trust-relationship.json` that contains the trust relationship configuration for your role. See the following example:
+. Create a JSON file that contains the trust relationship configuration for your role. See the following example:
 +
 [source,json]
 ----
@@ -35,7 +35,7 @@ Use this output as the value for `<arn>` in the next step.
         {
             "Effect": "Allow",
             "Principal": {
-                "AWS": <arn> <1>
+                "AWS": "<arn>" <1>
             },
             "Action": "sts:AssumeRole"
         }
@@ -54,7 +54,7 @@ $ aws iam create-role \
 --query "Role.Arn"
 ----
 <1> Replace `<name>` with the role name, for example, `hcp-cli-role`.
-<2> Replace `<file_name>` with the file name, for example, `assume-role-policy.json`.
+<2> Replace `<file_name>` with the name of the JSON file you created in the previous step.
 +
 .Example output
 [source,terminal]

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

@@ -6,55 +6,59 @@
 [id="hcp-aws-create-secret-s3_{context}"]
 = Creating the {aws-full} S3 bucket and S3 OIDC secret
 
-If you plan to create and manage hosted clusters on {aws-first}, create the 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.
 
 .Procedure
 
-. Create an S3 bucket that has public access to host OIDC discovery documents for your clusters:
-
-.. To create the bucket in the `us-east-1` region, enter the following code:
+. Create an S3 bucket that has public access to host OIDC discovery documents for your clusters by running the following commands:
 +
-[source,bash]
+[source,terminal]
 ----
-aws s3api create-bucket --bucket <bucket_name>
-aws s3api delete-public-access-block --bucket <bucket_name>
-echo '{
-    "Version": "2012-10-17",
-    "Statement": [
-        {
-            "Effect": "Allow",
-            "Principal": "*",
-            "Action": "s3:GetObject",
-            "Resource": "arn:aws:s3:::<bucket_name>/*"
-        }
-    ]
-}' | envsubst > policy.json
-aws s3api put-bucket-policy --bucket <bucket_name> --policy file://policy.json
+$ aws s3api create-bucket --bucket <bucket_name> \// <1>
+  --create-bucket-configuration LocationConstraint=<region> \// <2>
+  --region <region> <2>
 ----
-
-.. To create the bucket in a region other than the `us-east-1` region, enter the following code:
 +
-[source,bash]
+<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.
++
+[source,terminal]
 ----
-aws s3api create-bucket --bucket <bucket_name> \
-  --create-bucket-configuration LocationConstraint=<region> \
-  --region <region>
-aws s3api delete-public-access-block --bucket <bucket_name>
-echo '{
+$ aws s3api delete-public-access-block --bucket <bucket_name> <1>
+----
++
+<1> Replace `<bucket_name>` with the name of the S3 bucket you are creating.
++
+[source,terminal]
+----
+$ echo '{
     "Version": "2012-10-17",
     "Statement": [
         {
             "Effect": "Allow",
             "Principal": "*",
             "Action": "s3:GetObject",
-            "Resource": "arn:aws:s3:::<bucket_name>/*"
+            "Resource": "arn:aws:s3:::<bucket_name>/*" <1>
         }
     ]
 }' | envsubst > policy.json
-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.
++
+[source,terminal]
+----
+$ aws s3api put-bucket-policy --bucket <bucket_name> --policy file://policy.json <1>
+----
++
+<1> Replace `<bucket_name>` with the name of the S3 bucket you are creating.
++
+[NOTE]
+====
+If you are using a Mac computer, you must export the bucket name in order for the policy to work.
+====
 
-. Create an OIDC S3 secret named `hypershift-operator-oidc-provider-s3-credentials` for the HyperShift operator.
+. Create an OIDC S3 secret named `hypershift-operator-oidc-provider-s3-credentials` for the HyperShift Operator.
 
 . Save the secret in the `local-cluster` namespace.
 
@@ -75,7 +79,6 @@ aws s3api put-bucket-policy --bucket <bucket_name> --policy file://policy.json
 | Specifies the region of the S3 bucket.
 |===
 
-
 . To create an {aws-short} secret, run the following command:
 +
 [source,terminal]
@@ -85,9 +88,9 @@ $ oc create secret generic <secret_name> --from-file=credentials=<path>/.aws/cre
 +
 [NOTE]
 ====
-Disaster recovery backup for the secret is not automatically enabled. Run the following command to add the label that enables the `hypershift-operator-oidc-provider-s3-credentials` secret to be backed up for disaster recovery:
+Disaster recovery backup for the secret is not automatically enabled. To add the label that enables the `hypershift-operator-oidc-provider-s3-credentials` secret to be backed up for disaster recovery, run the following command:
 [source,terminal]
 ----
 $ oc label secret hypershift-operator-oidc-provider-s3-credentials -n local-cluster cluster.open-cluster-management.io/backup=true
 ----
-====
+====

modules/hcp-cli-console.adoc

@@ -34,6 +34,11 @@ $ chmod +x hcp
 $ sudo mv hcp /usr/local/bin/.
 ----
 
+[NOTE]
+====
+If you download the CLI on a Mac computer, you might see a warning about the `hcp` binary file. You need to adjust your security settings to allow the binary file to be run.
+==== 
+
 .Verification
 
 * Verify that you see the list of available parameters by running the following command:

modules/hcp-cli-gateway.adoc

@@ -32,6 +32,11 @@ $ chmod +x hcp
 $ sudo mv hcp /usr/local/bin/.
 ----
 
+[NOTE]
+====
+If you download the CLI on a Mac computer, you might see a warning about the `hcp` binary file. You need to adjust your security settings to allow the binary file to be run.
+==== 
+
 .Verification
 
 * Verify that you see the list of available parameters by running the following command:

modules/hcp-cli-terminal.adoc

@@ -3,9 +3,9 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="hcp-cli-terminal_{context}"]
-= Installing the {hcp} command-line interface by using the CLI
+= Installing the {hcp} command-line interface from the terminal
 
-You can install the {hcp} command-line interface (CLI), `hcp`, by using the CLI.
+You can install the {hcp} command-line interface (CLI), `hcp`, from the terminal.
 
 .Procedure
 
@@ -46,6 +46,11 @@ $ chmod +x hcp
 $ sudo mv hcp /usr/local/bin/.
 ----
 
+[NOTE]
+====
+If you download the CLI on a Mac computer, you might see a warning about the `hcp` binary file. You need to adjust your security settings to allow the binary file to be run.
+==== 
+
 .Verification
 
 * Verify that you see the list of available parameters by running the following command: