Configuring a private Docker registry

This page explains how to configure an existing Docker registry for GKE On-Prem.


GKE On-Prem does not support unsecured Docker registries. When you start your Docker registry, you must provide a certificate and a key. The certificate can be signed by a public certificate authority (CA), or it can be self-signed.

Creating a Docker registry

To learn how to create a Docker registry, see Run an externally-accessible registry.

Configuring the registry

Your admin workstation VM must trust the CA that signed your certificate. To establish this trust, perform the following steps on your admin workstation VM:

  1. Create a directory to hold the certificate:

    sudo mkdir -p /etc/docker/certs.d/[REGISTRY_SERVER]

    where [REGISTRY_SERVER] is the IP address or hostname of the VM that runs your Docker registry.

  2. Copy your certificate file to /etc/docker/certs.d/[REGISTRY_SERVER]/ca.crt. You must name the file ca.crt, even if it had a different name originally.

  3. Restart the Docker service:

    sudo service docker restart
  4. Verify that you can log in to Docker:

    docker login -u [USERNAME] -p [PASSWORD] [REGISTRY_SERVER]

    where [USERNAME] and [PASSWORD] are the credentials for logging in to the Docker registry.

    Possible errors and solutions

    • Get https://[REGISTRY_SERVER]/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers). Make sure you have the correct IP address for the VM that runs your Docker registry.

    • login attempt to https://[REGISTRY_SERVER]/v2/ failed with status: 401 Unauthorized. Make sure your username and password are correct.

    • Get https://[REGISTRY_SERVER]/v1/users/: x509: certificate signed by unknown authority. Your admin workstation VM doesn't trust the certificate.

When you run gkectl prepare during installation, the images needed for installation are pushed to your Docker registry.


For more information, refer to Troubleshooting.