TECH **Docker Hub & Private Registries: Push, Pull, Tagging – Zero-Fluff Study Guide**

Docker Hub & Private Registries: Push, Pull, Tagging – Zero-Fluff Study Guide

1. What This Is & Why It Matters

You’re a DevOps engineer deploying microservices to Kubernetes. Your team builds Docker images in CI/CD, but when you try to deploy, the cluster can’t pull the image. Logs show:

Failed to pull image "myapp:v2": rpc error: code = Unknown desc = Error response from daemon: pull access denied for myapp, repository does not exist or may require 'docker login'

Why? You forgot to push the image to a registry, or you tagged it incorrectly.

Docker Hub and private registries (like AWS ECR, Google GCR, or self-hosted Harbor) are the central storage for your container images—like GitHub for code, but for Docker. If you don’t master tagging, pushing, and pulling, your deployments will fail silently, your CI/CD pipelines will break, and you’ll waste hours debugging "image not found" errors.

Real-world scenario:
- You inherit a legacy app with hardcoded latest tags in Kubernetes manifests. A bad deploy overwrites the image, and now all environments are broken because latest is mutable.
- Your company enforces image scanning for vulnerabilities. If you push to Docker Hub (public), you expose proprietary code. If you use a private registry, you must authenticate securely.
- You’re on-call, and a production pod crashes. You need to roll back to a known-good image—but only if you tagged it properly.

This guide teaches you: ✅ How to tag images for immutability (no more latest disasters).
✅ How to push/pull from Docker Hub and private registries (AWS ECR, GCR, etc.).
✅ How to securely authenticate without leaking credentials.
✅ How to debug registry issues in Kubernetes.

2. Core Concepts & Components

1. Docker Image

• A read-only template with your app and dependencies (e.g., nginx:1.25).
• Production insight: If you don’t pin versions (nginx:1.25 vs nginx:latest), a bad deploy can break everything.

2. Docker Tag

• A label for an image (e.g., myapp:v1.2.3). Defaults to latest if omitted.
• Production insight: Always use semantic versioning (v1.2.3) or Git SHAs (myapp:abc123)—never latest in production.

3. Docker Registry

• A server that stores Docker images (like Docker Hub, AWS ECR, or self-hosted Harbor).
• Production insight: Public registries (Docker Hub) are not secure for proprietary code—use private registries for internal apps.

4. Docker Hub

• The default public registry (like GitHub for Docker images).
• Production insight: Rate-limited (100 pulls/6 hours for free accounts). Enterprise plans remove limits.

5. Private Registry

• A self-hosted or cloud-based registry (AWS ECR, Google GCR, Azure ACR, Harbor).
• Production insight: Private registries require authentication—leaking credentials can lead to supply-chain attacks.

6. Image Naming Convention

• Format: [REGISTRY/]REPO[:TAG] or [REGISTRY/]REPO[@DIGEST].
• nginx:1.25 (Docker Hub, no registry prefix)
• 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:v1 (AWS ECR)
• Production insight: Kubernetes requires the full registry path (e.g., 123456789012.dkr.ecr...).

7. Image Digest

• A unique SHA256 hash of an image (e.g., sha256:abc123...).
• Production insight: Digests are immutable—use them for secure rollbacks (unlike tags, which can be overwritten).

8. docker login

• Authenticates you with a registry (stores credentials in ~/.docker/config.json).
• Production insight: Never hardcode credentials in CI/CD—use IAM roles (AWS) or Kubernetes secrets.

9. docker push / docker pull

• push: Uploads an image to a registry.
• pull: Downloads an image from a registry.
• Production insight: If you don’t tag correctly, push will fail with denied: requested access to the resource is denied.

10. Kubernetes ImagePullSecrets

• A Kubernetes secret that stores registry credentials (used in pod.spec.imagePullSecrets).
• Production insight: Without this, Kubernetes can’t pull private images.

3. Step-by-Step Hands-On: Push, Pull, and Tag Like a Pro

Prerequisites

• Docker installed (docker --version).
• A Docker Hub account (or AWS/GCP/Azure account for private registries).
• A simple app (e.g., Dockerfile with FROM nginx:alpine).

Task 1: Build and Tag an Image Properly

Goal: Build an image with a semantic version tag (not latest).

1. Build with a tag:
   bash
docker build -t myapp:v1.0.0 .
2. -t = tag (format: name:tag).

3. . = build context (current directory).

4. Verify the tag:
   bash
docker images | grep myapp
   Expected output:
   REPOSITORY TAG IMAGE ID CREATED SIZE
myapp v1.0.0 abc123def456 2 minutes ago 23MB

5. Tag the same image with multiple names (e.g., for different registries):
   bash
docker tag myapp:v1.0.0 mydockerhubusername/myapp:v1.0.0
docker tag myapp:v1.0.0 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:v1.0.0

6. This doesn’t duplicate the image—just adds aliases.

7. Verify all tags:
   bash
docker images | grep myapp
   Expected output:
   myapp v1.0.0 abc123def456 5 minutes ago 23MB
mydockerhubusername/myapp v1.0.0 abc123def456 5 minutes ago 23MB
123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp v1.0.0 abc123def456 5 minutes ago 23MB

Task 2: Push to Docker Hub (Public Registry)

Goal: Push an image to Docker Hub and pull it from another machine.

1. Log in to Docker Hub:
   bash
docker login
2. Enter your Docker Hub username/password.

3. Credentials are stored in ~/.docker/config.json.

