Install and Upgrade in SUSE Rancher

Airlock Microgateway is published as a partner chart for SUSE Rancher. The instructions below cover the required steps to install and upgrade the Airlock Microgateway Operator in a cluster managed by SUSE Rancher Manager.

Prerequisites

A valid license is required to use Airlock Microgateway unless you use the Community Edition. To try premium features without first contacting a sales partner, request an evaluation license. For a comparison of the available editions, see Editions.

Request one of the following licenses

  • Request an evaluation license.

    • The license is sent automatically within a few minutes.

  • Request a premium license.

    • A sales partner will contact you to discuss licensing.

Install

Deploy Kubernetes Gateway API CRDs

Airlock Microgateway requires the Kubernetes Gateway API CRDs. SUSE K3s and RKE2 bundle these CRDs with Traefik when it is used as the ingress controller. Starting with version 1.37 of K3s and RKE2, however, the CRDs are installed separately using the bundled gateway-api-crd or rke2-gateway-api-crd chart.

Caution
  • A cluster upgrade may bump the bundled Gateway API CRDs to a version the installed Airlock Microgateway release does not support. The Airlock Microgateway Operator then rejects the Gateway API resources: configuration changes are no longer applied, and restarted Gateways no longer serve traffic.
    • Before upgrading the cluster, verify that the new CRD version is within the supported version range. If not, upgrade Airlock Microgateway first, or disable the bundled chart and manage the CRDs yourself as described below.

Manual installation of the CRDs is required in the following cases:

  • The cluster is not K3s or RKE2, or the CRDs are not managed by the cluster and therefore missing.
  • You need a different CRD version or the experimental channel required for incubating features. In this case, first disable the bundled chart by disabling the AddOn gateway-api-crd on K3s or rke2-gateway-api-crd on RKE2. For instructions, see Disabling Manifests in the K3s documentation or Disabling Server Charts in the RKE2 documentation.

To install the CRDs manually, run the following command:

​
1

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

kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.0/experimental-install.yaml
Info

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

Deploy Airlock Microgateway license

If you use the Community Edition, you can skip license deployment.

  1. Create the airlock-microgateway-system namespace:

    1

    kubectl create namespace airlock-microgateway-system

  2. 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:

    1
2
3

    kubectl create secret generic airlock-microgateway-license \
  -n airlock-microgateway-system \
  --from-file=microgateway-license.txt=<path-to-your-local-microgateway-license.txt>
Notice

For more information about license monitoring, see Monitor Microgateway Licenses.

Deploy Airlock Microgateway Operator

CRDs are included via the standard Helm 3 mechanism, i.e., Helm will handle initial installation but not upgrades.

  1. In Rancher Manager, click ☰ > Cluster Management, then click Explore for the cluster on which you want to install Airlock Microgateway.

  2. In the left navigation, click Apps > Charts. Set the repository filter to Partners, then select the Airlock Microgateway chart.

  3. Select the chart version you want to install, then click Install.

  4. Select airlock-microgateway-system as the namespace, then click Next.

  5. Review the chart values, then click Install.

    Notice

    When license.mode is set to required, the Operator rejects gateways without a valid license. A missing or misconfigured license can therefore prevent a gateway from being deployed.

    • To prevent gateways from being rejected, verify that a valid Premium license is configured before setting license.mode to required.
    • Use optional only if you intentionally want the Operator to fall back to the Community Edition when no license is configured.

    Rancher deploys the chart, then opens Apps > Installed Apps. The airlock-microgateway app should display the state Deployed and the newly installed chart version.`

What’s next

  1. Gateway Deployment
    • Deploy the gateway either as an Ingress or as an in-cluster Gateway.
  2. Session Handling
    • Enable session handling to persist session information and correlate requests with a session ID. This is a prerequisite for OIDC-based authentication.
  3. Configuration Guides
    • Learn how to use Airlock Microgateway for other typical scenarios such as request routing, request filtering or authentication enforcement.

Upgrade

The following instructions explain how to upgrade running Airlock Microgateway deployments to a newer version without interrupting service.

Notice
  • These instructions may not apply when upgrading to an Airlock Microgateway release that contains breaking changes. Additional upgrade steps may be required.
  • Rancher displays the default values for the new chart version and overlays the customized values from the installed release. Settings renamed in the new chart version are carried over under their old names and are therefore ignored. As a result, the intended custom configuration is not applied.
    • Before upgrading, identify any renamed settings and transfer their values to the new setting names.

  1. On clusters that bundle the Gateway API CRDs, the CRDs are upgraded during the cluster upgrade. If you manage the CRDs yourself, follow the instructions in the Upgrading to a new version section of the official Gateway API CRD Management Guide.

    In most cases, you can upgrade the CRDs using one of the following commands, depending on the installed Gateway API channel:

    ​
    1

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

    kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.0/experimental-install.yaml

  2. In Rancher Manager, click ☰ > Cluster Management, then click Explore for the cluster on which you want to upgrade Airlock Microgateway.

  3. Rancher does not automatically upgrade the CRDs associated with installed apps. To upgrade the Airlock Microgateway CRDs manually, click Kubectl Shell in the header, then run the following command using the chart version to which you are upgrading.

    1
2
3
4

    helm show crds microgateway \
  --version 5.2.0 \
  --repo https://github.com/rancher/partner-charts/raw/main |
  kubectl apply --server-side --force-conflicts -f -

  4. To upgrade the Airlock Microgateway Operator, click Apps > Installed Apps in the left navigation.

    • Note: If a newer chart version is available, it is displayed for the airlock-microgateway app in the Upgradable column.

  1. Click the version to open the upgrade page

  2. Review the chart values, then click Upgrade.

    Rancher upgrades the chart, then opens the detail page for the airlock-microgateway app. It should display the state Deployed.

External links: