Microgateway configuration in sidecarless mode with K8s Gateway API

In the sidecar-based K8s Gateway API data plane mode, the Microgateway Operator monitors and reconfigures the Microgateway Engine Pods whenever a K8s Gateway API CRs (e.g. Gateway or HTTPRoute, etc.) changes. The same happens when a ContentSecurityPolicy with additional Microgateway CRs is deployed to customize/extend the built-in Airlock Microgateway security, e.g., by adding custom deny rules or additional limits.

Configuration examples of K8s Gateway API CRs

Configured CR

Description

GatewayClass

Our example GatewayClass CR 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.

For more information about the GatewayClass CR, see the official documentation of the GatewayClass.

Example:

copy
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: airlock-microgateway
spec:
  controllerName: microgateway.airlock.com/gatewayclass-controller
  description: This is an example GatewayClass.

Gateway

Our example Gateway CR contains the target namespace for the Microgateway Engine Pod and other details. , the name of the Microgateway Engine Pod, and the Namespace in which this Pod will be deployed.

For another example, see the official example for a simple Gateway.

Example:

copy
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gateway-example
  namespace: example-backend-gw
spec:
  gatewayClassName: airlock-microgateway
  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 
          microgateway.airlock.com/ciphers: ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-ECDSA-AES256-GCM-SHA384

In spec.listeners.tls.options, TLS protocol versions and ciphers can be set. For more details, see Envoy documentation of common TLS configuration.

HTTPRoute

The HTTPRoute CR configures the routing between the Microgateway Engine Pods and back-end application(s). As our example with different Namespaces for the Microgateway Engine Pod and the example application Pod demonstrates, cross-Namespace-routing can be configured.

To secure your back-end application(s), you must configure the incoming traffic to be routed through the Microgateway Engine Pod. We strongly recommend testing your routing configuration by generating test requests and checking the Access Log.

Airlock Microgateway does currently not support Listener Isolation. For more information, see the official documentation on Listener Isolation.

For more information about the HTTPRoute CR, see the official documentation of the HTTPRoute.

Example:

copy
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

ReferenceGrant

Cross-namespace routing can be configured, for example, with a ​ReferenceGrant CR​. In the spec section of the following example, we allow routing access from the example-backend-gw Namespace to the example-backend-app Namespace.

For more information, see the official documentation of the ReferenceGrant.

Example:

copy
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

BackendTLSPolicy

This is an incubating feature as described in the article Release notes and incubating features in Airlock Microgateway.

The BackendTLSPolicy is a Direct Attached Policy providing a way to configure how the Airlock Microateway Engine connects to a Backend via TLS. This policy must reside in the same namespace as the associated Service.

  • The BackendTLSPolicy supports one of the following configuration options:
  • CACertificateRefs
    • This CR specifies one or more Kubernetes ConfigMap or Secret resources that contain the CA certificate for verifying the identity of the Backend server. The CA certificate must be stored in a key named ca.crt in a PEM-encoded format within the referenced ConfigMap or Secret.
  • WellKnownCACertificates
    • Instructs the Airlock Microateway Engine to use a set of trusted CA certificates, known as System certificates when verifying the identity of the Backend server.

Only one of CACertificateRefs or WellKnownCACertificates may be specified. See also official BackendTLSPolicy documentation for configuration details.

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 
    microgateway.airlock.com/ciphers: ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-ECDSA-AES256-GCM-SHA384

In spec.options, TLS protocol versions and ciphers can be set. For more details, see Envoy documentation of common TLS configuration.

Configuration examples of Airlock Microgateway CRs

Configured CR

Description

ContentSecurityPolicy

To implement custom deny rules, limits, etc., a CR ContentSecurityPolicy can be added. This CR is a Direct Policy Attachment for the K8s Gateway API. It allows adding Airlock Microgateway-specific CRs to secure web applications in a K8s Gateway API-based data plane mode. It does so by referencing various other CRs covering different customized web application security aspects.

Airlock Microgateway uses a security-by-default strategy and will apply the built-in security measures to traffic routed between the Microgateway Engine Pod and any back-end application. However, in some situations, such as initial application integration, it can be helpful to disable the built-in security measures temporarily. This can be done by setting up a ContentSecurityPolicy with unsecured: {}.

For an example configuration, see CR ContentSecurityPolicy reference documentation.

AccessControlPolicy

The CR AccessControlPolicy is a Direct Attached Policy for the K8sGateway API. It specifies the options to perform access control with an Airlock Microgateway.

  • Configuration hints:
  • A SessionHandlingRef in the CR GatewayParameters selects the default CR SessionHandling configuration for the Gateway.

For an example configuration, see CR AccessControlPolicy reference documentation.

GatewayParameters

The CR GatewayParameters defines the configuration settings for deploying a gateway in a Kubernetes cluster, including options for logging, Service type, deployment strategy, and resource management.
It can be referenced by either the K8s Gateway API CRs GatewayClass or Gateway.

More specific GatewayParameters take precedence, e.g., if a Gateway references GatewayParameters, the parameters from its associated GatewayClass are completely overridden without merging.

Session handling configuration

Session handling must be configured for OIDC authentication and access control functionality. A Microgateway Session Agent is automatically injected into the Microgateway Engine deployment. The Session Agent handles the session store connection to the Redis database, which caches the session information. Access control requires session handling, including a Redis deployment ( as a session store. Configuration is done in the CRDs CR RedisProvider and CR SessionHandling.

Further configuration is required in the CR AccessControlPolicy and CR OIDCRelyingParty.

Configurations for LoadBalancer Services

Services of type LoadBalancer may require platform-dependent configuration. We have successfully tested adapted configurations for EKS and GKE. OpenShift and Cilium work without special settings for LoadBalancer Services.

Amazon Elastic Kubernetes Service (EKS) with LoadBalancer:

spec:
  kubernetes:
    service:
      type: LoadBalancer
      externalTrafficPolicy: Local 
      annotations:
        service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing

Azure Kubernetes Service (AKS) with LoadBalancer:

spec:
  kubernetes:
    service:
      type: LoadBalancer
      externalTrafficPolicy: Local 
      annotations:
        service.beta.kubernetes.io/azure-load-balancer-internal: "false"

Google Kubernetes Engine (GKE) with LoadBalancer:

spec:
  kubernetes:
    service:
      type: LoadBalancer
      externalTrafficPolicy: Local

Grafana dashboard configuration

Airlock Microgateway offers several preconfigured Helm-based Grafana dashboard templates that can be enabled and individually disabled in the Operator Helm chart.

Configuration target

Description

Grafana dashboards

The following example makes the dashboard templates available for Grafana:

copy
helm install airlock-microgateway -n airlock-microgateway-system oci://quay.io/airlockcharts/microgateway \​ 
   --set dashboards.create=true --version 4.5.0 --wait --set=operator.gatewayAPI.enabled=true --set=operator.gatewayAPI.podMonitor.create=true
  • Only one Microgateway Operator per cluster may be configured to provide the Grafana dashboard templates.
  • Grafana must be deployed with dashboards.create=true to enable the cluster-wide search for the dashboard templates.
  • Enable PodMonitor creation so metrics are scraped from Airlock Microgateway Engine in sidecarless mode.

TLS certificate generation and renewal between Operator and application namespaces

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:

  • airlock-microgateway-ca-cert – the CA certificate to generate self-signed TLS certificates.
  • webhook-server-cert – the server certificate of the Microgateway Operator.

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.

Further information and links