GatewayParameters

microgateway.airlock.com/v1alpha1


GatewayParameters defines the configuration settings for deploying a Gateway in a Kubernetes, including options for logging, service type, deployment strategy, and resource management. It can be referenced by either a GatewayClass or a Gateway.
Note: More specific GatewayParameters takes precedence, e.g., if a Gateway references GatewayParameters, the parameters from its associated GatewayClass are completely overridden without merging.

apiVersion: microgateway.airlock.com/v1alpha1
kind: GatewayParameters
metadata:
  name: gateway-parameters-example
spec:
  # Enable debug logging
  logging:
    level: debug

  kubernetes:
    # Expose the Gateway using a service with an internet-facing AWS Network Load Balancer
    service:
      type: LoadBalancer
      annotations:
        service.beta.kubernetes.io/aws-load-balancer-type: external
        service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip
        service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing

    deployment:
      replicas: 3

      strategy:
        type: RollingUpdate
        rollingUpdate:
          maxUnavailable: 1

      # Schedule the Airlock Microgateway Engine pods on a specific instance type and across availability zones
      placement:
        nodeSelector:
          node.kubernetes.io/instance-type: m3.medium
        topologySpreadConstraints:
          - maxSkew: 1
            topologyKey: topology.kubernetes.io/zone
            whenUnsatisfiable: ScheduleAnyway

      # Specify Volumes for the Airlock Microgateway Gateway deployment
      volumes:
        - name: vol-1
          emptyDir: {}

      engineContainer:
        # Set resource restrictions to apply to the Airlock Microgateway Engine container
        resources:
          limits:
            cpu: 500m
            memory: 128Mi
          requests:
            cpu: 10m
            memory: 40Mi
        # Specify VolumeMounts for the Airlock Microgateway Engine container
        volumeMounts:
          - name: vol-1
            mountPath: /tmp/data
        securityContext:
          # Specify additional capabilities assigned to the Airlock Microgateway Engine container
          capabilities:
            add: ["BPF"]

  defaults:
    customResponses:
      # Customize all direct error responses sent by the Gateway
      local:
        - statusCodeCondition:
            matcher:
              exact: 401
          customResponseRef:
            name: custom-401
        - statusCodeCondition:
            matcher:
              exact: 404
          customResponseRef:
            name: custom-404
        - statusCodeCondition:
            matcher:
              range:
                start: 400
                end: 499
          customResponseRef:
            name: custom-400
        - statusCodeCondition:
            matcher:
              range:
                start: 500
                end: 599
          customResponseRef:
            name: custom-5xx
      # Replace upstream error responses with custom responses
      upstream:
        - responseConditions:
            statusCode:
              matcher:
                range:
                  start: 400
                  end: 499
          customResponseRef:
            name: upstream-4xx
        - responseConditions:
            statusCode:
              matcher:
                range:
                  start: 500
                  end: 599
          customResponseRef:
            name: upstream-5xx

    sessionHandlingRef:
      name: session-handling-example

    telemetryRef:
      name: telemetry-example

    downstream:
      # Configure 'remoteIP' extraction.
      remoteIP:
        xff:
          numTrustedHops: 1
apiVersion: microgateway.airlock.com/v1alpha1
kind: GatewayParameters
metadata:
  name: default
spec: 
  logging: 
    level: info
  kubernetes: 
    service: 
      type: ClusterIP
    deployment: 
      replicas: 2
      placement: {}
      engineContainer: 
        securityContext: 
          capabilities: {}
      automountServiceAccountToken: false
  defaults: 
    customResponses: {}
    downstream: 
      remoteIP: 
        connectionIP: {}
  features: 
    envoyExtensionPolicyEnabled: false
    insecureTLSAllowed: false
  experimental: 
    tls: {}

GatewayParameters

Field Description Type Required Default Allowed Values
metadata defines the resource’s metadata ObjectMeta yes
spec defines the desired Gateway configuration parameters values. object no

GatewayParameters.spec

Field Description Type Required Default Allowed Values
defaults specifies default configurations and policies for the Gateway. object no
experimental specifies configurations and policies for the Gateway.
Note: Experimental contains Gateway API settings which are not graduated yet. Therefore, they are subject to change or might be removed in future releases.
object no
features specifies which optional features are enabled for the Gateway. object no
kubernetes defines the configuration for Kubernetes resources provisioned for the Gateway. object no
logging specifies Envoy system logging settings for the Gateway. object no

GatewayParameters.spec.defaults

