Authenticating to Registries

In this guide, you’ll learn how to:

• Pull images from public and private registries
• Authenticate with docker login
• Retag (rename) images
• Push images to private registries
• Inspect actual disk usage with Docker

1. Pulling Images from a Public Registry

Pulling from a public registry (for example, the official Ubuntu image on Docker Hub) requires no authentication:

docker pull ubuntu

2. Accessing Private Repositories

Attempting to pull an image from a private registry without logging in will result in an access denied error:

docker pull gcr.io/organization/ubuntu

Using default tag: latest
Error response from daemon: pull access denied for gcr.io/organization/ubuntu, repository does not exist or may require 'docker login': denied: requested access to the resource is denied

Similarly, pushing without authentication will fail:

docker push ubuntu

The push refers to repository [docker.io/library/ubuntu]
128fa0b0fb81: Layer already exists
c0151ca45f27: Layer already exists
b2fd17df2071: Layer already exists
[DEPRECATION NOTICE] registry v2 schema1 support will be removed...
errors:
  denied: requested access to the resource is denied
  unauthorized: authentication required

3. Logging In to a Registry

Use docker login to authenticate. By default, it targets Docker Hub (docker.io).

docker login docker.io

Example:

Username: registry-user
Password:
WARNING! Your password will be stored unencrypted in /home/vagrant/.docker/config.json.
Login Succeeded

For other registries such as Google Container Registry:

docker login gcr.io

Once logged in, subsequent docker pull and docker push commands will use your credentials.

4. Retagging (Renaming) an Image

Docker images cannot be renamed directly. Instead, you can create a new tag—a “soft link” to the same image ID.

1. List local images:

   docker image ls
   

2. Retag httpd:alpine to httpd:customv1:

   docker image tag httpd:alpine httpd:customv1
   

3. Confirm the new tag:

   docker image ls
   

Example output:

REPOSITORY  TAG        IMAGE ID       CREATED       SIZE
httpd       alpine     52862a02e4e9   2 weeks ago   112MB
httpd       customv1   52862a02e4e9   2 weeks ago   112MB
httpd       latest     c2aa7e16edd8   2 weeks ago   165MB
ubuntu      latest     549b9b86cb8d   4 weeks ago   64.2MB

Notice httpd:alpine and httpd:customv1 share the same IMAGE ID—no duplicate layers are created.

5. Pushing to a Private Registry

To push your retagged image:

docker image tag httpd:customv1 gcr.io/organization/httpd:customv1
docker push gcr.io/organization/httpd:customv1

Make sure you are logged in (docker login gcr.io) before pushing.

6. Checking Actual Disk Usage

Use docker system df to inspect disk usage across images, containers, volumes, and build cache:

docker system df

Example:

TYPE                TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images              3         0         341.9MB   341.9MB (100%)
Containers          0
Local Volumes       0
Build Cache         0

Even if docker image ls lists four tags, docker system df shows only three unique images. The SIZE column reflects unique layers, and RECLAIMABLE indicates potential space savings.

Command Reference Table

Links and References

• Docker CLI Reference
• Docker Hub Documentation
• Google Container Registry Auth