Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/GoogleCloudPlatform/docker-credential-gcr

A Docker credential helper for GCR users
https://github.com/GoogleCloudPlatform/docker-credential-gcr

compute-engine docker docker-client docker-image-registry docker-images docker-registry gcloud gcloud-sdk

Last synced: 2 months ago
JSON representation

A Docker credential helper for GCR users

Awesome Lists containing this project

README 

        



# docker-credential-gcr [![Build Status](https://github.com/GoogleCloudPlatform/docker-credential-gcr/actions/workflows/test.yml/badge.svg)](https://travis-ci.org/GoogleCloudPlatform/docker-credential-gcr) [![Go Report Card](https://goreportcard.com/badge/GoogleCloudPlatform/docker-credential-gcr)](https://goreportcard.com/report/GoogleCloudPlatform/docker-credential-gcr)



## Introduction



`docker-credential-gcr` is [Google Container Registry](https://cloud.google.com/container-registry/)'s _standalone_, `gcloud` SDK-independent Docker credential helper. It allows for **v18.03+ Docker clients** to easily make authenticated requests to GCR's repositories (gcr.io, eu.gcr.io, etc.).



**Note:** `docker-credential-gcr` is primarily intended for users wishing to authenticate with GCR in the **absence of `gcloud`**, though they are [not mutually exclusive](#gcr-credentials). For normal development setups, users are encouraged to use [`gcloud auth configure-docker`](https://cloud.google.com/sdk/gcloud/reference/auth/configure-docker), instead.



The helper implements the [Docker Credential Store](https://docs.docker.com/engine/reference/commandline/login/#/credentials-store) API, but enables more advanced authentication schemes for GCR's users. In particular, it respects [Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials) and is capable of generating credentials automatically (without an explicit login operation) when running in App Engine or Compute Engine.



For even more authentication options, see GCR's documentation on [advanced authentication methods](https://cloud.google.com/container-registry/docs/advanced-authentication).



## Installation



Download [latest release](https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/latest).



Install manually:



```

go install github.com/GoogleCloudPlatform/docker-credential-gcr/v2@latest

```



## Configuration and Usage



* Configure the Docker CLI to use `docker-credential-gcr` as a credential helper for the default set of GCR registries:



	```shell

	docker-credential-gcr configure-docker

	```



  To speed up `docker build`s, you can instead configure a minimal set of registries:



  ```shell

  docker-credential-gcr configure-docker --registries="gcr.io,us-west1-docker.pkg.dev,docker.europe-west3.rep.pkg.dev"

  ```



  * Alternatively, use the [manual configuration instructions](#manual-docker-client-configuration) below to configure your version of the Docker client.



* Log in to GCR (or don't! See the [GCR Credentials section](#gcr-credentials))



	```shell

	docker-credential-gcr gcr-login

	```



* Use Docker!



	```shell

	docker pull gcr.io/project-id/neato-container

	```



* Log out from GCR



	```shell

	docker-credential-gcr gcr-logout

	```



## GCR Credentials



_By default_, the helper searches for GCR credentials in the following order:



1. In the helper's private credential store (i.e. those stored via `docker-credential-gcr gcr-login`)

1. In a JSON file whose path is specified by the GOOGLE_APPLICATION_CREDENTIALS environment variable.

1. In a JSON file in a location known to the helper:

	* On Windows, this is `%APPDATA%/gcloud/application_default_credentials.json`.

	* On other systems, `$HOME/.config/gcloud/application_default_credentials.json`.

1. On Google App Engine, it uses the `appengine.AccessToken` function.

1. On Google Compute Engine, Kubernetes Engine, and App Engine Managed VMs, it fetches the credentials of the _service account_ associated with the VM from the metadata server (if available).



Users may limit, re-order how the helper searches for GCR credentials using `docker-credential-gcr config --token-source`. Number 1 above is designated by `store` and 2-5 by `env` (which cannot be individually restricted or re-ordered). Multiple sources are separated by commas, and the default is `"store,  env"`.



While it is recommended to use [`gcloud auth configure-docker`](https://cloud.google.com/sdk/gcloud/reference/auth/configure-docker) in `gcloud`-based work flows, you may optionally configure `docker-credential-gcr` to use `gcloud` as a token source (see example below).



**Examples:**



To use _only_ the gcloud SDK's access token:

```shell

docker-credential-gcr config --token-source="gcloud"

```



To search the environment, followed by the private store:

```shell

docker-credential-gcr config --token-source="env, store"

```



To verify that credentials are being returned for a given registry, e.g. for `https://gcr.io`:



```shell

echo "https://gcr.io" | docker-credential-gcr get

```



## Other Credentials



As of the 2.0 release, `docker-credential-gcr` no longer supports generalized [`credsStore`](https://docs.docker.com/engine/reference/commandline/login/#/credentials-store) functionality.



### Manual Docker Client Configuration



Add a `credHelpers` entry in the Docker config file (usually `~/.docker/config.json` on OSX and Linux, `%USERPROFILE%\.docker\config.json` on Windows) for each GCR registry that you care about. The key should be the domain of the registry (**without** the "https://") and the value should be the suffix of the credential helper binary (everything after "docker-credential-").



	e.g. for `docker-credential-gcr`:



  

    {

      "auths" : {

            ...

      },

      "credHelpers": {

            "coolregistry.com": ... ,

            "gcr.io": "gcr",

            "asia.gcr.io": "gcr",

            ...

      },

      "HttpHeaders": ...

      "psFormat": ...

      "imagesFormat": ...

      "detachKeys": ...

    }

  



## License



Apache 2.0. See [LICENSE](LICENSE) for more information.