Field Description Type Required Default Allowed Values
customResponses configures response replacement for the Gateway. object no
downstream defines the downstream configuration for the Gateway. object no
sessionHandlingRef selects the default SessionHandling configuration for the Gateway. object no
telemetryRef selects the default Telemetry configuration (logging, metrics, and tracing) for the Gateway. object no

GatewayParameters.spec.defaults.customResponses

Field Description Type Required Default Allowed Values
local defines a list of rules for customizing direct responses originating from the Gateway itself during its processing (i.e., not from the upstream/backend).

The rules are processed as follows:
  • The first rule (from top to bottom) where the statusCodeCondition matches the local response’s status code determines the custom response to be sent.
  • If no rule matches (or if no local rules are defined), the Gateway will send default responses.
Default error responses, available as text/html, application/json and text/plain (fallback):
  • 401 -> built-in 401 response
  • 403 -> built-in 403 response
  • 404 -> built-in 404 response
  • 429 -> built-in 429 response
  • 4xx -> built-in 400 response (status code replaced with 400)
  • 5xx -> built-in 5xx response (status code preserved for 502-504, others replaced with 500)
If you wish to customize all built-in error responses, we recommend at least the following set of rules as a starting point:
local:
 - statusCodeCondition:
     matcher:
       exact: 401
   customResponseRef:
     name: custom-401
 - statusCodeCondition:
     matcher:
       exact: 404
   customResponseRef:
     name: custom-404
 - statusCodeCondition:
     matcher:
       range:
         start: 400
         end: 499
   customResponseRef:
     name: custom-400
 - statusCodeCondition:
     matcher:
       range:
         start: 500
         end: 599
   customResponseRef:
     name: custom-5xx
Examples of local responses sent by the Gateway:
  • 301 | 302 | 303 | 307 | 308 (redirects)
  • 400 (invalid requests, blocked requests, rejected requests due to invalid configuration e.g., invalid OpenAPI spec)
  • 401 (denied by access control, OIDC/JWT authentication errors, token exchange errors)
  • 403 (CSRF protection, wrong scheme)
  • 404 (request does not match any route)
  • 408 (request timeout)
  • 429 (community rate limit reached)
  • 500 (invalid route/backend/policy configuration)
  • 502 | 503 (other errors)
  • 504 (backend timeout)
Note: If EnvoyExtensionPolicy is allowed, custom filters may generate arbitrary local responses.
object[] no
upstream defines a list of rules for replacing upstream responses with custom responses.

The rules are processed as follows:
  • The first rule (from top to bottom) where the responseConditions matches the upstream response determines the custom response to be sent.
  • If no rule matches (or if no upstream rules are defined), the unmodified upstream response is forwarded to the client.
object[] no

GatewayParameters.spec.defaults.customResponses.local[]

Field Description Type Required Default Allowed Values
customResponseRef selects the custom response to send. object yes
statusCodeCondition specifies a condition which the status code of the original local response must satisfy in order for this custom response to be sent. object yes

GatewayParameters.spec.defaults.customResponses.local[].customResponseRef

Field Description Type Required Default Allowed Values
name of the resource string yes

GatewayParameters.spec.defaults.customResponses.local[].statusCodeCondition

Field Description Type Required Default Allowed Values
matcher matches one or more status codes. object yes exact{}, range{}

GatewayParameters.spec.defaults.customResponses.local[].statusCodeCondition.matcher

Field Description Type Required Default Allowed Values
exact matches a specific status code. int32 no [100, 599]
range matches an inclusive range of status codes. object no

GatewayParameters.spec.defaults.customResponses.local[].statusCodeCondition.matcher.range

Field Description Type Required Default Allowed Values
end of the range (inclusive). int32 yes [100, 599]
start of the range (inclusive). int32 yes [100, 599]

GatewayParameters.spec.defaults.customResponses.upstream[]

Field Description Type Required Default Allowed Values
customResponseRef selects the custom response to send. object yes
responseConditions specifies conditions which the upstream response must all satisfy in order for this custom response to be sent. object yes

GatewayParameters.spec.defaults.customResponses.upstream[].customResponseRef

Field Description Type Required Default Allowed Values
name of the resource string yes

GatewayParameters.spec.defaults.customResponses.upstream[].responseConditions

Field Description Type Required Default Allowed Values
statusCode specifies a condition on the original upstream response’s status code. object yes

GatewayParameters.spec.defaults.customResponses.upstream[].responseConditions.statusCode

Field Description Type Required Default Allowed Values
matcher matches one or more status codes. object yes exact{}, range{}

