Updated instructions on linking AWS accounts in Docker Cloud (#4647)

* updated ifconfig to ip addr show w/hints for Docker for Mac, Windows users

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

* improved the note on Docker for Mac and Windows

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

* update AWS IAM role instructions on Cloud docs

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

* optimized images, fixed duplicate text content

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

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

@@ -20,55 +20,71 @@ the new policy to your existing role by following the instructions
 
 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 **Another AWS account** to allow your Docker Cloud account to perform actions in this AWS account.
 
-  ![](images/aws-swarm-iam-role-1.png)
+    ![link aws accounts](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.
+4. Select **Require external ID (Best practice when a third party will assume this role)**.
 
-    This will either be your Docker Cloud username, or if you are using Organizations in Docker Cloud, the organization name.
+    * In the **External ID** field, enter the namespace
-    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.
+    you will be linking.
 
-5.  Leave **Require MFA** unchecked. Click **Next Step**.
+      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.
 
-6.  On the next screen, do not select a policy. Click **Next Step**.
+    * Leave **Require MFA** unchecked.
 
-    You will add the policy in a later step.
+    Click **Next Permissions**.
 
-7.  Give the new role a name, such as `dockercloud-swarm-role`.
+5.  On the next screen, do not select a policy (you will add the policy in a later step).
 
-    > **Note**: You must use one role per Docker Cloud account namespace, so if
+    Click **Next: Review**.
-    you will be using a single AWS account for multiple Docker Cloud accounts,
+
-    you should add an identifying namespace to the end of the name. For example,
+    ![review settings](images/aws-swarm-iam-role-3.png)
+
+6.  Give the new role a name, such as `dockercloud-swarm-role`.
+
+    > **Note**: You must use one role per Docker Cloud account
+    namespace, so if you will be using a single AWS account for
+    multiple Docker Cloud accounts, you should add an
+    identifying namespace to the end of the name. For example,
     you might have `dockercloud-swarm-role-moby` and
     `dockercloud-swarm-role-teamawesome`.
 
-8.  Click **Create Role**.
+7.  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.
+8.  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.
+9.  On the **Permissions** tab, click **+ Add an inline policy**.
 
-11. In the **Inline Policies** section, click the link to create a policy.
+11. On the next page, click **Custom Policy** and click **Select**.
 
-12. On the next page, click **Custom Policy** and click **Select**.
+12. On the **Policy Editor** page that appears, give the policy a name like `dockercloud-swarm-policy`.
 
-13. On the **Policy Editor** page that appears, give the policy a name like `dockercloud-swarm-policy`.
+13. In the **Policy Document** section, copy and paste the policy document found in the [Docker for AWS page](/docker-for-aws/iam-permissions/).
 
-14. In the **Policy Document** section, copy and paste the policy document found in the [Docker for AWS page](/docker-for-aws/iam-permissions/).
+    ![attach a policy](images/aws-swarm-iam-role-4-policy.png)
 
-15. Click **Apply Policy**.
+14. Click **Apply Policy**.
 
-16. Back on the role view, click into the new role to view details, and copy the full **Role ARN** string.
+15. 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)
 
+Now skip down to the topic on how to
+[Add your AWS account credentials to Docker Cloud](#add-your-aws-account-credentials-to-docker-cloud).
+
 ## Attach a policy for legacy AWS links
 
 If you already have your AWS account connected to Docker Cloud and used the
@@ -79,9 +95,7 @@ policy, and re-link your account.
 
 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.
+3.  On the **Permissions** tab, click **+ Add an inline policy**.
-
-4.  Click the link in the **Inline Policies** section to create a policy.
 
 5.  On the next page, click **Custom Policy** and click **Select**.
 
@@ -96,18 +110,18 @@ policy, and re-link your account.
 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.
+Because you edited the role's permissions, you need to re-link
-Back in Docker Cloud, click the account menu and select **Cloud Settings**, and
+to your account. Back in Docker Cloud, click the account menu and
-in the **Service providers** section, click the green plug icon to _unlink_ your
+select **Cloud Settings**, and in the **Service providers** section,
-AWS account.
+click the green plug icon to _unlink_ your AWS account.
 
 Then, follow the instructions below to re-link your account.
 
 ## Add your AWS account credentials to Docker Cloud
 
-Once you've created the a `dockercloud-swarm-policy`, added the
+Once you've created the a `dockercloud-swarm-policy`,
-`dockercloud-swarm-role` inline, and have the role's Role ARN, go back to Docker
+added the `dockercloud-swarm-role` inline, and have the role's
-Cloud to connect the account.
+Role ARN, go back to Docker Cloud to connect the account.
 
 1.  In Docker Cloud, click the account menu at the upper right and select **Cloud settings**.
 2.  In the **Service providers** section, click the plug icon next to Amazon Web Services.