Container Registry

This section provides information about deploying a container registry.

Fabric can make use of existing container registries with authentication handled through Kubernetes. In addition, a default container registry (Docker) is packaged with the Fabric Helm chart and can be configured to use Fabric as its authentication provider.

About Container Images

A container image represents binary data that encapsulates an application and all its software dependencies. Container images are executable software bundles that can run standalone and that make very well defined assumptions about their runtime environment. You typically create a container image of your application and push it to a registry before referring to it in a Pod.

Fabric does not directly communicate with the container registry. Communication is accomplished between Kubernetes/Platform and the established registry.

Using an Existing Registry

Ensure your cluster (and namespaces: cortex and cortex-compute) have valid permissions to pull images from your registry.

You must configure the container registry settings on all namespaces in Kubernetes.

Docker Registry Options

The Fabric Helm chart includes the docker-registry Helm chart packaged as a subchart (accessible at https://private-registry.${DOMAIN}).

Disable Cortex provided Private Registry

To disable the default registry provided by the Fabric Helm chart set the following option either on the Helm CLI or in the override yaml for the Fabric deployment:

docker-registry:
  enabled: false

Configure Explicit Username and Password Authentication

To configure the Fabric Helm chart to deploy a Docker registry that uses specified hard-coded username and password:

1. Create explicit username(s) and password(s) to access the registry and encode them with htpasswd in the values.yaml under docker-registry.secrets.htpasswd (this can be a multiline string with multiple user/passwords defined):

   htpasswd -Bbn ${USER} ${PASSWORD}

2. Set up override config (values.yaml) for the Fabric Helm chart accordingly:

   docker-registry:
     enabled: true
     secrets:
       # output of `htpasswd -Bbn ${USER} ${PASSWORD}`
       htpasswd: |
        docker:$2y$05$PzEimMd4LakK2m81gPWjguvG0dL45ZFfg0cMwAzx8VcFwTBEBM2z2
     persistence:
       enabled: true
       size: 100Gi

NOTE

To allow any user to push and pull images from the Docker registry, do not set a value for docker-registry.secrets.htpasswd; this deploys the registry without auth enabled.

Configure Docker Registry with Fabric Token Auth

To configure the Docker registry packaged with Fabric to use Fabric as the authentication provider for the registry, use the following settings:

docker-registry:
  configData:
    auth:
      token:
        realm: 'https://api.{{BASE_DOMAIN}}/fabric/v4/docker/authenticate'

This allows users to authenticate against the registry using the Fabric CLI command cortex docker login.

NOTE

To authenticate to the CLI, users obtain a PAT (Personal Access Token) from the Fabric Console Settings page.

Configure Kubernetes-Docker Registry Auth

Create a Kubernetes secret to allow pulling Docker images from the deployed Docker registry (or use instruction/script from install doc step #4).

kubectl create secret docker-registry ${SECRET_NAME:-docker-login-pr} \
  --docker-server=https://private-registry.${DOMAIN} \
  --docker-username=$USERNAME \
  --docker-password=$PASSWORD \
  -n cortex

This docker-registry secret type must be set as the ImagePullSecret on any Kubernetes resources launched in order to authenticate against the registry. In order to avoid appending the ImagePullSecret on each pod or template you can associate the imagePullSecret with the default service account in all namespaces (cortex and cortex-compute):

kubectl patch sa default -n $NAMESPACE -p "imagePullSecrets":[{"name":"${SECRET_NAME:-docker-login-pr}" }]