Registry

Container Registry Commands

This guide covers the displace registry commands for managing container registries in your Displace clusters. For architectural overview and concepts, see Container Registry.

Overview

flowchart LR
    subgraph commands["Registry Commands"]
        create["displace registry create"]
        status["displace registry status"]
        health["displace registry health"]
        push["displace registry push"]
        list["displace registry list"]
        gc["displace registry gc"]
        delete["displace registry delete"]
    end

    subgraph registry["k3d Registry"]
        images["Container Images"]
    end

    create -->|"Creates"| registry
    status -->|"Checks"| registry
    health -->|"Diagnoses"| registry
    push -->|"Uploads"| images
    list -->|"Queries"| images
    gc -->|"Cleans"| images
    delete -->|"Removes"| registry

Command Reference

displace registry create

Creates a new local k3d container registry for development.

Syntax:

displace registry create [name] [flags]

Flags:

Flag	Description	Default
`--port`	Port for the registry	`5000`

Examples:

# Create default registry
displace registry create

Expected output:

Creating registry: displace-registry
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Registry created successfully

Name:     k3d-displace-registry
Endpoint: k3d-displace-registry:5000
Port:     5000
Status:   running

To use this registry with a new cluster:
  k3d cluster create my-cluster --registry-use k3d-displace-registry:5000

To push images:
  displace registry push <image>

# Create registry with custom name
displace registry create my-registry

# Create registry on different port
displace registry create --port 5001

displace registry status

Shows the status and configuration of your container registry.

Syntax:

displace registry status [flags]

Flags:

Flag	Description
`--json`	Output in JSON format

Examples:

displace registry status

Expected output:

Registry Status: k3d-displace-registry
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Type:      k3d (local)
Endpoint:  k3d-displace-registry:5000
Port:      5000
Status:    ✓ running
Images:    12

To push images:
  displace registry push <image>

Or manually:
  docker tag <image> localhost:5000/<image>
  docker push localhost:5000/<image>

# JSON output for scripting
displace registry status --json

JSON output:

{
  "name": "k3d-displace-registry",
  "type": "k3d",
  "endpoint": "k3d-displace-registry:5000",
  "port": 5000,
  "status": "running"
}

displace registry health

Runs comprehensive health checks on the container registry to diagnose issues.

Syntax:

displace registry health [flags]

Flags:

Flag	Short	Description	Default
`--name`		Registry name to check	`displace-registry`
`--verbose`	`-v`	Show detailed diagnostics	`false`

Examples:

# Basic health check
displace registry health

Expected output:

Registry Health Check: k3d-displace-registry
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Container Status    Running
✅ API Accessible      http://localhost:5000/v2/
✅ Read Access         Catalog accessible
✅ Network             Reachable from cluster

All health checks passed!

# Verbose diagnostics
displace registry health --verbose

Verbose output:

Registry Health Check: k3d-displace-registry
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Container Status
  Name:       k3d-displace-registry
  Image:      registry:2
  State:      running
  Uptime:     2d 4h 32m
  ✅ PASS

API Accessibility
  Endpoint:   http://localhost:5000/v2/
  Response:   200 OK
  Latency:    2ms
  ✅ PASS

Read Access
  Catalog:    GET /v2/_catalog
  Response:   {"repositories":["myapp","wordpress"]}
  ✅ PASS

Network Connectivity
  Cluster DNS:  k3d-displace-registry:5000
  Resolution:   172.18.0.2
  Port Check:   5000/tcp open
  ✅ PASS

All health checks passed!

# Check specific registry
displace registry health --name my-registry

When health check fails:

Registry Health Check: k3d-displace-registry
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Container Status    Running
❌ API Accessible      Connection refused
⏭️  Read Access         Skipped (API unavailable)
⏭️  Network             Skipped (API unavailable)

Health check failed!

Suggested fixes:
  1. Restart the registry: docker restart k3d-displace-registry
  2. Check Docker logs: docker logs k3d-displace-registry
  3. Recreate registry: displace registry delete && displace registry create

Use cases:

Diagnosing push/pull failures
Verifying registry setup after installation
Troubleshooting network connectivity issues
Pre-deployment validation in CI/CD

