Gateway Deployment

Airlock Microgateway supports the Kubernetes Gateway API. You use Gateway API resources to define a Gateway instance and the reverse proxy specific behavior. In this setup, the Microgateway Operator acts as the Gateway API controller. When you create the CR Gateway, the Operator creates a Deployment and a matching Service that exposes the configured listener ports.

You can deploy your Microgateway in one of the following patterns:

Ingress: Exposed to clients outside the cluster.
In-cluster Gateway: Reachable only from within the cluster.

Both patterns use the same Kubernetes Gateway API resources. The main difference is how the Service in front of the Microgateway Engine is exposed.

For a comparison of the two deployment patterns, see System Architectures.

Prerequisite

Airlock Microgateway is installed (see Installation and Upgrade).

Configuration

Create the GatewayClass resource

A GatewayClass represents a class of Gateways managed by a specific controller. The spec.controllerName tells Kubernetes which controller is responsible for reconciling this GatewayClass and all associated resources.

For Airlock Microgateway, spec.controllerName must match the controller name configured for the Microgateway Operator (Helm chart setting). The default value is: microgateway.airlock.com/gatewayclass-controller

1
2
3
4
5
6
7


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

Notice

When installing the Microgateway Operator via Helm, a default GatewayClass named airlock-microgateway may already be created. If it exists, you can reuse it.

Create the Gateway resource

A Gateway defines a Microgateway instance and its directly configured listeners, including ports, protocols, hostnames, and TLS settings. You can optionally use ListenerSet resources to add listeners whose configuration is managed separately. The spec.controllerName tells Kubernetes which controller is responsible for reconciling this GatewayClass and all associated resources. When the Microgateway Operator accepts the configuration, it creates:

A Deployment in the same namespace as the Gateway.
A Service with the same name as the Gateway, exposing the configured listener ports.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


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

You can optionally create a GatewayParameters custom resource in the same namespace as the Gateway and reference it via spec.infrastructure.parametersRef to override Microgateway defaults (for example, the Service type and annotations). If you are happy with the defaults, omit the infrastructure.parametersRef section.

Especially for Ingress deployments, make sure TLS is configured appropriately. To configure a publicly trusted certificate, cert-manager can be used to obtain and manage it. See Configuring the HTTP-01 Gateway API solver for details.

Use ListenerSets (optional)

ListenerSets let you define additional listeners for a Gateway in separate resources. They support the following use cases:

Multitenancy: Different application teams can manage their own ListenerSets while sharing a Gateway and its load-balancing infrastructure.
Large-scale deployments: ListenerSets allow a Gateway to use more than the 64 listeners that can be defined directly in Gateway.spec.listeners. Teams can also share ListenerSet configurations to reduce duplication.
Certificates for more listeners per Gateway: Additional HTTPS listeners can use their own TLS certificates, allowing a single Gateway to expose more applications with application-specific certificates.

ListenerSets are optional. You can continue to configure listeners directly in the Gateway when separate listener resources are not needed.

For the responsibilities of each role, see Management roles and responsibilities in System Architectures.

The following example demonstrates listener delegation. It extends gateway-example in the example-backend-gw namespace from the preceding section and creates a ListenerSet and an HTTPRoute. The following prerequisites must be met:

The Gateway configuration is valid, including its existing TLS Secret and any referenced GatewayParameters.
The application is deployed in the example-backend namespace, which contains:
- A Service named example-backend that exposes the application over HTTP on Service port 80 and has ready endpoints.
- A Secret named application-server-certificate of type kubernetes.io/tls, containing a certificate for app.example.org and its matching private key.

Allow ListenerSets to attach to the Gateway

As the Cluster operator, label the application namespace:

1
2


kubectl label namespace example-backend \
  example.com/gateway-access=gateway-example

By default, a Gateway does not accept ListenerSets. Save the following merge patch as gateway-listener-access.yaml to allow ListenerSets from namespaces with this label:

1
2
3
4
5
6
7


spec:
  allowedListeners:
    namespaces:
      from: Selector
      selector:
        matchLabels:
          example.com/gateway-access: gateway-example

Apply the patch to the existing Gateway:

1
2
3
4


kubectl patch gateway gateway-example \
  --namespace example-backend-gw \
  --type=merge \
  --patch-file=gateway-listener-access.yaml

This patch adds the ListenerSet attachment configuration without replacing the existing listeners or infrastructure settings. Keep the equivalent configuration in the manifests used to manage the Gateway.

The Gateway must define at least one listener in spec.listeners, even when using ListenerSets.

allowedListeners controls which namespaces may attach ListenerSets. It does not grant Kubernetes permissions to create or modify resources. Configure the corresponding role-based access control (RBAC) permissions separately, and keep control of the namespace labels used for attachment.

Create the ListenerSet

As an application developer, save the following resource as application-listeners.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
  name: application-listeners
  namespace: example-backend
spec:
  parentRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: gateway-example
    namespace: example-backend-gw
  listeners:
    - name: https
      hostname: app.example.org
      port: 443
      protocol: HTTPS
      tls:
        mode: Terminate
        certificateRefs:
          - group: ""
            kind: Secret
            name: application-server-certificate
      allowedRoutes:
        namespaces:
          from: Same
        kinds:
          - group: gateway.networking.k8s.io
            kind: HTTPRoute

Apply the resource:

1

kubectl apply -f application-listeners.yaml

The parentRef attaches the ListenerSet to the shared Gateway. The HTTPS listener terminates TLS using the Secret in the ListenerSet’s namespace.