GatewayParameters.spec.defaults.customResponses.upstream[].responseConditions.statusCode.matcher

Field Description Type Required Default Allowed Values
exact matches a specific status code. int32 no [100, 599]
range matches an inclusive range of status codes. object no

GatewayParameters.spec.defaults.customResponses.upstream[].responseConditions.statusCode.matcher.range

Field Description Type Required Default Allowed Values
end of the range (inclusive). int32 yes [100, 599]
start of the range (inclusive). int32 yes [100, 599]

GatewayParameters.spec.defaults.downstream

Field Description Type Required Default Allowed Values
remoteIP defines how the remote IP of a client is propagated.
Default: connectionIP: {…}
object no connectionIP{...} connectionIP{}, customHeader{}, proxyProtocol{}, xff{}

GatewayParameters.spec.defaults.downstream.remoteIP

Field Description Type Required Default Allowed Values
connectionIP configures to use the source IP address of the direct downstream connection. object no {}
customHeader specifies to use a custom header for remote IP extraction. object no
proxyProtocol configures to use the proxy protocol connection header for IP extraction. The proxy protocol adds a header to TCP connections to preserve the client’s IP address.
For more details, refer to the protocol specification: https://www.haproxy.org/download/3.1/doc/proxy-protocol.txt
Note: When this field is set, all incoming connections must use the proxy protocol, otherwise, the connection will be closed.
object no
xff configures to use the standard ‘X-Forwarded-For’ header for IP extraction. object no numTrustedHops{...} numTrustedHops{}, trustedCIDRRanges{}

GatewayParameters.spec.defaults.downstream.remoteIP.customHeader

Field Description Type Required Default Allowed Values
headerName specifies the name of the custom header containing the remote IP. string yes
required specifies if the custom header is required. If true and not available the request will be rejected with 403. bool no true true, false

GatewayParameters.spec.defaults.downstream.remoteIP.proxyProtocol

Field Description Type Required Default Allowed Values
version specifies the version of the proxy protocol. If unspecified, all versions are accepted. enum no V1, V2

GatewayParameters.spec.defaults.downstream.remoteIP.xff

Field Description Type Required Default Allowed Values
numTrustedHops specifies to extract the client’s originating IP from the nth rightmost entry in the X-Forwarded-For header. With the default value of 1, the IP is extracted from the rightmost entry.
Only one of numTrustedHops and trustedCIDRRanges can be set.
Default: 1
int32 no 1 [1, 2147483647]
trustedCIDRRanges specifies the IPv4 or IPv6 CIDR ranges, e.g. 196.148.3.128/26 or 2001:db8::/28 to trust when evaluating the remote IP address to determine the original client’s IP address. When the remote IP address matches a trusted CIDR and the X-Forwarded-For header was sent, each entry in the X-Forwarded-For header is evaluated from right to left and the first non-trusted address is used as the original client address. If all addresses in X-Forwarded-For are within the trusted list, the first (leftmost) entry is used.
Only one of numTrustedHops and trustedCIDRRanges can be set.
string[] no

GatewayParameters.spec.defaults.sessionHandlingRef

Field Description Type Required Default Allowed Values
name of the resource string yes

GatewayParameters.spec.defaults.telemetryRef

Field Description Type Required Default Allowed Values
name of the resource string yes

GatewayParameters.spec.experimental

Field Description Type Required Default Allowed Values
tls specifies frontend and backend tls configuration for the entire Gateway.

Note: If .spec.tls.frontend is specified in the Gateway resource, the frontend configuration here in GatewayParameters will be ignored.
Note: If .spec.tls.backend is specified in the Gateway resource, the backend configuration here in GatewayParameters will be ignored.
GatewayTLSConfig no

GatewayParameters.spec.features

Field Description Type Required Default Allowed Values
envoyExtensionPolicyEnabled specifies whether the controller processes EnvoyExtensionPolicy resources for HTTPRoutes attached to the Gateway.
Use EnvoyExtensionPolicy only if the features of Airlock Microgateway and Kubernetes Gateway API do not provide this functionality. If you identify missing features or use cases, please report them to help improve our product.
Note: Invalid or malformed Envoy configurations may prevent the Gateway’s configuration from being updated.
bool no false true, false
insecureTLSAllowed specifies whether the Gateway accepts BackendTLSPolicies that disable certificate validation. Allowing insecure TLS may expose the Gateway to man-in-the-middle attacks and other vulnerabilities.
THIS IS INSECURE AND SHOULD ONLY BE USED FOR TESTING.
bool no false true, false

