From a9c959d39f9dba0edd043635ce46aa7b075c03cd Mon Sep 17 00:00:00 2001 From: Samuel Karp Date: Thu, 2 Jan 2020 11:16:09 -0800 Subject: [PATCH] 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. --- README.md | 59 +++++++++++++++++++----------- docs/docker-credential-ecr-login.1 | 27 ++++++++++++-- 2 files changed, 61 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 7510f0c7..515be93f 100644 --- a/README.md +++ b/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 in 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` diff --git a/docs/docker-credential-ecr-login.1 b/docs/docker-credential-ecr-login.1 index a1be37ce..50c900d0 100644 --- a/docs/docker-credential-ecr-login.1 +++ b/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,8 +104,13 @@ 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. +Copyright 2018-2020 Amazon.com, Inc. or its affiliates. All rights reserved. .SH LICENSE Licensed under the Apache License, version 2.0.