The Gateway’s allowedListeners specifies the namespaces from which ListenerSets may attach to the Gateway. The listener’s allowedRoutes specifies which routes may attach to that listener. In this example, only HTTPRoutes from the ListenerSet’s namespace (example-backend) may attach to the listener.

If a TLS Secret is stored in a different namespace, a suitable ReferenceGrant is required in the Secret’s namespace. Keeping the Secret in the ListenerSet’s namespace avoids that additional configuration.

Attach an HTTPRoute to the ListenerSet

Save the following resource as application-route.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: application-route
  namespace: example-backend
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: ListenerSet
      name: application-listeners
      sectionName: https
  hostnames:
    - app.example.org
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: example-backend
          port: 80

Apply the resource:

1

kubectl apply -f application-route.yaml

The route references the ListenerSet, not the Gateway. The sectionName selects the https listener within that ListenerSet. The route and the referenced Service are both in example-backend.

Notice

Routes attached to a Gateway do not automatically attach to listeners in its ListenerSets.

When moving a listener configuration to a ListenerSet, update the affected routes to reference that ListenerSet.

Verify the configuration

Inspect the status of the Gateway, ListenerSet, and HTTPRoute:

1
2
3
4
5
6
7
8


kubectl get gateway gateway-example \
  --namespace example-backend-gw --output yaml

kubectl get listenerset application-listeners \
  --namespace example-backend --output yaml

kubectl get httproute application-route \
  --namespace example-backend --output yaml

Check the following conditions for the current resource generation:

Resource	Expected status
Gateway	`Accepted=True` and `Programmed=True` in `status.conditions`. The `status.attachedListenerSets` count includes the new ListenerSet.
ListenerSet	`Accepted=True` and `Programmed=True` in `status.conditions`. For the `https` entry in `status.listeners`, check that `Accepted`, `ResolvedRefs`, and `Programmed` are `True` and that `Conflicted` is not `True`.
HTTPRoute	The entry in `status.parents` for `application-listeners` has `Accepted=True` and `ResolvedRefs=True`.

If the expected conditions are not met, inspect their reason and message fields. Check the namespace label, parent references, allowed route namespaces, certificate reference, and backend Service as applicable.

These checks do not replace a connectivity test from the intended clients after the Gateway Service has been exposed.

Avoid listener conflicts

Listener configurations must be distinct across the Gateway and its attached ListenerSets. For example, HTTPS listeners with identical ports and hostnames conflict even if their listener names or certificates differ.

When listeners in different resources conflict, listeners defined directly in the Gateway take precedence. Between ListenerSets, the older resource takes precedence; equal creation timestamps are resolved by alphabetical order of namespace/name. A ListenerSet can remain partially accepted when only some of its listeners conflict, so inspect the individual entries in status.listeners rather than relying only on the ListenerSet’s overall status.

Continue with Variant A: Ingress Gateway (RECOMMENDED) or Variant B: In-cluster Gateway to configure how the Gateway Service is exposed. ListenerSets can be used with either deployment pattern.

Variant A: Ingress Gateway (RECOMMENDED)

For Ingress, you typically expose the Microgateway using a Kubernetes Service of type LoadBalancer so that your cloud provider assigns an external IP address and DNS name.

Use the CR GatewayParameters to configure the Service type and cloud-provider specific annotations to make the setup work.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


apiVersion: microgateway.airlock.com/v1alpha1
kind: GatewayParameters
metadata:
  name: gateway-parameters-example
  namespace: example-backend-gw
spec:
  kubernetes:
    service:
      type: LoadBalancer
      externalTrafficPolicy: Local
      # Optional: configure cloud-specific annotations for the Service.
      # If not required, omit the annotations section.
      annotations:
        ...

Reference the GatewayParameters from your Gateway using spec.infrastructure.parametersRef..

Adjust the annotations to match your cloud provider. If your setup does not require any annotations, omit the annotations section completely.

Amazon Elastic Kubernetes Service (EKS) with LoadBalancer:

1
2
3
4
5
6
7


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

Azure Kubernetes Service (AKS) with LoadBalancer:

1
2
3
4
5
6
7


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

Google Kubernetes Engine (GKE) with LoadBalancer:

1
2
3
4
5


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

Variant B: In-cluster Gateway

For an in-cluster Gateway you usually do not need an external load balancer. A Kubernetes Service of type ClusterIP is sufficient, so only workloads inside the cluster can reach the Gateway.

ClusterIP is the default Service type of Microgateway. Therefore, you do not need a GatewayParameters resource just to configure the Service type. You can either:

Omit spec.infrastructure.parametersRef in the Gateway
Set the Service type explicitly using GatewayParameters as shown below.

1
2
3
4
5
6
7
8
9


apiVersion: microgateway.airlock.com/v1alpha1
kind: GatewayParameters
metadata:
  name: gateway-parameters-example
  namespace: example-backend-gw
spec:
  kubernetes:
    service:
      type: ClusterIP

Configure client IP detection

Configure the remote-IP settings in GatewayParameters to match your deployment topology. The selected remote IP address is used for GeoIP lookups.

Notice

If client IP detection identifies a proxy or load balancer instead of the intended client, GeoIP evaluates that intermediary’s address. Country-based request conditions and country information in headers, logs, and metrics can then produce unintended results.

Verify client IP detection before relying on GeoIP information.

Send a test request through the intended network path and inspect network.forwarded_ip in the default access log. This field contains the identified remote IP address. In contrast, source.ip records the direct downstream connection address.

For the available extraction methods and settings, see GatewayParameters.spec.defaults.downstream.remoteIP.

For country-based request conditions, GeoIP command operators, and database management, see Geolocation.

CR reference documentation

CR GatewayParameters