harbor registry

docker run --rm -it registry.ghost-prod.alphabravo.io/ghost-base/harbor-registry:<tag> --help

Common harbor-registry use cases

Run with configuration file

harbor-registry requires a configuration file to run and provides the Docker Distribution v2 registry API.

# Run with a configuration file (daemon mode with port mapping)
docker run -d --name harbor-registry \
  -p 5000:5000 \
  -v $(pwd)/config.yml:/etc/registry/config.yml \
  registry.ghost-prod.alphabravo.io/ghost-base/harbor-registry:<tag> \
  serve /etc/registry/config.yml

# Test registry API
curl http://localhost:5000/v2/

Available harbor-registry options

The harbor-registry service provides these options:

# Main command:
# registry serve <config> - Serve the registry API
# registry --help         - Show help information

Run as a daemon service

docker run -d --name harbor-registry \
  -p 5000:5000 \
  -v $(pwd)/config.yml:/etc/registry/config.yml \
  registry.ghost-prod.alphabravo.io/ghost-base/harbor-registry:<tag> \
  serve /etc/registry/config.yml

# Test registry API
curl http://localhost:5000/v2/

Harbor deployment integration

harbor-registry is commonly used as part of Harbor deployments. Here's how to integrate with Helm:

# Override Harbor chart to use DHI image in values.yaml
registry:
  registry:
    image:
      repository: registry.ghost-prod.alphabravo.io/ghost-base/harbor-registry
      tag: <tag>
      pullPolicy: IfNotPresent

# Helm install with DHI harbor-registry
# Currently Harbor does not provide arm64 compatible images, so only amd64
# deployments are possible.
helm repo add harbor https://helm.goharbor.io
helm install my-harbor harbor/harbor \
  --set registry.registry.image.repository=registry.ghost-prod.alphabravo.io/ghost-base/harbor-registry \
  --set registry.registry.image.tag=<tag>

Local development and testing

Use harbor-registry for local development and testing:

# Run with config file for testing
docker run --rm -v $(pwd)/config.yml:/etc/registry/config.yml \
  registry.ghost-prod.alphabravo.io/ghost-base/harbor-registry:<tag> \
  serve /etc/registry/config.yml

# Show help
docker run --rm registry.ghost-prod.alphabravo.io/ghost-base/harbor-registry:<tag> --help

Non-hardened images vs Ghost hardened images

Key differences

Why no shell or package manager?

Ghost hardened images prioritize security through minimalism:

• Reduced attack surface: Fewer binaries mean fewer potential vulnerabilities
• Immutable infrastructure: Runtime containers shouldn't be modified after deployment
• Compliance ready: Meets strict security requirements for regulated environments

Hardened image debugging

The hardened images intended for runtime don't contain a shell nor any tools for debugging. The recommended method for debugging applications built with Ghost hardened images is to use Docker Debug to attach to these containers. Docker Debug provides a shell, common debugging tools, and lets you install other tools in an ephemeral, writable layer that only exists during the debugging session.

For example, you can use Docker Debug:

docker debug registry.ghost-prod.alphabravo.io/ghost-base/harbor-registry:<tag>

Differences from upstream

The Ghost hardened image differs from the upstream goharbor/registry-photon image in several ways:

Entrypoint and custom CA certificate installation

Upstream behavior:

• Uses an entrypoint script (/home/harbor/entrypoint.sh) that:
  • Automatically installs custom CA certificates from /etc/harbor/ssl and /harbor_cust_cert directories
  • Appends these certificates to the system CA bundle
  • Then executes the registry binary

DHI behavior:

• Runs the binary directly (/usr/local/bin/registry) without the entrypoint wrapper
• Does not automatically install custom CA certificates

Workaround for custom CA certificates:

If you need to use custom CA certificates, you have several options:

1. Use an init container (Kubernetes):

   initContainers:
     - name: install-certs
       image: registry.ghost-prod.alphabravo.io/ghost-base/busybox:1
       command:
         - sh
         - -c
         - |
           if [ -d /etc/harbor/ssl ]; then
             find /etc/harbor/ssl -name ca.crt -exec cat {} \; >> /shared-ca-bundle/ca-bundle.crt
           fi
           if [ -d /harbor_cust_cert ]; then
             find /harbor_cust_cert -name "*.crt" -o -name "*.ca" -o -name "*.pem" | while read f; do
               [ -f "$f" ] && cat "$f" >> /shared-ca-bundle/ca-bundle.crt
             done
           fi
       volumeMounts:
         - name: harbor-ssl
           mountPath: /etc/harbor/ssl
           readOnly: true
         - name: harbor-cust-cert
           mountPath: /harbor_cust_cert
           readOnly: true
         - name: shared-ca-bundle
           mountPath: /shared-ca-bundle
   containers:
     - name: registry
       image: registry.ghost-prod.alphabravo.io/ghost-base/harbor-registry:<tag>
       env:
         - name: SSL_CERT_FILE
           value: /shared-ca-bundle/ca-bundle.crt
       volumeMounts:
         - name: shared-ca-bundle
           mountPath: /shared-ca-bundle
   volumes:
     - name: harbor-ssl
     - name: harbor-cust-cert
     - name: shared-ca-bundle
       emptyDir: {}
   

