docs: rewrite section on AWS credentials

The credential helper now supports a variety of different mechanisms for
providing AWS credentials, and some of them are more complex than
others.  This commit reorganizes the description about how AWS
credentials are sourced, adds more detail to the manual page, and
includes information about the bugs that may exist for some Kubernetes
users.

Author: samuelkarp

README.md

@@ -13,27 +13,8 @@ for the Docker daemon that makes it easier to use
 
 You must have at least Docker 1.11 installed on your system.
 
-You also must have AWS credentials available in one of the standard locations:
-
-* The `~/.aws/credentials` file
-* The `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables
-* An [IAM role for Amazon EC2](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)
-* If you are working with an assumed role please set the environment variable: `AWS_SDK_LOAD_CONFIG=true` also.
-
-The Amazon ECR Docker Credential Helper uses the same credentials as the AWS
-CLI and the AWS SDKs. For more information about configuring AWS credentials,
-see
-[Configuration and Credential Files](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files)
-in the *AWS Command Line Interface User Guide*.
-
-The credentials must have a policy applied that
-[allows access to Amazon ECR](http://docs.aws.amazon.com/AmazonECR/latest/userguide/ecr_managed_policies.html).
-
-If you are using a yet unreleased version of the plugin with web identity credentials support using
-AssumeRoleWithWebIdentity in your k8s containers, you would need to set `AWS_SDK_LOAD_CONFIG=true` before
-your invocation to `docker push`. Also, due to a current bug in k8s as discussed 
-[here](https://github.com/kubernetes-sigs/external-dns/pull/1185), for containers that don't run as root, you
-would need the workaround mentioned there with `securityContext` of `nobody / 65534` on your k8s pod, otherwise, the token file is unreadable, and the plugin silently errors with a 401.
+You also must have AWS credentials available.  See the [AWS credentials section](#aws-credentials) for details on how to
+use different AWS credentials.
 
 ## Installing
 
@@ -150,6 +131,8 @@ Docker to work with the helper.
 
 ## Configuration
 
+### Docker
+
 Place the `docker-credential-ecr-login` binary on your `PATH` and set the
 contents of your `~/.docker/config.json` file to be:
 
@@ -178,6 +161,40 @@ ECR registry:
 This is useful if you use `docker` to operate on registries that use different
 authentication credentials.
 
+### AWS credentials
+
+The Amazon ECR Docker Credential Helper allows you to use AWS credentials stored different locations.  Standard ones
+include:
+
+* The shared credentials file (`~/.aws/credentials`)
+* The `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables
+* An [IAM role for an Amazon ECS task](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)
+* An [IAM role for Amazon EC2](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)
+
+To use credentials associated with a different named profile in the shared credentials file (`~/.aws/credentials`), you
+may set the `AWS_PROFILE` environment variable. 
+
+The Amazon ECR Docker Credential Helper can optionally read and support some configuration options specified in the AWS
+shared configuration file (`~/.aws/config`).  To use these options, you must set the `AWS_SDK_LOAD_CONFIG` environment
+variable to `true`.  The supported options include:
+
+* Assumed roles specified with `role_arn` and `source_profile`
+* External credential processes specified with `credential_process`
+* Web Identities like [IAM Roles for Service Accounts in
+  Kubernetes](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) (*Note: Kubernetes
+  users using containers with a non-root user may encounter permission issues described in [this
+  bug](https://github.com/kubernetes-sigs/external-dns/pull/1185) and may need to employ a workaround adjusting the
+  Kubernetes `securityContext`.*)
+
+The Amazon ECR Docker Credential Helper uses the same credentials as the AWS
+CLI and the AWS SDKs. For more information about configuring AWS credentials,
+see
+[Configuration and Credential Files](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files)
+in the *AWS Command Line Interface User Guide*.
+
+The credentials must have a policy applied that
+[allows access to Amazon ECR](http://docs.aws.amazon.com/AmazonECR/latest/userguide/ecr_managed_policies.html).
+
 ## Usage
 
 `docker pull 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-repository:my-tag`

docs/docker-credential-ecr-login.1

@@ -23,7 +23,8 @@ COMMAND
 .SH DESCRIPTION
 The Amazon ECR Credential Helper for Docker is a credential helper for the
 .BR docker (1)
-command that makes it easier to use Amazon Elastic Container Registry.
+command that makes it easier to store and retrieve container images with Amazon
+Elastic Container Registry.
 .SH USAGE
 Place the
 .B docker\-credential\-ecr\-login
@@ -63,8 +64,21 @@ EC2 instance profiles, and ECS task roles.
 To use credentials associated with a different named profile in the shared
 credentials file, you may set the \fIAWS_PROFILE\fP environment variable.
 
-To use credentials from an assumed role, you must set the
-\fIAWS_SDK_LOAD_CONFIG\fP environment variable to \fItrue\fP.
+The credential helper can optionally read and support some configuration
+options specified in the shared configuration file (\fI~/.aws/config\fP).  To
+use these options, you must set the \fIAWS_SDK_LOAD_CONFIG\fP environment
+variable to \fItrue\fP.  The supported options include:
+.IP \[bu] 2
+Assumed roles specified with \fIrole_arn\fP and \fIsource_profile\fP
+.IP \[bu]
+External credential processes specified with \fIcredential_process\fP
+.IP \[bu]
+Web Identities like IAM roles for Service Accounts in Kubernetes
+
+.RE
+The credentials must have a policy applied that allows access to Amazon ECR.
+See http://docs.aws.amazon.com/AmazonECR/latest/userguide/ecr_managed_policies.html
+for more information.
 .SH OPTIONS
 .TP 16
 .BR -v
@@ -90,6 +104,11 @@ This command is not implemented and is a no-op.
 .TP 16
 .BR erase
 This command is not implemented and is a no-op.
+.SH BUGS
+Kubernetes users using the credential helper inside containers with a non-root
+user may encounter permission issues described here:
+https://github.com/kubernetes-sigs/external-dns/pull/1185.  You may be able to
+work around this bug by adjusting the Kubernetes \fIsecurityContext\fP.
 .SH COPYRIGHT
 Copyright 2018 Amazon.com, Inc. or its affiliates.  All rights reserved.
 .SH LICENSE