forked from awslabs/amazon-ecr-credential-helper
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
54 additions
and
62 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -13,12 +13,13 @@ 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. See the [AWS credentials section](#aws-credentials) for details on how to | ||
You also must have AWS credentials available. See the [AWS credentials section](#aws-credentials) for details on how to | ||
use different AWS credentials. | ||
|
||
## Installing | ||
|
||
### Amazon Linux 2 | ||
|
||
You can install the Amazon ECR Credential Helper from the [`docker` or `ecs` | ||
extras](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-linux-ami-basics.html#extras-library). | ||
|
||
|
@@ -28,10 +29,10 @@ $ sudo yum install amazon-ecr-credential-helper | |
``` | ||
|
||
Once you have installed the credential helper, see the | ||
[Configuration section](#Configuration) for instructions on how to configure | ||
Docker to work with the helper. | ||
[Configuration section](#Configuration) for instructions on how to configure Docker to work with the helper. | ||
|
||
### Mac OS | ||
|
||
A community-maintained Homebrew formula is available in the core tap. | ||
|
||
[![Homebrew package](https://repology.org/badge/version-for-repo/homebrew/amazon-ecr-credential-helper.svg)](https://repology.org/project/amazon-ecr-credential-helper/versions) | ||
|
@@ -41,12 +42,12 @@ $ brew install docker-credential-helper-ecr | |
``` | ||
|
||
Once you have installed the credential helper, see the | ||
[Configuration section](#Configuration) for instructions on how to configure | ||
Docker to work with the helper. | ||
[Configuration section](#Configuration) for instructions on how to configure Docker to work with the helper. | ||
|
||
### Debian Buster (and future versions) | ||
You can install the Amazon ECR Credential Helper from the Debian Buster | ||
archives. This package will also be included in future releases of Debian. | ||
|
||
You can install the Amazon ECR Credential Helper from the Debian Buster archives. This package will also be included in | ||
future releases of Debian. | ||
|
||
[![Debian Stable package](https://repology.org/badge/version-for-repo/debian_stable/amazon-ecr-credential-helper.svg)](https://repology.org/project/amazon-ecr-credential-helper/versions) | ||
[![Debian Testing package](https://repology.org/badge/version-for-repo/debian_testing/amazon-ecr-credential-helper.svg)](https://repology.org/metapackage/amazon-ecr-credential-helper/versions) | ||
|
@@ -58,12 +59,11 @@ $ sudo apt install amazon-ecr-credential-helper | |
``` | ||
|
||
Once you have installed the credential helper, see the | ||
[Configuration section](#Configuration) for instructions on how to configure | ||
Docker to work with the helper. | ||
[Configuration section](#Configuration) for instructions on how to configure Docker to work with the helper. | ||
|
||
### Ubuntu 19.04 Disco Dingo and newer | ||
You can install the Amazon ECR Credential Helper from the Ubuntu 19.04 Disco | ||
Dingo (and newer) archives. | ||
|
||
You can install the Amazon ECR Credential Helper from the Ubuntu 19.04 Disco Dingo (and newer) archives. | ||
|
||
[![Ubuntu 19.04 package](https://repology.org/badge/version-for-repo/ubuntu_19_04/amazon-ecr-credential-helper.svg)](https://repology.org/metapackage/amazon-ecr-credential-helper/versions) | ||
[![Ubuntu 19.10 package](https://repology.org/badge/version-for-repo/ubuntu_19_10/amazon-ecr-credential-helper.svg)](https://repology.org/project/amazon-ecr-credential-helper/versions) | ||
|
@@ -75,10 +75,10 @@ $ sudo apt install amazon-ecr-credential-helper | |
``` | ||
|
||
Once you have installed the credential helper, see the | ||
[Configuration section](#Configuration) for instructions on how to configure | ||
Docker to work with the helper. | ||
[Configuration section](#Configuration) for instructions on how to configure Docker to work with the helper. | ||
|
||
### Arch Linux | ||
|
||
A community-maintained package is available in the Arch User Repository. | ||
|
||
[![AUR package](https://repology.org/badge/version-for-repo/aur/amazon-ecr-credential-helper.svg)](https://repology.org/metapackage/amazon-ecr-credential-helper/versions) | ||
|
@@ -90,15 +90,14 @@ $ makepkg -si | |
``` | ||
|
||
Once you have installed the credential helper, see the | ||
[Configuration section](#Configuration) for instructions on how to configure | ||
Docker to work with the helper. | ||
[Configuration section](#Configuration) for instructions on how to configure Docker to work with the helper. | ||
|
||
### From Source | ||
To build and install the Amazon ECR Docker Credential Helper, we suggest Go | ||
1.12+, `git` and `make` installed on your system. | ||
|
||
If you just installed Go, make sure you also have added it to your PATH or | ||
Environment Vars (Windows). For example: | ||
To build and install the Amazon ECR Docker Credential Helper, we suggest Go 1.12+, `git` and `make` installed on your | ||
system. | ||
|
||
If you just installed Go, make sure you also have added it to your PATH or Environment Vars (Windows). For example: | ||
|
||
``` | ||
$ export GOPATH=$HOME/go | ||
|
@@ -112,62 +111,56 @@ setx GOPATH %USERPROFILE%\go | |
<your existing PATH definitions>;%USERPROFILE%\go\bin | ||
``` | ||
|
||
If you haven't defined the PATH, the command below will fail silently, and | ||
running `docker-credential-ecr-login` will output: `command not found` | ||
If you haven't defined the PATH, the command below will fail silently, and running `docker-credential-ecr-login` will | ||
output: `command not found` | ||
|
||
You can install this via `go get` with: | ||
|
||
``` | ||
go get -u github.com/awslabs/amazon-ecr-credential-helper/ecr-login/cli/docker-credential-ecr-login | ||
``` | ||
|
||
|
||
If you already have Docker environment, just clone this repository anywhere | ||
and run `make docker`. This command builds the binary with Go inside the Docker | ||
container and output it to local directory. | ||
If you already have Docker environment, just clone this repository anywhere and run `make docker`. This command builds | ||
the binary with Go inside the Docker container and output it to local directory. | ||
|
||
With `TARGET_GOOS` environment variable, you can also cross compile the binary. | ||
|
||
Once you have installed the credential helper, see the | ||
[Configuration section](#Configuration) for instructions on how to configure | ||
Docker to work with the helper. | ||
[Configuration section](#Configuration) for instructions on how to configure 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: | ||
Place the `docker-credential-ecr-login` binary on your `PATH` and set the contents of your `~/.docker/config.json` file | ||
to be: | ||
|
||
```json | ||
{ | ||
"credsStore": "ecr-login" | ||
"credsStore": "ecr-login" | ||
} | ||
``` | ||
|
||
This configures the Docker daemon to use the credential helper for all Amazon | ||
ECR registries. | ||
This configures the Docker daemon to use the credential helper for all Amazon ECR registries. | ||
|
||
With Docker 1.13.0 or greater, you can configure Docker to use different | ||
credential helpers for different registries. To use this credential helper for | ||
a specific ECR registry, create a `credHelpers` section with the URI of your | ||
ECR registry: | ||
With Docker 1.13.0 or greater, you can configure Docker to use different credential helpers for different registries. To | ||
use this credential helper for a specific ECR registry, create a `credHelpers` section with the URI of your ECR | ||
registry: | ||
|
||
```json | ||
{ | ||
"credHelpers": { | ||
"public.ecr.aws": "ecr-login", | ||
"<aws_account_id>.dkr.ecr.<region>.amazonaws.com": "ecr-login" | ||
} | ||
"credHelpers": { | ||
"public.ecr.aws": "ecr-login", | ||
"<aws_account_id>.dkr.ecr.<region>.amazonaws.com": "ecr-login" | ||
} | ||
} | ||
``` | ||
|
||
This is useful if you use `docker` to operate on registries that use different | ||
authentication credentials. | ||
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 | ||
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`) | ||
|
@@ -176,23 +169,22 @@ include: | |
* 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. | ||
may set the `AWS_PROFILE` environment variable. | ||
|
||
The Amazon ECR Docker Credential Helper reads and supports some configuration options specified in the AWS | ||
shared configuration file (`~/.aws/config`). To disable these options, you must set the `AWS_SDK_LOAD_CONFIG` environment | ||
variable to `false`. The supported options include: | ||
The Amazon ECR Docker Credential Helper reads and supports some configuration options specified in the AWS shared | ||
configuration file (`~/.aws/config`). To disable these options, you must set the `AWS_SDK_LOAD_CONFIG` environment | ||
variable to `false`. 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 | ||
* 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*. | ||
|
||
|
@@ -207,9 +199,8 @@ The credentials must have a policy applied that | |
|
||
`docker pull public.ecr.aws/amazonlinux/amazonlinux:latest` | ||
|
||
If you have configured additional profiles for use with the AWS CLI, you can use | ||
those profiles by specifying the `AWS_PROFILE` environment variable when invoking `docker`. | ||
For example: | ||
If you have configured additional profiles for use with the AWS CLI, you can use those profiles by specifying | ||
the `AWS_PROFILE` environment variable when invoking `docker`. For example: | ||
|
||
`AWS_PROFILE=myprofile docker pull 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-repository:my-tag` | ||
|
||
|
@@ -224,9 +215,10 @@ For more information about Amazon ECR, see the the | |
|
||
## Security disclosures | ||
|
||
If you think you’ve found a potential security issue, please do not post it in the Issues. Instead, please follow the instructions [here](https://aws.amazon.com/security/vulnerability-reporting/) or [email AWS security directly](mailto:[email protected]). | ||
If you think you’ve found a potential security issue, please do not post it in the Issues. Instead, please follow the | ||
instructions [here](https://aws.amazon.com/security/vulnerability-reporting/) | ||
or [email AWS security directly](mailto:[email protected]). | ||
|
||
## License | ||
|
||
The Amazon ECR Docker Credential Helper is licensed under the Apache 2.0 | ||
License. | ||
The Amazon ECR Docker Credential Helper is licensed under the Apache 2.0 License. |