Configure use of your image registry

Big picture

Configure Calico to pull images from a registry (public or private).

Value

In many deployments, installing Calico in clusters from third-party private repos is not an option. Calico offers these public and private registry options, which can be used in any combination:

  • Install from a registry for use cases like air-gapped clusters, or clusters with bandwidth or security constraints
  • Install from an image path in a registry if you have pulled Calico images to a sub path in your registry
  • Install images by registry digest

Concepts

A container image registry (often known as a registry), is a service where you can push, pull, and store container images. In Kubernetes, a registry is considered private if it is not publicly available.

A private registry requires an image pull secret. An image pull secret provides authentication for an image registry; this allows you to control access to certain images or give access to higher pull rate limits (like with DockerHub).

An image path is a directory in a registry that contains images required to install Calico.

Before you begin

Required

  • Calico is managed by the operator
  • Configure pull access to your registry
  • If you are using a private registry that requires user authentication, ensure that an image pull secret is configured for your registry in the tigera-operator namespace. Set the environment variable, REGISTRY_PULL_SECRET to the secret name. For help, see imagePullSecrets and registry fields, in Installation resource reference.
  • Use the Crane command to manage the Calico for Windows images, as using docker pull commands for these images may not work depending on the operating system and version in which the commands are run.

How to

The following examples show the path format for public and private registry, $REGISTRY/. If you are using an image path, substitute the format: $REGISTRY/$IMAGE_PATH/.

Push Calico images to your registry

To install images from your registry, you must first pull the images from Tigera’s registry, retag them with your own registry, and then push the newly-tagged images to your own registry. Use the crane cp command instead of pulling+retagging+pushing on the Calico for Windows images (node-windows and cni-windows).

  1. Use the following commands to pull the required Calico images.
  1. docker pull quay.io/tigera/operator:v1.32.10
  2. docker pull calico/typha:v3.27.4
  3. docker pull calico/ctl:v3.27.4
  4. docker pull calico/node:v3.27.4
  5. docker pull calico/cni:v3.27.4
  6. docker pull calico/apiserver:v3.27.4
  7. docker pull calico/kube-controllers:v3.27.4
  8. docker pull calico/dikastes:v3.27.4
  9. docker pull calico/pod2daemon-flexvol:v3.27.4
  10. docker pull calico/csi:v3.27.4
  11. docker pull calico/node-driver-registrar:v3.27.4
  1. Retag the images with the name of your registry $REGISTRY.
  1. docker tag quay.io/tigera/operator:v1.32.10 $REGISTRY/tigera/operator:v1.32.10
  2. docker tag calico/typha:v3.27.4 $REGISTRY/calico/typha:v3.27.4
  3. docker tag calico/ctl:v3.27.4 $REGISTRY/calico/ctl:v3.27.4
  4. docker tag calico/node:v3.27.4 $REGISTRY/calico/node:v3.27.4
  5. docker tag calico/cni:v3.27.4 $REGISTRY/calico/cni:v3.27.4
  6. docker tag calico/apiserver:v3.27.4 $REGISTRY/calico/apiserver:v3.27.4
  7. docker tag calico/kube-controllers:v3.27.4 $REGISTRY/calico/kube-controllers:v3.27.4
  8. docker tag calico/dikastes:v3.27.4 $REGISTRY/calico/dikastes:v3.27.4
  9. docker tag calico/pod2daemon-flexvol:v3.27.4 $REGISTRY/calico/pod2daemon-flexvol:v3.27.4
  10. docker tag calico/csi:v3.27.4 $REGISTRY/calico/csi:v3.27.4
  11. docker tag calico/node-driver-registrar:v3.27.4 $REGISTRY/calico/node-driver-registrar:v3.27.4
  1. Push the images to your registry.
  1. docker push $REGISTRY/tigera/operator:v1.32.10
  2. docker push $REGISTRY/calico/typha:v3.27.4
  3. docker push $REGISTRY/calico/ctl:v3.27.4
  4. docker push $REGISTRY/calico/node:v3.27.4
  5. docker push $REGISTRY/calico/cni:v3.27.4
  6. docker push $REGISTRY/calico/apiserver:v3.27.4
  7. docker push $REGISTRY/calico/kube-controllers:v3.27.4
  8. docker push $REGISTRY/calico/dikastes:v3.27.4
  9. docker push $REGISTRY/calico/pod2daemon-flexvol:v3.27.4
  10. docker push $REGISTRY/calico/csi:v3.27.4
  11. docker push $REGISTRY/calico/node-driver-registrar:v3.27.4
  1. Use crane cp to copy the Windows images to your private registry.

For hybrid Linux + Windows clusters, use crane cp on the following Windows images to copy them to your private registry.

  1. crane cp calico/node-windows:v3.27.4 $REGISTRY/calico/node-windows:v3.27.4
  2. crane cp calico/cni-windows:v3.27.4 $REGISTRY/calico/cni-windows:v3.27.4

Run the operator using images from your registry

Before applying tigera-operator.yaml, modify registry references to use your custom registry:

For OpenShift

Download all manifests first, then modify the following:

  1. sed -ie "s?quay.io?$REGISTRY?g" manifests/02-tigera-operator.yaml

For all other platforms

  1. sed -ie "s?quay.io?$REGISTRY?g" tigera-operator.yaml

Next, if you are implementing user authentication to access a private registry, add the image pull secret for your registry to the secret tigera-pull-secret.

  1. sed -ie "/serviceAccountName: tigera-operator/a \      imagePullSecrets:\n\      - name: $REGISTRY_PULL_SECRET"  tigera-operator.yaml

Configure the operator to use images

Set the spec.registry field of your Installation resource to the name of your custom registry. For example:

  1. apiVersion: operator.tigera.io/v1
  2. kind: Installation
  3. metadata:
  4.   name: default
  5. spec:
  6.   variant: Calico
  7.   imagePullSecrets:
  8.     - name: tigera-pull-secret
  9.   registry: myregistry.com