Using a custom image registry

There might be reasons to pull the container images only from internal image registries, not directly from external registries like Docker Hub. To do so, follow along with this guide.

How to use your custom image registry

  1. Copy the Airlock Microgateway images into your custom image registry using CRANE or other tools that retain the original digest.

    2. In our case, run the crane tool to copy a remote image from <SRC> to <DST> while retaining the digest value.

    copy
    crane copy <SRC> <DST>
    • The digest of the Airlock Microgateway images are verified by the Microgateway Operator and, therefore cannot be modified. Since pulling and pushing the images changes the digest, a tool like CRANE must be used to transfer the images into a custom registry.
    • Besides the digest, the Microgateway Operator and the Microgateway Engine image must have the same tags. Identical tags are enforced by a validator. Mixing different versions like Microgateway Operator in version 4.0 and Microgateway Engine in version 4.1 is not supported.
  2. Adjust the following attributes in the Kubernetes Deployment airlock-microgateway-operator-controller-manager:
    • Configure the Microgateway Operator image in spec.template.spec.containers['manager'].image
    • Configure the Microgateway Engine image in spec.template.spec.containers['manager'].env['ENGINE_IMAGE']

    The Microgateway Operator will be pulled from the custom image registry. The Operator uses the environment variables and replaces the image in the corresponding container template file (see Microgateway Operator).

  3. Adjust the following attributes in the Kubernetes Deployment airlock-microgateway-license-guard:
    • Configure the License Guard image in spec.template.spec.containers['ratelimit'].image
  4. Adjust the following attributes in the Kubernetes Deployment airlock-microgateway-license-guard-redis:
    • Configure the License Guard Redis image in spec.template.spec.containers['redis'].image
  5. Adjust configuration values in the values.yaml of the CNI Helm chart. See the documentation in the values.yaml file for details.
  6. With the adjustments, the images will be used from the custom image registry.

    7. The following Kustomize example shows how the mentioned attributes can be patched:

    copy
    cat <<EOF > custom_image_registry.yaml
--- 
apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: airlock-microgateway-system 
  name: airlock-microgateway-operator-controller-manager
spec:
  template:
    spec:
      containers:
        - name: manager
          env: 
            - name: ENGINE_IMAGE 
              value: custom.image.registry/my-repository/airlock-microgateway-engine:<TAG>@sha256:<SHA256_DIGEST>
EOF


  
cat <<EOF >./kustomization.yaml
--- 
apiVersion: kustomize.config.k8s.io/v1beta1 
kind: Kustomization 
 
resources:
  - https://github.com/airlock/microgateway/deploy/deployment/?ref=main 

patches:
  - path: custom_image_registry.yaml

images:
  - name: docker.io/ergon/airlock-microgateway-operator
    newName: custom.image.registry/my-repository/airlock-microgateway-operator
  - name: docker.io/ergon/airlock-microgateway-license-guard
    newName: custom.image.registry/my-repository/airlock-microgateway-license-guard 
  - name: cgr.dev/chainguard/redis
    newName: custom.image.registry/my-repository/airlock-microgateway-redis 
EOF

    We highly suggest using the original image names to prevent confusion and only changing the image registry and repository.

    • Ensure that the replaced Airlock Microgateway images are always specified in the Kubernetes manifest files with a tag and a digest.
    • After changing any Microgateway images in the deployment files, the Microgateway Operator must be restarted.