GatewayParameters.spec.kubernetes

Field Description Type Required Default Allowed Values
deployment configures the Kubernetes Deployment provisioned for the Gateway. object no
service configures the Kubernetes Service provisioned for the Gateway. object no

GatewayParameters.spec.kubernetes.deployment

Field Description Type Required Default Allowed Values
automountServiceAccountToken configures whether a service account token should be automatically mounted. Set this to true only if a sidecar that requires a service account token (e.g., OpenShift ServiceMesh) is injected to the Gateway Deployment. bool no false true, false
engineContainer configures the container running the Airlock Microgateway Engine. object no
imagePullSecrets configures the list of references to secrets in the same namespace, which will be used in the Gateway deployment for pulling any of the images.
More info: https://kubernetes.io/docs/concepts/containers/images#specifying-imagepullsecrets-on-a-pod
LocalObjectReference[] no
placement configures scheduling of the Airlock Microgateway Engine pod. object no
replicas sets the number of Gateway Deployment replicas. int32 no 2 [1, 2147483647]
strategy configures the deployment strategy which is used to replace existing Airlock Microgateway Engine pods with new ones.
If undefined, default settings (RollingUpdate) are applied.
DeploymentStrategy no
volumes specify the list of Kubernetes Volumes that can be mounted by EngineContainer belonging to the Gateway deployment. Volume[] no

GatewayParameters.spec.kubernetes.deployment.engineContainer

Field Description Type Required Default Allowed Values
resources specifies the compute resources required for this container.
If undefined, default resource settings are applied: {"requests":{"cpu":"100m","memory":"256Mi"}}.
Setting this field overrides the defaults entirely, values are not merged.
See https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ for details.
ResourceRequirements no
securityContext specifies the security configuration that will be applied to the EngineContainer. object no
volumeMounts specifies the list of volumes to mount into the EngineContainer’s filesystem. Volume[] no

GatewayParameters.spec.kubernetes.deployment.engineContainer.securityContext

Field Description Type Required Default Allowed Values
capabilities specifies the set of POSIX capabilities of the EngineContainer.
All capabilities are dropped by default.
object no

GatewayParameters.spec.kubernetes.deployment.engineContainer.securityContext.capabilities

Field Description Type Required Default Allowed Values
add specifies the POSIX capabilities that should be granted to the EngineContainer.
Since all capabilities are dropped first, this list represents the full set of capabilities the container will run with.
Capabilities[] no

GatewayParameters.spec.kubernetes.deployment.placement

Field Description Type Required Default Allowed Values
affinity specifies affinity and anti-affinity rules for the Airlock Microgateway Engine pods. Affinity no
nodeSelector is a selector which must be true for the Airlock Microgateway Engine pods to fit on a node. map[string]string no
tolerations allows scheduling of Airlock Microgateway Engine pods on tainted nodes. Toleration[] no
topologySpreadConstraints describes how the Airlock Microgateway Engine pods ought to spread across topology domains (e.g., nodes, zones).
If the label selector of the constraints is undefined, the label selector of the deployment will be used instead.
TopologySpreadConstraint[] no

GatewayParameters.spec.kubernetes.service

Field Description Type Required Default Allowed Values
allocateLoadBalancerNodePorts defines if NodePorts will be automatically allocated for services with type LoadBalancer.
If undefined, the default is true. It may be set to false if the cluster load-balancer does not rely on NodePorts.
bool no true, false
annotations specifies additional annotations for the Service, e.g., for configuring cloud LoadBalancers. map[string]string no
externalTrafficPolicy describes how nodes distribute service traffic they receive on one of the Service’s “externally-facing” addresses (NodePorts, and LoadBalancer IPs). Meaning of the possible values:
Local: preserves the source IP of the traffic by routing only to endpoints on the same node as the traffic was received on (dropping the traffic if there are no local endpoints).
Cluster: routes traffic to all endpoints. Be aware that this may break client IP detection and dependent features (e.g., deny rule exceptions or access control policies with request conditions matching remote IPs).
If undefined, the Local policy is applied.
ServiceExternalTrafficPolicy no Cluster, Local
type specifies the type of Kubernetes Service. ServiceType no ClusterIP ClusterIP, LoadBalancer, NodePort

GatewayParameters.spec.logging

Field Description Type Required Default Allowed Values
level specifies the logging level for the Envoy system logs of the Airlock Microgateway Engine. enum no info off, critical, error, warn, info, debug, trace