Skip to main content
Version: V1-Next

Private Registry Support

Pulling from private Registry​

CIVITAS/CORE provides support for using a private container registry as an alternative to public registries such as Docker Hub. This feature enhances security and control over the image lifecycle by enabling internal hosting and management of container images.

Global Use of the Private Registry​

Once the private registry functionality is enabled, all container images used within the deployment will be pulled exclusively from the configured private registry. This ensures consistency and avoids reliance on public repositories during runtime.

Supported Image Reference Schemes​

CIVITAS/CORE deployments support the following configurations for referencing container images within a private registry:

  • Original Image Reference:
    docker.io/apache/superset:4.1.2
  • Alternative 1: Flat Structure
    registry.intern/apache/superset:4.1.2
    All container images are mirrored directly under the root path of the private registry. This flat structure simplifies references and is ideal when no logical separation by folder is needed.
  • Alternative 2: Folder-based Structure
    registry.intern/folder/apache/superset:4.1.2
    In this configuration, images are mirrored into a specific subfolder of the registry. All image paths must include the same folder prefix consistently. This structure is suitable for grouping or separating images by environment, project, or team.

Image Pull Secret Configuration​

To authenticate against the private registry, an image pull secret must be configured as part of the deployment. This secret contains the necessary credentials and is referenced during pod scheduling and image pull operations. The required parameters (e.g., registry URL, username, password/token) are managed centrally in the deployment inventory.

Harbor Integration for Image Replication​

To facilitate a self-hosted registry setup, CIVITAS/CORE uses Harbor — an open-source registry that supports advanced features like image replication, RBAC, and vulnerability scanning.

Harbor Replication Requirements​

To mirror images into Harbor from external registries, the following must be configured:

  1. Registry Definitions: Define source registries from which Harbor can pull images.
  2. Replication Rules: Set up per-image rules for pulling and tagging.
  3. Target Project: Define the destination "project" inside Harbor that will receive the images.

For a detailed walkthrough on how to configure these settings in Harbor, consult the Harbor Administration Documentation.

Manual Steps (If Required)​

If credentials are required to access source registries, they must be manually configured in Harbor. Refer to the official guide here:
Create Replication Endpoints

CIVITAS/CORE Automation: Harbor Playbook​

To automate the Harbor configuration and image replication process, CIVITAS/CORE provides an Ansible playbook civitas-core/tools/harbor-playbook.yml

Execution Command​

Run the playbook from the root directory of the CIVITAS/CORE repository:

ansible-playbook -i <inventory> -l localhost tools/harbor-playbook.yml

See the Inventory Customization Guide for the needed customizing.