displace registry push

Pushes a local Docker image to the cluster's container registry.

Syntax:

displace registry push <image> [flags]

Flags:

Flag	Description
`--cluster`	Target cluster (default: current context)

Examples:

# Push image with default tag
displace registry push myapp

Expected output:

Pushing myapp to registry: k3d-displace-registry
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Tagging image for localhost:5000...

✓ Successfully pushed myapp

Image available at:
  From host:    localhost:5000/myapp:latest
  From cluster: k3d-displace-registry:5000/myapp:latest

# Push with specific tag
displace registry push myapp:v1.0.0

# Push to specific cluster's registry
displace registry push myapp --cluster production

Behind the scenes:

Tags your local image for the registry endpoint
Pushes to localhost:5000/<image> (for local k3d)
Image becomes available at k3d-displace-registry:5000/<image> inside the cluster

displace registry list

Lists all container images stored in the registry.

Syntax:

displace registry list [flags]

Flags:

Flag	Description
`--json`	Output in JSON format

Examples:

displace registry list

Expected output:

Images in registry: k3d-displace-registry
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
REPOSITORY                     TAGS
------------------------------------------------------------
myapp                          latest, v1.0.0, v1.0.1
wordpress                      6.4, latest
laravel-app                    dev, main
static-site                    latest

# JSON output for scripting
displace registry list --json

JSON output:

[
  {
    "repository": "myapp",
    "tags": ["latest", "v1.0.0", "v1.0.1"]
  },
  {
    "repository": "wordpress",
    "tags": ["6.4", "latest"]
  }
]

displace registry gc

Runs garbage collection to clean up unused image layers and free storage space.

Syntax:

displace registry gc [flags]

Flags:

Flag	Short	Description	Default
`--dry-run`		Preview what would be deleted	`false`
`--force`	`-f`	Skip confirmation prompt	`false`

Examples:

# Dry run to see what would be cleaned
displace registry gc --dry-run

Expected output (dry run):

Registry Garbage Collection: k3d-displace-registry
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[DRY RUN] The following would be removed:

Unreferenced Blobs:
  sha256:a3ed95...  12.4 MB
  sha256:f7e294...   8.2 MB
  sha256:c1b823...  45.1 MB

Orphaned Manifests:
  myapp@sha256:old123...  (no tags)
  test-image@sha256:abc...  (no tags)

Summary:
  Blobs to remove:     3
  Manifests to remove: 2
  Space to reclaim:    65.7 MB

Run without --dry-run to perform cleanup.

# Run garbage collection
displace registry gc

Expected output:

Registry Garbage Collection: k3d-displace-registry
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️  Warning: This will permanently remove unused image layers.
    Make sure no pushes are currently in progress.

Proceed with garbage collection? (y/N): y

Analyzing registry...
  Found 3 unreferenced blobs
  Found 2 orphaned manifests

Removing unreferenced blobs...
  ✓ sha256:a3ed95...  12.4 MB
  ✓ sha256:f7e294...   8.2 MB
  ✓ sha256:c1b823...  45.1 MB

Removing orphaned manifests...
  ✓ myapp@sha256:old123...
  ✓ test-image@sha256:abc...

Garbage collection complete!
  Blobs removed:     3
  Manifests removed: 2
  Space reclaimed:   65.7 MB

# Force garbage collection without confirmation
displace registry gc --force

When nothing to clean:

Registry Garbage Collection: k3d-displace-registry
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Analyzing registry...

No garbage found! Registry is clean.
  Active images:  12
  Total size:     234.5 MB

Use cases:

Freeing disk space after many image pushes
Cleaning up old development images
Removing untagged/orphaned images
Periodic maintenance in CI/CD pipelines

Warning: Garbage collection cannot be undone. Ensure no image pushes are in progress when running this command.

displace registry delete

Deletes a local k3d container registry.

Syntax:

displace registry delete <name> [flags]

Flags:

Flag	Short	Description
`--force`	`-f`	Skip confirmation prompt

Examples:

# Delete with confirmation
displace registry delete displace-registry

Expected output:

Are you sure you want to delete registry 'displace-registry'? (y/N): y
Deleting registry: displace-registry
✓ Registry deleted successfully

