diff --git a/CHANGELOG.md b/CHANGELOG.md index b247088a..286e591d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ +# 0.4.0 + +* Feature - Added support for chaining assumed roles in the shared config file (`~/.aws/config`) defined by `source_profile` and `credential_source` ([#177](https://github.com/awslabs/amazon-ecr-credential-helper/pull/177)) +* Feature - Added support for Web Identities and [IAM Roles for Service Accounts (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) with Kubernetes ([#183](https://github.com/awslabs/amazon-ecr-credential-helper/pull/183)) +* Bug - Fixed the `make docker` target when the credential helper git repository is used as a git submodule ([#184](https://github.com/awslabs/amazon-ecr-credential-helper/issues/184)) + # 0.3.1 * Bug - Log directory is now automatically created when the helper runs diff --git a/README.md b/README.md index 53d06f9e..515be93f 100644 --- a/README.md +++ b/README.md @@ -13,21 +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). +You also must have AWS credentials available. See the [AWS credentials section](#aws-credentials) for details on how to +use different AWS credentials. ## Installing @@ -144,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: @@ -172,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/VERSION b/VERSION index 9e11b32f..1d0ba9ea 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.3.1 +0.4.0 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.