Docker Registry Proxy

An authenticating Docker Registry proxy with transparent Kubernetes integration.

This project provides a proxy to a Docker Registry with support for arbitrary authentication. We desire managed private Docker Registries, such as Google Container Registry (GCR), Amazon Elastic Container Registry (ECR), Private Docker Hub,, etc., as they are much cheaper to set-up, manage and reliably scale. However, authentication and access control options for these are limited.

With this in mind, some use-cases of this Docker Registry Proxy are:

  • Provide users your own domain to pull Docker images from e.g. docker pull, is much nicer to use than docker pull
  • Provide arbitrary authentication for pulling Docker images from your registries. e.g. Hosted registries such as GCR and ECR only allow access to private registries via Service Accounts, Roles, or static credentials; this presents a key-management issue and/or ties client authentication to your cloud provider. The Docker Registry Proxy has a pluggable authentication mechanism, allowing you to implement arbitrary authentication flows. e.g. LDAP, OAuth2, OIDC, etc.
  • Provide access to a single source of private Docker images from multiple cloud providers via Instance Identity Documents. The Kubelet Image Service makes this possible with Kubernetes clusters.

Kubelet Image Service

The Kubelet Image Service is designed to be the endpoint for the --image-service-endpoint flag in kubelet to directly intercept and transparently add arbitrary authentication when pulling Docker images in Kubernetes. This flag was merged in Aug 2016, so expected it to be available from K8s 1.5+. Using this, you no longer need to rely on imagePullSecrets which requires static credentials.

This is deployed in a container via a DaemonSet, thus requires access to the hostPath: /var/run/docker.sock to interact with the Docker Engine on the node.

Managed Kubernetes

In most managed kubernetes offerings, it is difficult to modify the kubelet flags. The GKE documentation recommends making host image modifications via a DaemonSet. This section lists the DaemonSet workarounds used for each Cloud Service Provider (CSP).

Google Kubernetes Engine (GKE) and Amazon Elastic Kubernetes Engine (EKS)

The DaemonSet updates /etc/systemd/system/kubelet.service on the host (using hostPath mounts) and then restarts kubelet via systemd (using hostPath mounts to /run/systemd).