Clarify instructions under `create a dockercloud-swarm-role` (#3345)

* Clarify instructions to create a dockercloud-swarm-role

Add clarification to steps 1, 5, 6, and 8 under `create a dockercloud-swarm-role role with an embedded policy` to prevent misunderstandings.

* walked through the steps and made some copyedits

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* brought standard mode AWS linking topic up-to-date

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* added images for aws linking in swarm, improved procedure flow

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

docker-cloud/cloud-swarm/link-aws-swarm.md

@@ -18,19 +18,22 @@ the new policy to your existing role by following the instructions
 
 ## Create a dockercloud-swarm-role role with an embedded policy
 
-1.  Go to the AWS IAM Role creation panel at  <a href="https://console.aws.amazon.com/iam/home#roles">https://console.aws.amazon.com/iam/home#roles</a>.
+1.  Go to the AWS IAM Role creation panel at  <a href="https://console.aws.amazon.com/iam/home#roles">https://console.aws.amazon.com/iam/home#roles</a>. Click **Create new role**.
 
-2.  Select **Role for Cross-Account Access**, and in the submenu that opens select **Provide access between your AWS account and a 3rd party AWS account**.
+2.  Select **Role for cross-account access**, and in the submenu that opens select **Provide access between your AWS account and a 3rd party AWS account**.
+
+  ![](images/aws-swarm-iam-role-1.png)
 
 3.  In the **Account ID** field, enter the ID for the Docker Cloud service: `689684103426`.
+
 4.  In the **External ID** field, enter the namespace you will be linking.
 
     This will either be your Docker Cloud username, or if you are using Organizations in Docker Cloud, the organization name.
     Failure to use the correct name will result in the following error message: `Invalid AWS credentials or insufficient EC2 permissions` when attempting to link your Docker account to your AWS account.
 
-5.  Leave **Require MFA** unchecked.
+5.  Leave **Require MFA** unchecked. Click **Next Step**.
 
-6.  On the next screen, do not select a policy. Click **Next**.
+6.  On the next screen, do not select a policy. Click **Next Step**.
 
     You will add the policy in a later step.
 
@@ -42,42 +45,63 @@ the new policy to your existing role by following the instructions
     you might have `dockercloud-swarm-role-moby` and
     `dockercloud-swarm-role-teamawesome`.
 
-8.  On the next page click **Create Role**.
+8.  Click **Create Role**.
 
     AWS IAM creates the new role and returns you to the **Roles** list.
 
 9.  Click the name of the role you just created to view its details.
+
 10. On the **Permissions** tab, click the carat icon next to **Inline Policies** to expand the section.
+
 11. In the **Inline Policies** section, click the link to create a policy.
+
 12. On the next page, click **Custom Policy** and click **Select**.
+
 13. On the **Policy Editor** page that appears, give the policy a name like `dockercloud-swarm-policy`.
+
 14. In the **Policy Document** section, copy and paste the policy document found in the [Docker for AWS page](/docker-for-aws/iam-permissions/).
-15. Click **Create Policy**.
-16. Back on the role view, review your entries and copy the full **Role ARN** string.
+
+15. Click **Apply Policy**.
+
+16. Back on the role view, click into the new role to view details, and copy the full **Role ARN** string.
 
     The ARN string should look something like `arn:aws:iam::123456789123:role/dockercloud-swarm-role`. You'll use the ARN in the next step.
 
+    ![](images/aws-swarm-iam-role-2.png)
+
 ## Attach a policy for legacy AWS links
 
-If you already have your AWS account connected to Docker Cloud and used the legacy node cluster functionality you will need to create and attach a new policy, and re-link your account.
+If you already have your AWS account connected to Docker Cloud and used the
+legacy node cluster functionality you will need to create and attach a new
+policy, and re-link your account.
 
 1.  Go to the AWS IAM Roles list at  <a href="https://console.aws.amazon.com/iam/home#roles">https://console.aws.amazon.com/iam/home#roles</a>.
+
 2.  Click your existing version of the `dockercloud-role`.
+
 3.  On the **Permissions** tab, click the carat icon next to **Inline Policies** to expand the section.
+
 4.  Click the link in the **Inline Policies** section to create a policy.
+
 5.  On the next page, click **Custom Policy** and click **Select**.
+
 6.  On the **Policy Editor** page that appears, give the policy a name like `dockercloud-swarm-policy`.
+
 7.  In the **Policy Document** section, copy and paste the policy document found in the [Docker for AWS page](/docker-for-aws/iam-permissions/).
-8.  Click **Apply Policy**.
-9.  Select and copy the **Role ARN** on the role screen.
+
+8.  Click **Validate Policy**.
+
+9.  If the validation succeeds, click **Apply Policy**.
+
+10.  Select and copy the **Role ARN** on the role screen.
     It shouldn't have changed, but you'll use it to re-link your account.
 
 Because you edited the role's permissions, you need to re-link to your account.
 Back in Docker Cloud, click the account menu and select **Cloud Settings**, and
-in the **Service providers** section, click the green plug icon to unlink your
+in the **Service providers** section, click the green plug icon to _unlink_ your
 AWS account.
 
-Then follow the instructions below to re-link your account.
+Then, follow the instructions below to re-link your account.
 
 ## Add your AWS account credentials to Docker Cloud
 

docker-cloud/infrastructure/link-aws.md

@@ -49,7 +49,7 @@ Create an access control policy that will grant specific privileges to Docker Cl
     }
     ```
 
-    To limit the user to a specific region, use the [policy below](link-aws.md#limit-dockercloud-user-to-a-specific-ec2-region) instead.
+    To limit the user to a specific region, use the [policy below](link-aws.md#limit-dockercloud-policy-to-a-specific-ec2-region) instead.
 
     `ec2:*` allows the user to perform any operation in EC2.
 
@@ -58,7 +58,7 @@ Create an access control policy that will grant specific privileges to Docker Cl
     > **Note**: You cannot use an instance profile that has more permissions than the IAM user you are using with Docker Cloud. If you do that, you will get an "unauthorized operation" error. You can fix this issue by adding the `"Action":"iam:PassRole"` permission to the policy for the service user. You can read more about this [here](http://blogs.aws.amazon.com/security/post/Tx3M0IFB5XBOCQX/Granting-Permission-to-Launch-EC2-Instances-with-IAM-Roles-PassRole-Permission){: target="_blank" class="_"}.
 
 6.  Click **Validate Policy**.
-7.  If the validation is successful click **Create Policy**.
+7.  If the validation succeeds, click **Create Policy**.
 
 ### Limit dockercloud-policy to a specific EC2 region
 
@@ -92,34 +92,44 @@ You can use the following `dockercloud-policy` to limit Docker Cloud to a specif
 ```
 
 ## Create a dockercloud-role role
