Installation-related instructions

This article covers general installation-related tasks. Additionally, mind the installation modes described in the article Sidecar-based mode installation types.

Brief installation information may also be found on our Microgateway GitHub page and Microgateway Artifact Hub page.

Installation in Kubernetes

Prerequisites

General:
A valid license is required. Airlock Microgateway is available in a Premium and a free Community edition. See the article Configuration and monitoring of licenses.
Choose the required installation mode according to the article Sidecar-based mode installation types.

Environment-dependent configuration:
For Kubernetes with Istio Service Mesh or Cilium, see section Integration with service meshes.
For sidecar-based deployments, choose the required installation mode according to the article Sidecar-based mode installation types.

Installation preparation

Both modes of installation, sidecar-based and sidecarless, can be either exclusive or combined. In the case of a combination, both installation preparations must be carried out.

Install a cert-manager

You can install the cert-manager with the commands below in the 'VERSION' you wish to install. You may use the latest cert-manager version (see official cert-manager Helm installation instructions), which should work fine in most cases.

# Add the cert-manager repository and perform a Helm-based installation
helm repo add jetstack https://charts.jetstack.io 
helm install cert-manager jetstack/cert-manager --version 'VERSION' -n cert-manager --create-namespace --set crds.enabled=true --wait

Sidecar-based preparations

For sidecar-based data plane mode deployments, install the CNI DaemonSet and required RBAC (Role Based Access Control) manifests using our Helm charts.

CNI Helm charts are available here:
Airlock Microgateway Helm charts on GitHub
Airlock Microgateway Helm charts on Artifact Hub

We offer Helm value files for CNI installations on GKE/OpenShift:
gke-values.yaml (on GitHub)
openshift-values.yaml (on GitHub)

The default values have been tested in our installation environments. However, some values may need to be adapted to meet the requirements of your setup environment. Path information for the CNI config files and binaries can either be found in the documentation of your Kubernetes distribution or CNI provider or queried with the following commands.

The cniNetDir, the directory of the CNI config files on the host, can be queried with:

crictl info -o go-template --template '{{.config.cni.confDir}}'

The cniBinDir, the directory of the CNI plugin binaries on the host, can be queried with:

crictl info -o go-template --template '{{.config.cni.binDir}}'

Installation procedure:
Adapt and run the following command with the current CNI Helm chart version.

helm install airlock-microgateway-cni -n kube-system oci://quay.io/airlockcharts/microgateway-cni --version 4.5.0

Wait for the Airlock Microgateway CNI DaemonSet to be up and running.

kubectl -n kube-system rollout status daemonset -l app.kubernetes.io/instance=airlock-microgateway-cni

Verify the correctness of the installation with helm test.

helm upgrade airlock-microgateway-cni -n kube-system oci://quay.io/airlockcharts/microgateway-cni --set tests.enabled=true --reuse-values --version 4.5.0

Check the log messages.

helm test airlock-microgateway-cni -n kube-system --logs

On successful installation, the logs should show the message Success. If the installation was not successful, go to Troubleshooting Microgateway CNI Helm test for troubleshooting.
Disable the helm test deployment afterward.

helm upgrade airlock-microgateway-cni -n kube-system oci://quay.io/airlockcharts/microgateway-cni --set tests.enabled=false --reuse-values --version 4.5.0

Sidecarless preparations

The sidecarless data plane mode installation of Airlock Microgateway requires installing the K8s Gateway API standard channel v1.2.1.

Run the following command:

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/standard-install.yaml

Wait until the required CRDs for K8s Gateway API usage have been installed.
Example:

customresourcedefinition.apiextensions.k8s.io/gatewayclasses.gateway.networking.k8s.io created 
customresourcedefinition.apiextensions.k8s.io/gateways.gateway.networking.k8s.io created 
customresourcedefinition.apiextensions.k8s.io/grpcroutes.gateway.networking.k8s.io created 
customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.io created 
customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking.k8s.io created

More details, including release notes and upgrade information, can be found in the official Kubernetes Gateway API installation documentation.

Install the Airlock Microgateway Operator

Create the airlock-microgateway-system namespace.

kubectl create namespace airlock-microgateway-system

Store the license in the Microgateway Operator namespace, in a Kubernetes secret with the name airlock-microgateway-license and the key microgateway-license.txt. Use the following command:

kubectl -n airlock-microgateway-system create secret generic airlock-microgateway-license  
--from-file=microgateway-license.txt=<my-local-microgateway-license.txt>

