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 airgapped 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.

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.

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

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