4. Push the image:
   bash
docker push mydockerhubusername/myapp:v1.0.0

5. If you get denied: requested access to the resource is denied, you forgot to tag with your username.

6. Verify on Docker Hub:

7. Go to https://hub.docker.com/r/mydockerhubusername/myapp/tags.

8. You should see v1.0.0.

9. Pull the image from another machine:
   bash
docker pull mydockerhubusername/myapp:v1.0.0

Task 3: Push to AWS ECR (Private Registry)

Goal: Push an image to AWS ECR and configure Kubernetes to pull it.

Step 1: Create an ECR Repository

1. Go to AWS ECR → Create repository → Name: myapp.
2. Note the repository URI (e.g., 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp).

Step 2: Authenticate Docker with ECR

1. Install AWS CLI (if not installed):
   bash
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install
2. Configure AWS credentials:
   bash
aws configure
3. Enter your AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
4. Log in to ECR:
   bash
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com
5. This temporarily stores credentials in ~/.docker/config.json.

Step 3: Tag and Push to ECR

1. Tag the image for ECR:
   bash
docker tag myapp:v1.0.0 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:v1.0.0
2. Push to ECR:
   bash
docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:v1.0.0
3. Verify in AWS Console:
4. Go to ECR → myapp → Images.
5. You should see v1.0.0.

Step 4: Configure Kubernetes to Pull from ECR

1. Create an imagePullSecret for ECR:
   bash
kubectl create secret docker-registry ecr-creds \
--docker-server=123456789012.dkr.ecr.us-east-1.amazonaws.com \
--docker-username=AWS \
--docker-password=$(aws ecr get-login-password --region us-east-1) \
[email protected]
2. Deploy a pod using the secret:
   ```yaml
   # pod.yaml
   apiVersion: v1
   kind: Pod
   metadata:
   name: myapp
   spec:
   containers:
   • name: myapp
     image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:v1.0.0 imagePullSecrets:
   • name: ecr-creds
     ```
3. Apply the pod:
   bash
kubectl apply -f pod.yaml
4. Verify the pod is running:
   bash
kubectl get pods

4. ? Production-Ready Best Practices

Security

• Never use latest in production—it’s mutable and can break deployments.
• Rotate registry credentials (AWS IAM roles, Kubernetes secrets).
• Scan images for vulnerabilities (AWS ECR scanning, Trivy, Clair).
• Use image digests (myapp@sha256:abc123...) for immutable deployments.

Cost Optimization

• Clean up untagged images (AWS ECR lifecycle policies, docker system prune).
• Use private registries for internal apps (Docker Hub has rate limits).
• Cache images in CI/CD (e.g., GitHub Actions actions/cache).

Reliability & Maintainability

• Tag images with Git SHAs (myapp:abc123) for traceability.
• Use semantic versioning (v1.2.3) for controlled rollouts.
• Document registry paths (e.g., 123456789012.dkr.ecr...).

Observability

• Monitor registry pull counts (AWS CloudWatch, Prometheus).
• Log failed pulls (Kubernetes events: kubectl describe pod myapp).
• Set up alerts for rate limits (Docker Hub, ECR).

5. ⚠️ Common Mistakes & Traps

6. ? Exam/Certification Focus

Typical Question Patterns

1. "You need to deploy a private image to Kubernetes. What’s missing?"
2. Answer: imagePullSecrets in the pod spec.

3. Trap: Forgetting to create the secret first.

4. "How do you make an image immutable?"

5. Answer: Use digests (myapp@sha256:abc123...) instead of tags.

6. Trap: Tags can be overwritten; digests cannot.

7. "You get denied: requested access to the resource is denied when pushing. What’s wrong?"

8. Answer: You forgot to docker login or tagged incorrectly (missing registry prefix).

9. Trap: Assuming docker push myapp:v1 works without a registry.

10. "How do you authenticate Docker with AWS ECR?"

11. Answer: aws ecr get-login-password | docker login --username AWS --password-stdin <ECR_URI>.
12. Trap: Using docker login with a password instead of AWS CLI.

7. ? Hands-On Challenge

Challenge:
You have a Docker image myapp:v1 built locally. Push it to both Docker Hub and AWS ECR, then deploy it to Kubernetes using imagePullSecrets.

Solution:

# 1. Tag for Docker Hub
docker tag myapp:v1 mydockerhubusername/myapp:v1

# 2. Push to Docker Hub
docker login
docker push mydockerhubusername/myapp:v1

# 3. Tag for AWS ECR
docker tag myapp:v1 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:v1

# 4. Authenticate and push to ECR
aws ecr get-login-password | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com
docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:v1

# 5. Create Kubernetes secret
kubectl create secret docker-registry ecr-creds \
  --docker-server=123456789012.dkr.ecr.us-east-1.amazonaws.com \
  --docker-username=AWS \
  --docker-password=$(aws ecr get-login-password) \
  [email protected]

# 6. Deploy pod
kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: myapp
spec:
  containers:
  - name: myapp
    image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:v1
  imagePullSecrets:
  - name: ecr-creds
EOF

Why it works:
- Proper tagging ensures the image is pushed to the correct registry.
- imagePullSecrets allows Kubernetes to authenticate with ECR.

8. ? Rapid-Reference Crib Sheet

9. ? Where to Go Next

• Docker Hub Documentation
• AWS ECR Documentation
• Kubernetes imagePullSecrets
• Harbor (Self-Hosted Registry)