Depending on your installation preparations, adapt and run one of the following command with the current Airlock Microgateway Operator Helm chart version. This will install airlock-microgateway in the airlock-microgateway-system namespace.

When the K8s Gateway API resources have been installed during preparation, run:

helm install -n airlock-microgateway-system airlock-microgateway oci://quay.io/airlockcharts/microgateway --wait --version 4.5.0 --set=operator.gatewayAPI.enabled=true

Else, run:

helm install -n airlock-microgateway-system airlock-microgateway oci://quay.io/airlockcharts/microgateway --wait --version 4.5.0

During installation, the installation status is echoed – i.e., the preliminary cleanup task and scaling the test installation to only 1 replica (to ensure no pods from previous runs are present).

The logs should show the message Thank you for installing Airlock Microgateway. ... including further information on successful installation.

Additional testing for sidecar-based or mixed installations

Helm-based testing is available for the sidecar-based mode of exclusively sidecar-based or mixed installation.

Verify the correctness of the installation with helm test.

helm upgrade airlock-microgateway -n airlock-microgateway-system oci://quay.io/airlockcharts/microgateway --set tests.enabled=true --reuse-values --version 4.5.0

Check the log messages.

helm test airlock-microgateway -n airlock-microgateway-system --logs

On successful installation, the logs should show the following message: ### Installation of 'airlock-microgateway' succeeded. If the installation was not successful, go to Troubleshooting Microgateway Operator Helm test for troubleshooting.
Disable the helm test deployment afterward.

helm upgrade airlock-microgateway -n airlock-microgateway-system oci://quay.io/airlockcharts/microgateway --set tests.enabled=false --reuse-values --version 4.5.0

Explanation: By using the --reuse-values setting, the --set=operator.gatewayAPI.enabled=true setting of mixes installation preparations is retained.

Installation in OpenShift

To install the certified Airlock Microgateway Operator, visit the Red Hat Operator Hub in the web console on your OpenShift cluster or the Red Hat Ecosystem Catalog and install the Operator from there. You can find the required installation information directly on the Red Hat platforms.

Airlock Microgateway - Red Hat Ecosystem Catalog nu

CNI installation for sidecar mode installations

Disclaimer

Airlock Microgateway installations in sidecar mode require the installation of the Airlock CNI Plugin which is not certified by Red Hat. If you require a fully certified installation, you must choose the sidecarless mode for OpenShift.

Prerequisites

Choose the required installation mode according to the article Sidecar-based mode installation types.

Environment-dependent configuration

The Airlock Microgateway CNI Plugin requires specific environment settings:
The default Security Context Constraint (SCC) privileged provides sufficient rights and can be used for the serviceAccount. For further information consult the OpenShift website (Default security context constraints).
For sidecar-based deployments, all pods protected by Airlock Microgateway must explicitly reference the Airlock Microgateway CNI NetworkAttachmentDefinition via the annotation k8s.v1.cni.cncf.io/networks.

Microgateway CNI installation

Install the CNI DaemonSet and required RBAC (Role Based Access Control) manifests using our Helm charts. The default values have been tested in our installation environments.

Airlock Microgateway CNI Helm charts are available here:
Airlock Microgateway Helm charts on GitHub
Airlock Microgateway Helm charts on Artifact Hub

We recommend installing the CNI plugin into the namespace openshift-operators instead of kube-system.

Privileged access is required to install the CNI plugin on the node. In OpenShift, this may lead to a warning if the label pod-security.kubernetes.io/warn: privileged is not set for the OpenShift operator namespace during the CNI helm install process. For the related OpenShift documentation, see Managing pod security admission in OpenShift.

Installation procedure:
Adapt and run the following command with the current CNI helm chart version from GitHub or a local version of the openshift-values.yaml file.

helm install airlock-microgateway-cni -n openshift-operators oci://quay.io/airlockcharts/microgateway-cni -f https://github.com/airlock/microgateway/tree/4.5.0/deploy/charts/airlock-microgateway-cni/openshift-values.yaml --version 4.5.0

Wait for the Airlock Microgateway CNI Plugin to be up and running.

kubectl -n openshift-operators rollout status daemonset -l app.kubernetes.io/instance=airlock-microgateway-cni

Verify the correctness of the installation with helm test.

helm upgrade airlock-microgateway-cni -n openshift-operators oci://quay.io/airlockcharts/microgateway-cni --set tests.enabled=true --reuse-values --version 4.5.0

Check the log messages.

helm test airlock-microgateway-cni -n openshift-operators --logs

On successful installation, the logs should show Success.
Disable the helm test deployment afterwards.