# Force delete without confirmation
displace registry delete displace-registry --force

Warning: Deleting a registry removes all stored images permanently.

Common Workflows

Initial Setup

When you run displace install, a registry is created automatically:

# Registry is created during installation
displace install

# Verify registry exists
displace registry status

Build and Push Workflow

flowchart LR
    build["docker build"] --> tag["docker tag"]
    tag --> push["displace registry push"]
    push --> deploy["displace project deploy"]

# Build your application
docker build -t myapp:latest .

# Push to cluster registry
displace registry push myapp:latest

# Deploy (image is pulled from registry)
displace project deploy --cluster displace-local

Template Integration

Templates include Makefile targets that handle registry operations:

# In a template project directory
make build    # Build Docker image
make push     # Push to registry
make deploy   # Deploy to cluster

# Or all at once
make build push deploy

Using Images in Kubernetes Manifests

Reference images from the cluster registry in your manifests:

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: app
        # Use the cluster-internal endpoint
        image: k3d-displace-registry:5000/myapp:latest
        imagePullPolicy: Always

Important: Use k3d-displace-registry:5000 (not localhost:5000) in Kubernetes manifests. Pods resolve this to the registry container via k3d networking.

Best Practices

Image Tagging

# Use semantic versioning
displace registry push myapp:v1.0.0

# Include git SHA for traceability
displace registry push myapp:$(git rev-parse --short HEAD)

# Always push :latest for convenience
displace registry push myapp:latest
displace registry push myapp:v1.0.0

Regular Cleanup

Images accumulate over time. Clean up periodically:

# Check current images
displace registry list

# For complete cleanup, recreate the registry
displace registry delete displace-registry --force
displace registry create displace-registry

CI/CD Integration

#!/bin/bash
# Example CI script

# Build with unique tag
IMAGE_TAG="${CI_COMMIT_SHA:-latest}"
docker build -t myapp:$IMAGE_TAG .

# Push to registry
displace registry push myapp:$IMAGE_TAG

# Update deployment
kubectl set image deployment/myapp \
  app=k3d-displace-registry:5000/myapp:$IMAGE_TAG

Troubleshooting

Registry Not Found

Error:

No registries found. Create one with: displace registry create

Solution:

# Create the default registry
displace registry create displace-registry

# If cluster exists, connect it to the registry
# (requires cluster recreation for k3d)
k3d cluster delete displace-local
displace cluster create displace-local --provider local

Push Fails

Error:

failed to push image: ...

Solutions:

Check registry is running:

displace registry status
docker ps | grep registry

Verify image exists locally:
```
docker images | grep myapp
```
Check Docker daemon:
```
docker info
```
Restart registry if needed:
```
docker restart k3d-displace-registry
```

Image Not Found in Cluster

Error in pod:

Failed to pull image "k3d-displace-registry:5000/myapp:latest": ...

Solutions:

Verify image was pushed:
```
displace registry list
```

Check image reference in manifest:

# Correct (cluster-internal)
image: k3d-displace-registry:5000/myapp:latest

# Wrong (host-only)
image: localhost:5000/myapp:latest

Test registry from inside cluster:

kubectl run test --rm -it --image=busybox -- \
  wget -qO- http://k3d-displace-registry:5000/v2/_catalog

Registry Status Shows "Not Running"

Solution:

# Check Docker container
docker ps -a | grep registry

# Start if stopped
docker start k3d-displace-registry

# Or recreate
displace registry delete displace-registry --force
displace registry create displace-registry

Registry

Container Registry Commands

Overview

Command Reference

displace registry create

displace registry status

displace registry health

displace registry push

displace registry list

displace registry gc

displace registry delete

Common Workflows

Initial Setup

Build and Push Workflow

Template Integration

Using Images in Kubernetes Manifests

Best Practices

Image Tagging

Regular Cleanup

CI/CD Integration

Troubleshooting

Registry Not Found

Push Fails

Image Not Found in Cluster

Registry Status Shows "Not Running"

Related Documentation

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Getting Started

Providers

Templates

Development

Guides

Infrastructure

Reference

Clone this wiki locally