Use a Registry Mirror

Registry mirrors are local copies of images from a public registry that follows (or mirrors) the file structure of a public registry. You can push container images to a local registry from downloaded images or images that you create with the Konvoy Image Builder. If your environment allows Internet access, when an image is not found locally, the mirror registry would then consult its upstream registries. This kind of registry does not contain any images other than the ones requested.

Export Variables

Set the environment variable with your registry information.

CODE

export REGISTRY_URL="<https/http>://<registry-address>:<registry-port>"
export REGISTRY_USERNAME=<username>
export REGISTRY_PASSWORD=<password>
export REGISTRY_CA=<path to the cacert file on the bastion>

Definitions:

REGISTRY_URL: the address of an existing local registry accessible in the VPC that the new cluster nodes will be configured to use a mirror registry when pulling images.
- EX: https://registry.example.com

Other local registries may use the options below:

REGISTRY_USERNAME: optional-set to a user that has pull access to this registry.
REGISTRY_PASSWORD: optional if username is not set.
JFrog - REGISTRY_CA: (optional) the path on the bastion machine to the registry CA. This value is only needed if the registry is using a self-signed certificate and the AMIs are not already configured to trust this CA.
To increase Docker Hub's rate limit use your Docker Hub credentials when creating the cluster, by setting flags --registry-mirror-url=https://registry-1.docker.io --registry-mirror-username=<your-username> --registry-mirror-password=<your-password> when running dkp create cluster.

Use Flags in Cluster Creation

If you set the --registry-mirror flag during cluster creation, the Kubelet will now send to requests to the dynamic-credential-provider with a different config. Only use one image registry per cluster.

To apply private registry configurations during the dkp cluster create operation, add the appropriate flags to the command:

Registry configuration	Flag
CA certificate chain to use while communicating with the registry mirror using Transport Layer Security(TLS)	`--registry-mirror-cacert file`
URL of a container registry to use as a mirror in the cluster	`--registry-mirror-url string` OR apply variable `${REGISTRY_URL}`
Set to a user that has pull access to this registry	`--registry-mirror-username string` OR apply variable `${REGISTRY_USERNAME}`
Password to authenticate the registry mirror	`--registry-mirror-password string` OR apply variable `${REGISTRY_PASSWORD}`

This is useful when using an internal registry and when Internet access is not available such as in an air-gapped environment. However, registry mirrors can be used in non-air-gapped environments as well for security and speed.

AWS ECR - Adding the mirror flags to EKS would enable new clusters to also use ECR as image mirror. If you set the --registry-mirror flag, the Kubelet will now send to requests to the dynamic-credential-provider with a different config. You can still pull your own images from ECR directly or use ECR as a mirror.

When the cluster is up and running, you can deploy and test workloads.

Registry Mirror Cluster Example

Selecting your provider, run:

CODE

dkp create cluster [aws, azure, gcp, preprovisoned, vsphere] \
    --cluster-name=${CLUSTER_NAME} \
    --registry-mirror-cacert /tmp/registry.pem \
    --registry-mirror-url=${REGISTRY_URL}

More information is found in the Custom Installation and Additional Infrastructure Tools sections under the Create a New Cluster section of each Infrastructure Provider. Mirrors can be used in both air-gapped and non-air-gapped environments by adding the flag to the dkp create cluster command.