2. Mount certificates and set SSL_CERT_FILE (Docker/Docker Compose):

   services:
     registry:
       image: registry.ghost-prod.alphabravo.io/ghost-base/harbor-registry:<tag>
       environment:
         SSL_CERT_FILE: /etc/ssl/certs/ca-certificates.crt
       volumes:
         - ./custom-certs:/custom-certs:ro
         - ./ca-bundle.crt:/etc/ssl/certs/ca-certificates.crt:ro
   

3. Build a custom image with certificates pre-installed:

   FROM registry.ghost-prod.alphabravo.io/ghost-base/harbor-registry:<tag>
   COPY custom-certs/*.crt /usr/local/share/ca-certificates/
   USER root
   RUN update-ca-certificates
   USER nonroot
   

Healthcheck

Upstream: Includes a built-in healthcheck that tests the registry HTTP endpoint.

DHI: Does not include a healthcheck. You should define your own healthcheck in your Kubernetes configuration:

Kubernetes example:

livenessProbe:
  httpGet:
    path: /v2/
    port: 5000
  initialDelaySeconds: 30
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /v2/
    port: 5000
  initialDelaySeconds: 5
  periodSeconds: 5

Volumes

Upstream: Declares /storage as a volume in image metadata.

DHI: Does not include volume declarations. Ensure you explicitly mount any required storage paths (such as /storage) in your deployment configuration.

Binary naming

Upstream: The registry binary is named registry_DO_NOT_USE_GC to warn against using the registry's built-in garbage collection (Harbor manages GC through registryctl instead).

DHI: The binary is named registry without the GC warning suffix.

Image variants

Ghost hardened images come in different variants depending on their intended use.

• Runtime variants are designed to run your application in production. These images are intended to be used either directly or as the FROM image in the final stage of a multi-stage build. These images typically:

  • Run as the nonroot user
  • Do not include a shell or a package manager
  • Contain only the minimal set of libraries needed to run the app

• Build-time variants typically include dev in the variant name and are intended for use in the first stage of a multi-stage Dockerfile. These images typically:

  • Run as the root user
  • Include a shell and package manager
  • Are used to build or compile applications

• FIPS variants include fips in the variant name and tag. They come in both runtime and build-time variants. These variants use cryptographic modules that have been validated under FIPS 140, a U.S. government standard for secure cryptographic operations. For example, usage of MD5 fails in FIPS variants.

To view the image variants and get more information about them, select the Tags tab for this repository, and then select a tag.

Migrate to a Ghost hardened image

To migrate your application to a Ghost hardened image, you must update your Kubernetes manifests or Docker configurations. At minimum, you must update the base image in your existing deployment to a Ghost hardened image. This and a few other common changes are listed in the following table of migration notes.

The following steps outline the general migration process.

1. Find hardened images for your Harbor deployment.

   A hardened image may have several variants. Inspect the image tags and find the image variant that meets your needs. The harbor-registry service is typically used as part of Harbor registry deployments.

2. Update your Harbor Helm chart configurations.

   Update the image references in your Helm values or Harbor deployment configurations to use the hardened images:

   • From: goharbor/registry-photon:<tag>
   • To: registry.ghost-prod.alphabravo.io/ghost-base/harbor-registry:<tag>

3. For custom Harbor deployments, update the base image in your manifests.

   If you're building custom Harbor deployments, ensure that your registry pod uses the hardened harbor-registry as the registry container image.

4. Update configuration file mounting.

   Ensure your deployments properly mount configuration files that harbor-registry needs. The service requires access to registry configuration through proper volume mounting.

5. Test Harbor functionality.

   After migration, verify that registry operations, health checks, and other Harbor functions continue to work correctly with the hardened image. Test the /v2/ endpoint and image push/pull operations.

Troubleshoot migration

The following are common issues that you may encounter during migration.

General debugging

The hardened images intended for runtime don't contain a shell nor any tools for debugging. The recommended method for debugging applications built with Ghost hardened images is to use Docker Debug to attach to these containers. Docker Debug provides a shell, common debugging tools, and lets you install other tools in an ephemeral, writable layer that only exists during the debugging session.

Permissions

By default image variants intended for runtime, run as the nonroot user. Ensure that necessary files and directories are accessible to the nonroot user. You may need to copy files to different directories or change permissions so your application running as the nonroot user can access them.

harbor-registry requires read access to configuration files and may need write access to registry storage directories. Ensure your volume mounts and file permissions allow the nonroot user to access these files when running in containers.

Privileged ports

Non-dev hardened images run as a nonroot user by default. As a result, applications in these images can't bind to privileged ports (below 1024) when running in Kubernetes or in Docker Engine versions older than 20.10. Harbor registry typically uses port 5000 which is not privileged.

No shell

By default, image variants intended for runtime don't contain a shell. Use dev images in build stages to run shell commands and then copy any necessary artifacts into the runtime stage. In addition, use Docker Debug to debug containers with no shell.

Entry point

Ghost hardened images may have different entry points than images such as Docker Official Images. Use docker inspect to inspect entry points for Ghost hardened images and update your Dockerfile if necessary.