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: 1apiVersion: 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:
text/html, application/json and text/plain (fallback):
|
object[] | no | ||
| upstream | defines a list of rules for replacing upstream responses with custom responses. The rules are processed as follows:
|
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 |