Sidecarless mode with K8s Gateway API

The CR GatewayClass describes a class of Gateways available to the user for creating Gateway resources.

Example:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: airlock-microgateway
spec:
  controllerName: microgateway.airlock.com/gatewayclass-controller
  description: GatewayClass for Airlock Microgateway.

The GatewayClass CR example contains the Airlock Microgateway controllerName.
The name must match the Microgateway Controller name configured in the Operator Helm chart (default: microgateway.airlock.com/gatewayclass-controller.

The CR Gateway represents an instance of a service-traffic handling infrastructure by binding Listeners to a set of IP addresses.

Example:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gateway-example
  namespace: example-backend-gw
spec:
  gatewayClassName: airlock-microgateway
  infrastructure:
    parametersRef:
      group: microgateway.airlock.com
      kind: GatewayParameters
      name: gateway-parameters-example
  listeners:
    - name: http
      hostname: "*.example.com"       
      port: 80
      protocol: HTTP
    - name: https
      hostname: "*.example.com"   
      port: 443
      protocol: HTTPS
      tls:
        mode: Terminate
        certificateRefs:
          - name: downstream-server-certificate
        options:  
          microgateway.airlock.com/minimumVersion: TLSv1_2 
          microgateway.airlock.com/maximumVersion: TLSv1_3

If the Airlock Microgateway Controller is configured to support the referenced GatewayClass, the following occurs:

spec.listeners.protocol

Airlock Microgateway supports the following application protocols:

microgateway.airlock.com/http3 is our implementation-specific protocol string for HTTP/3 and is considered an incubating feature. It configures the Airlock Microgateway to serve HTTP/3 on the provided port. Note that in the future this implementation-specific protocol could be replaced by a standardised protocol string from the Gateway API.

When microgateway.airlock.com/http3 is set as the protocol, the Airlock Microgateway Engine will listen on the configured ports for UDP and TCP traffic. Each response will have the Alt-Svc header set to indicate HTTP/3 support. The Service will have mixed protocols, exposing the UDP and TCP port. This can potentially be a problem when choosing to expose the Airlock Microgateway with a Service of type LoadBalancer because some cloud providers do not support Services with mixed protocols.

spec.listeners.tls.options

TLS options define a set of key and value used to extend TLS configuration Gateway resources. These list all Airlock Microgateway–specific TLS options.

For further details about the Envoy TLS settings, refer to the Envoy TLS protocol settings documentation.

Client certificate validation (downstream mTLS)

Client certificate validation ensures that only trusted clients can access a given web application or API. Properties of the client certificate can be leveraged for fine-grained access control and for propagating the user’s identity.

Prerequisite:
Client certificate validation is implemented using K8s Gateway API 1.4.x-experimental. To use this feature, you must install the Gateway API experimental channel.

This section focuses on the configuration of client certificate validation. For details on access control and identity propagation, refer to the API reference for all options, and the examples. See CR AccessControlPolicy and CR IdentityPropagation.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gateway-example
  namespace: example-backend-gw
spec:
  gatewayClassName: airlock-microgateway
  infrastructure:
    parametersRef:
      group: microgateway.airlock.com
      kind: GatewayParameters
      name: gateway-parameters-example
  listeners:
    - name: https
      hostname: "*.example.com"       
      port: 443
      protocol: HTTPS
      tls:
        mode: Terminate
        certificateRefs:
          - name: downstream-server-certificate
    - name: mtls
      hostname: "*.example.com"   
      port: 8443
      protocol: HTTPS
      tls:
        mode: Terminate
        certificateRefs:
          - name: downstream-server-certificate
  tls:
    frontend:
      default: {}
      perPort:
        - port: 8443
          tls:
            validation:
              mode: AllowValidOnly
              caCertificateRefs:
                - group: ""
                  kind: "Secret"
                  name: ca
                - group: ""
                  kind: "ConfigMap"
                  name: ca

The Gateway CR example defines two listeners. One on port 443 for standard HTTPS, and another on port 8443 with client certificate validation (mTLS) enabled. The spec.tls.frontend section contains two keys. default, which configures the behavior applied to all listeners, and perPort, which allows you to apply a port-specific TLS configuration.

This example demonstrates how to combine global and per-port TLS settings, including mTLS, on a single Gateway.

The CR HTTPRoute provides a way to route HTTP requests. This includes the capability to match requests by hostname, path, header, or query param. Filters can be used to specify additional processing steps. Backends specify where matching requests should be routed.

Example:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: backend
  namespace: example-backend-gw
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: gateway-example
  rules:
    - backendRefs:
        - group: ""
          kind: Service
          name: example-backend
          namespace: example-backend-app
          port: 8080

The CR HTTPRoute configures the routing between the Microgateway Engine Pods and back-end application(s). The example demonstrates how to configure cross-Namespace routing when the Microgateway Engine Pod and the example application Pod are in different namespaces.

The CR BackendTLSPolicy provides a way to configure how a Gateway connects to a Backend via TLS.

Example:

apiVersion: gateway.networking.k8s.io/v1alpha3 
kind: BackendTLSPolicy 
metadata:  
  name: example-backend 
  namespace: example-backend-app 
spec:  
  targetRefs:  
    - kind: Service 
      group: "" 
      name: example-backend 
      sectionName: https 
  validation:  
    hostname: backend 
    caCertificateRefs:  
      - kind: Secret 
        group: "" 
        name: example-backend-cert 
      - kind: ConfigMap 
        group: "" 
        name: kube-root-ca 
  options:  
    microgateway.airlock.com/minimumVersion: TLSv1_2
    microgateway.airlock.com/maximumVersion: TLSv1_3

spec.options

TLS options define a set of key and value used to extend TLS configuration BackendTLSPolicy resources. These list all Airlock Microgateway–specific TLS options.

spec:
  options:  
    microgateway.airlock.com/verifyCertificateHashes: |
      # Example with 64 hexadecimal characters
      df6ff72fe9116521268f6f2dd4966f51df479883fe7037b39f75916ac3049d1a

      # Example with 32 colon-separated byte pairs
      DF:6F:F7:2F:E9:11:65:21:26:8F:6F:2D:D4:96:6F:51:DF:47:98:83:FE:70:37:B3:9F:75:91:6A:C3:04:9D:1A

For further details about the Envoy TLS settings, refer to the Envoy TLS protocol settings documentation.

The CR ReferenceGrant identifies kinds of resources in other namespaces that are trusted to reference the specified kinds of resources in the same namespace as the policy.

Example:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: backend
  namespace: example-backend-app
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: example-backend-gw
  to:
    - group: ""
      kind: Service
      name: example-backend

Helm Microgateway Operator chart configuration must take place before or with installation or upgrade. The configuration can be persistently adjusted in a local values.yaml file or passed with every Helm installation using the --set option.

helm upgrade -i airlock-microgateway \
  oci://quay.io/airlockcharts/microgateway \
  --version 4.8.0 \
  -n airlock-microgateway-system \
  --wait \
  --set operator.sidecarGateway.enabled=false \
  --set operator.gatewayAPI.enabled=true \
  --set operator.gatewayAPI.podMonitor.create=true \
  --set operator.serviceMonitor.create=true \
  --set dashboards.create=true \
  --reuse-values

Any communication between containers in the airlock-microgateway-system namespace and, i.e., Microgateway Engine containers, is secured using TLS/mTLS.

During the Microgateway Operator startup, the following self-signed certificates are generated and stored as secrets in the airlock-microgateway-system namespace:

Each time an Airlock Microgateway Engine is deployed, an airlock-microgateway-bootstrap-secret is generated and saved to the Namespace of the Engine Deployment. This secret holds the required certificates and keys for mTLS-based communication between the Microgateway Engine and the Operator. The TLS certificates of the bootstrap secret are renewed automatically every 48h.