helm upgrade airlock-microgateway-cni -n openshift-operators  oci://quay.io/airlockcharts/microgateway-cni --set tests.enabled=false --reuse-values --version 4.5.0

What's next

Append default/airlock-microgateway-cni in the annotation k8s.v1.cni.cncf.io/networks of the web application Pod to allow the Microgateway CNI plugin work together with OpenShift Multus. For example: k8s.v1.cni.cncf.io/networks: [<network>,...],default/airlock-microgateway-cni. For further information, consider Adding a pod to an additional network in OpenShift.
Label the web application Pods to protect as explained in Annotations for the Microgateway Operator.

Integration with Service Meshes

To use Airlock Microgateway in your Kubernetes or OpenShift cluster with Istio, follow this guide to deploy the Airlock Microgateway Operator and its resources in sidecar-based data plane mode.

Current limitations:
Istio Ambient Mode is not supported.

Kubernetes with Istio Service Mesh

The Istio Service Mesh must be deployed as described in their documentation (Istio) Documentation.
Ensure that the Microgateway Operator and Microgateway CNI plugin do not have Istio injected – neither through labeling the namespace nor with the corresponding annotation.
For more information, consult (Istio) Sidecar injection.
Depending on which Kubernetes distribution you are using, complete the instructions according to the corresponding installation environment (e.g. Openshift).
If Istio meshConfig.outboundTrafficPolicy.mode is set to the non-default value REGISTRY_ONLY, create the resources ServiceEntry with the ports described in Network communication to allow network traffic to the services.

Example:

apiVersion: networking.istio.io/v1 
kind: ServiceEntry 
metadata: 
  name: airlock-microgateway-operator-xds 
  namespace: airlock-microgateway-system 
spec: 
  hosts: 
    - "airlock-microgateway-operator-xds.airlock-microgateway-system.svc.cluster.local" 
  location: MESH_EXTERNAL 
  ports: 
    - number: 13377 
      name: grpc 
      protocol: TLS 
  resolution: DNS

Additional configuration for sidecar-based mode

In case Istio is configured for mTLS and with rewriteAppHTTPProbers disabled, exclude probes and metrics endpoints reserved by Airlock Microgateway:

annotations:
  traffic.sidecar.istio.io/excludeInboundPorts: "19001, 19002, 19004"

When Istio is configured to rewrite the probes endpoints, it adds the environment variable ISTIO_KUBE_APP_PROBERS to the container. This variable contains the original probes' endpoint of the container. A missing environment variable ISTIO_KUBE_APP_PROBERS indicates that Istio couldn't rewrite the probes endpoint or is disabled at all.

OpenShift Service Mesh

To install OpenShift Service Mesh, install the Red Hat OpenShift Service Mesh Operator first. Then install the Airlock Microgateway Operator on the OpenShift container platform and create a ServiceMeshControlPlane resource to deploy the control plane.

The OpenShift Service Mesh must be deployed as described in their documentation official OpenShift Service Mesh documentation.
For sidecar-based installations: Ensure that the Microgateway Operator and Microgateway CNI plugin do not have Istio injected – neither through labeling the namespace nor with the corresponding annotation.
For more information, consult (OSM) Sidecar Injection.
If Istio meshConfig.outboundTrafficPolicy.mode is set to the non-default value REGISTRY_ONLY, create the resources ServiceEntry with the ports described in Network communication to allow network traffic to the services.

Example:

apiVersion: networking.istio.io/v1 
kind: ServiceEntry 
metadata: 
  name: airlock-microgateway-operator-xds 
  namespace: airlock-microgateway-system 
spec: 
  hosts: 
    - "airlock-microgateway-operator-xds.airlock-microgateway-system.svc.cluster.local" 
  location: MESH_EXTERNAL 
  ports: 
    - number: 13377 
      name: grpc 
      protocol: TLS 
  resolution: DNS

Additional configuration for sidecar-based mode

In case OpenShift Service Mesh is configured for mTLS and with rewriteAppHTTPProbers disabled, exclude probes and metrics endpoints reserved by Airlock Microgateway:

annotations:
  traffic.sidecar.istio.io/excludeInboundPorts: "19001, 19002, 19004"

When OpenShift Service Mesh is configured to rewrite the probes endpoints, it adds the environment variable ISTIO_KUBE_APP_PROBERS to the container. This variable contains the original probes' endpoint of the container. A missing environment variable ISTIO_KUBE_APP_PROBERS indicates that Istio couldn't rewrite the probes endpoint or is disabled at all.

Google Cloud Service Mesh

For installation, follow the official Google Cloud Service Mesh documentation. Generic setup information for different use cases can also be found in the official documentation.

The Google Cloud Service Mesh must be deployed as described in their documentation official Google Cloud Service Mesh documentation.
Ensure that the Microgateway Operator and Microgateway CNI plugin do not have Istio injected – neither through labeling the namespace nor with the corresponding annotation.
For more information, consult (OSM) Sidecar Injection.
If Istio meshConfig.outboundTrafficPolicy.mode (either in the IstioOperator or in the ConfigMap equivalent) is set to the non-default value REGISTRY_ONLY, create the resources ServiceEntry with the ports described in Network communication to allow network traffic to the services.

Example:

apiVersion: networking.istio.io/v1 
kind: ServiceEntry 
metadata: 
  name: airlock-microgateway-operator-xds 
  namespace: airlock-microgateway-system 
spec: 
  hosts: 
    - "airlock-microgateway-operator-xds.airlock-microgateway-system.svc.cluster.local" 
  location: MESH_EXTERNAL 
  ports: 
    - number: 13377 
      name: grpc 
      protocol: TLS 
  resolution: DNS

Additional configuration for sidecar-based mode

In case Google Cloud Service Mesh is configured for mTLS and with rewriteAppHTTPProbers disabled, exclude probes and metrics endpoints reserved by Airlock Microgateway:

annotations:
  traffic.sidecar.istio.io/excludeInboundPorts: "19001, 19002, 19004"

When Google Cloud Service Mesh is configured to rewrite the probes endpoints, it adds the environment variable ISTIO_KUBE_APP_PROBERS to the container. This variable contains the original probes' endpoint of the container. A missing environment variable ISTIO_KUBE_APP_PROBERS indicates that Istio couldn't rewrite the probes endpoint or is disabled at all.

Cilium Service Mesh

Install Cilium according to the documentation (Cilium) Documentation.

For Airlock Microgateway installations in sidecar-based mode:
Set the Helm value cni.exclusive to false for the Microgateway CNI plugin to work correctly.
Currently we do not support the kube-proxy replacement because we use iptables.

For installations with K8s Gateway API, no special settings are required.

Depending on which Kubernetes distribution you are using, complete the instructions according to the corresponding installation environment (e.g. Openshift).
Test Cilium. Use the Cilium CLI tool to verify connectivity.

cilium connectivity test

Cilium CNI forwards the traffic and is visible using Hubble, and Airlock Microgateway should be up and running.

Cleanup after installation tests

CNI and operator test pods are not automatically uninstalled after test completion. We recommend uninstalling them after testing, even if they are inactive and do not require any resources.

Delete the CNI test Pods.

kubectl delete pod -n kube-system -l "app.kubernetes.io/instance=airlock-microgateway-cni,app.kubernetes.io/component=test-install"

Delete the Operator test Pods.

kubectl delete pod -n airlock-microgateway-system -l "app.kubernetes.io/instance=airlock-microgateway,app.kubernetes.io/component=test-install"

To remove remaining test resources, run:

helm upgrade airlock-microgateway -n airlock-microgateway-system --set tests.enabled=false --reuse-values oci://quay.io/airlockcharts/microgateway --version '<installed-version>'
helm upgrade airlock-microgateway-cni -n kube-system --set tests.enabled=false --reuse-values oci://quay.io/airlockcharts/microgateway-cni --version '<installed-version>'

Uninstalling Airlock Microgateway

Airlock Microgateway can be uninstalled using helm commands. However, helm does not support removing installed CRDs, which requires using kubectl delete commands to complete the uninstallation process.

sidecar.microgateway.airlock.com/inject from your applications and make sure they are restarted.
Uninstall the Microgateway Operator.

helm uninstall -n airlock-microgateway-system airlock-microgateway

Uninstall the Microgateway CRDs.

Before uninstalling the CRDs make sure that no other Airlock Microgateway installation is existing.

kubectl delete -k "https://github.com/airlock/microgateway/deploy/charts/airlock-microgateway/crds/?ref=<installed-release-version>"

Depending on the installed data plane mode, sidecar-based with CNI plugin or K8s Gateway API based, you must uninstall the Microgateway CNI plugin or the Gateway API CRDs.

CNI plugin uninstallation:

helm uninstall -n kube-system airlock-microgateway-cni

K8s Gateway API uninstallation:

Make sure other deployments do not use the Gateway API resources.

kubectl delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/{installed_version}/standard-install.yaml

Further information and links