Kubernetes Gateway API Custom Resources

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.

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 Kubernetes 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/v1 
kind: BackendTLSPolicy 
metadata:  
  name: example-backend 
  namespace: example-backend-app 
spec:  
  targetRefs:  
    - kind: Service 
      group: core
      name: example-backend 
      sectionName: https 
  validation:  
    hostname: backend 
    wellKnownCACertificates: "System"
  options:  
    microgateway.airlock.com/minimumVersion: TLSv1_2
    microgateway.airlock.com/maximumVersion: TLSv1_3

spec.validation.wellKnownCACertificates

Airlock Microgateway supports the following values for wellKnownCACertificates:

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