-1. Go to the AWS IAM Role creation panel at <a href="https://console.aws.amazon.com/iam/home#roles">https://console.aws.amazon.com/iam/home#roles</a>.
 
-2.  Select **Role for Cross-Account Access**, and in the submenu that opens select **Allows IAM users from a 3rd party AWS account to access this account**.
+1. Go to the AWS IAM Role creation panel at <a href="https://console.aws.amazon.com/iam/home#roles">https://console.aws.amazon.com/iam/home#roles</a>  Click **Create new role**.
+
+2.  Select **Role for cross-account access**, and in the submenu that opens select **Provide access between your AWS account and a 3rd party AWS account**.
 
     ![](images/aws-iam-role-1.png)
 
 3. In the **Account ID** field, enter the ID for the Docker Cloud service: `689684103426`.
+
 4. In the **External ID** field, enter your Docker Cloud username.
 
-    If you're linking to nodes for an organization, enter the organization name.
+   This might be your Docker ID username, or if you are using Organizations in Docker Cloud enter the organization name.
+
+5. Leave **Require MFA** unchecked. Click **Next Step**.
+
+6. On the next screen, select the `dockercloud-policy` you created to attach to the role. Click **Next Step**.
 
-5. Leave **Require MFA** unchecked.
-6. On the next screen, select the `dockercloud-policy` you created to attach to the role.
 7. Give the new role a name, such as `dockercloud-role`.
 
     > **Note**: You must use one role per Docker Cloud account namespace, so if you will be using nodes from a single AWS account for multiple Docker Cloud accounts, you should add an identifying the namespace to the end of the name. For example, you might have `dockercloud-role-moby` and `dockercloud-role-teamawesome`.
-8. On next page review your entries and copy the full **Role ARN** string.
 
-    The ARN string should look something like `arn:aws:iam::123456789123:role/dockercloud-role`. You'll use the ARN in the next step. If you forget to copy the ARN here, view the Role in IAM to see its related information including the ARN.
+8.  Click **Create Role**.
 
-9. Click **Create Role**.
+    AWS IAM creates the new role and returns you to the **Roles** list.
+
+9. Click into the new role to view details, and copy the full **Role ARN** string.
+
+    The ARN string should look something like
+    `arn:aws:iam::123456789123:role/dockercloud-role`. You'll use the
+    ARN in the next step. If you forget to copy the ARN here, view the
+    Role in IAM to see its related information including the ARN.
 
     ![](images/aws-iam-role-2.png)
 
 ## Add AWS account credentials
 
-Once you've created a `dockercloud-policy`, attached it to a
-`dockercloud-role`, and have the role's Role ARN, go back to Docker Cloud to connect the account.
+Once you've created a `dockercloud-policy`, attached it to a `dockercloud-role`,
+and have the role's Role ARN, go back to Docker Cloud to connect the account.
 
 1. In Docker Cloud, click **Cloud settings** at the lower left.
 2. In the Cloud Providers section, click the plug icon next to Amazon Web Services.