SidecarGateway

microgateway.airlock.com/v1alpha1


SidecarGateway defines an Airlock Microgateway Engine sidecar container configuration.

apiVersion: microgateway.airlock.com/v1alpha1
kind: SidecarGateway
metadata:
  name: sidecar-gateway-example
spec:
  podSelector:
    matchLabels:
      # podSelector which matches the example app to protect.
      app: example-app

  sessionHandlingRef:
    name: session-handling-example

  applications:
    - containerPort: 8443
      routes:
        # Do not apply any Airlock Microgateway filters
        # to '/metrics'
        - pathPrefix: /metrics
          unsecured: {}
        - pathPrefix: /
          secured:
            accessControlRef:
              name: access-control-example
            contentSecurityRef:
              name: content-security-example
      downstream:
        # Configure 'remoteIP' extraction.
        remoteIP:
          xff:
            numTrustedHops: 1
        restrictions:
          http:
            # Set max Header length to '80Ki'
            headersLength: 80Ki
        protocol:
          # Enable auto mode for http1/http2.
          auto: {}
        tls:
          # Enable TLS for downstream connections on port '8443'
          enable: true
          # Use the server certificate from the kubernetes TLS secret 'example-tls-secret'
          secretRef:
            name: example-tls-secret
          protocol:
            # Require TLS version 1.3
            minimum: TLSv1_3
          clientCertificate:
            # Do not require any client certificate
            ignored: {}
          xfcc: AlwaysForwardOnly
      upstream:
        tls:
          # Enable TLS for upstream connection on port '8443'
          enable: true
          protocol:
            # Require TLS version 1.2 or higher
            minimum: TLSv1_2

      envoyHTTPFilterRefs:
        prepend:
          - name: envoy-http-filter-example-1
        append:
          - name: envoy-http-filter-example-2

      telemetryRef:
        name: telemetry-example

  envoyClusterRefs:
    - name: envoy-cluster-example-1

SidecarGateway

Field Description Type Required Default Allowed Values
metadata defines the resource’s metadata ObjectMeta yes
spec defines the desired sidecar gateway configuration. object no
status describes the current status of the SidecarGateway. object no

SidecarGateway.spec

Field Description Type Required Default Allowed Values
applications defines applications which run on different ports. object[] yes
envoyClusterRefs selects the relevant EnvoyClusters. object[] no
podSelector defines to which Pods the configuration will be applied to. object no
sessionHandlingRef selects the SessionHandling configuration to apply. object no

SidecarGateway.spec.applications[]

Field Description Type Required Default Allowed Values
containerPort refers to the container port.
This must be a valid port number, 0 < x < 65536.
int64 no 8080 [1, 65535]
downstream defines the downstream configuration for this application object no
envoyHTTPFilterRefs selects the relevant EnvoyHTTPFilters. object no
routes defines the security configurations for different paths. The first matching route (from top to bottom) applies. object[] no
telemetryRef selects the relevant Telemetry configuration resource.
If undefined, default settings are applied, designed to work with most upstream web application services.
object no
upstream defines the upstream configuration for this application object no

SidecarGateway.spec.applications[].downstream

Field Description Type Required Default Allowed Values
protocol defines the exposed HTTP protocol version. At most one of http1, http2 and auto can be set.
Default: auto: {}
object no auto{...} auto{}, http1{}, http2{}
remoteIP defines how the remote IP of a client is propagated.
Default: xff: {…}
object no xff{...} connectionIP{}, customHeader{}, xff{}
requestNormalizations defines a set of normalization actions which are applied to the request before route matching. object no
restrictions defines restrictions for downstream. object no
timeouts defines timeouts for downstream object no
tls defines the TLS settings. object no

SidecarGateway.spec.applications[].downstream.protocol

Field Description Type Required Default Allowed Values
auto specifies that the protocol should be inferred. object no
http1 specifies that the client is assumed to speak HTTP/1.1. object no {}
http2 specifies that the client is assumed to speak HTTP/2. object no

SidecarGateway.spec.applications[].downstream.protocol.auto

Field Description Type Required Default Allowed Values
http2 specifies the settings for when HTTP/2 is inferred. object no

SidecarGateway.spec.applications[].downstream.protocol.auto.http2

Field Description Type Required Default Allowed Values
allowConnect specifies whether to allow proxying Websocket and other upgrades over H2 CONNECT. bool no false true, false

SidecarGateway.spec.applications[].downstream.protocol.http2

Field Description Type Required Default Allowed Values
allowConnect specifies whether to allow proxying Websocket and other upgrades over H2 CONNECT. bool no false true, false

SidecarGateway.spec.applications[].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
xff configures to use the standard ‘X-Forwarded-For’ header for IP extraction. object no numTrustedHops{...} numTrustedHops{}, trustedCIDRRanges{}

SidecarGateway.spec.applications[].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

SidecarGateway.spec.applications[].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

SidecarGateway.spec.applications[].downstream.requestNormalizations

Field Description Type Required Default Allowed Values
mergeSlashes ensures that adjacent slashes in the path are merged into one. bool no true true, false
normalizePath ensures normalization according to RFC 3986 without case normalization. bool no true true, false

SidecarGateway.spec.applications[].downstream.restrictions

Field Description Type Required Default Allowed Values
http defines limits for the HTTP protocol. object no

SidecarGateway.spec.applications[].downstream.restrictions.http

Field Description Type Required Default Allowed Values
headersLength defines maximum size of all request headers combined. Requests that exceed this limit will receive a 431 response. Quantity no 60Ki

SidecarGateway.spec.applications[].downstream.tls

Field Description Type Required Default Allowed Values
ciphers defines a list of the supported TLS cipher suites. For details on cipher list refer to the envoy documentation on cipher_suites in common tls configuration. string[] no
clientCertificate defines the TLS settings for verification of client certificates.
At most one of ignored, optional and required can be set.
Default: ignored: {}
object no ignored{...} ignored{}, optional{}, required{}
enable defines if the downstream connection is encrypted. bool no false true, false
protocol defines the supported TLS protocol versions. object no
secretRef defines the reference to the TLS server certificate (secret of type kubernetes.io/tls). object no
xfcc defines the handling of X-Forwarded-Client-Cert header. Meaning of the possible values:
Sanitize: Do not send the XFCC header to the next hop. This is the default value.
ForwardOnly: When the client connection is mTLS (Mutual TLS), forward the XFCC header in the request.
AppendAndForward: When the client connection is mTLS, append the client certificate information to the request’s XFCC header and forward it.
SanitizeAndSet: When the client connection is mTLS, reset the XFCC header with the client certificate information and send it to the next hop.
AlwaysForwardOnly: Always forward the XFCC header in the request, regardless of whether the client connection is mTLS.
Note: When forwarding the XFCC header in the request you might have to adjust the header length restrictions (See sidecargateway.spec.applications.downstream.restrictions.http)
enum no AlwaysForwardOnly, AppendAndForward, ForwardOnly, SanitizeAndSet, Sanitize

SidecarGateway.spec.applications[].downstream.tls.clientCertificate

Field Description Type Required Default Allowed Values
ignored disables verification of the client certificate. object no {}
optional enables verification of the client certificate if one is presented.
In this mode only trustedCA and crl settings can be configured since certificatePinning and allowedSANs require a client certificate.
object no
required contains settings for client certificate verification. A client must present a valid certificate.
At least one of trustedCA and certificatePinning must be set.
object no

SidecarGateway.spec.applications[].downstream.tls.clientCertificate.optional

Field Description Type Required Default Allowed Values
crl defines the Certificate Revocation List (CRL) settings. object no
trustedCA defines which CA certificates are trusted. object yes

SidecarGateway.spec.applications[].downstream.tls.clientCertificate.optional.crl

Field Description Type Required Default Allowed Values
lists defines the list of secretRefs containing Certificate Revocation Lists. object[] no
validationMode defines whether only the leaf certificate or also the CA certs should be checked. enum no VerifyChain VerifyChain, VerifyLeafCertOnly

SidecarGateway.spec.applications[].downstream.tls.clientCertificate.optional.crl.lists[]

Field Description Type Required Default Allowed Values
secretRef defines the reference to a secret containing one or more CRL’s (in PEM format) under the key ‘ca.crl’. object yes

SidecarGateway.spec.applications[].downstream.tls.clientCertificate.optional.crl.lists[].secretRef

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

SidecarGateway.spec.applications[].downstream.tls.clientCertificate.optional.trustedCA

Field Description Type Required Default Allowed Values
certificates defines the list of secretRefs containing trusted CA certificates. object[] yes
verificationDepth specifies the hops in the certificate chain at which validation is performed.
1 means that either the leaf or the signing CA must be in the set of trusted certificates.
int32 no 1 [0, 2147483647]

SidecarGateway.spec.applications[].downstream.tls.clientCertificate.optional.trustedCA.certificates[]

Field Description Type Required Default Allowed Values
secretRef defines the reference to a secret containing one or more CA certificates under the key ‘ca.crt’. object yes

SidecarGateway.spec.applications[].downstream.tls.clientCertificate.optional.trustedCA.certificates[].secretRef

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

SidecarGateway.spec.applications[].downstream.tls.clientCertificate.required

Field Description Type Required Default Allowed Values
allowedSANs is a list of matchers to verify the Subject Alternative name. If specified, it will verify that the
Subject Alternative Name of the presented certificate matches one of the specified matchers. The matching uses “any” semantics,
that is to say, the SAN is verified if at least one matcher is matched.
AllowedSANs requires trustedCA to be set.
object[] no
certificatePinning defines the constraints a client certificate must fulfill.
If more than one constraint is configured only one must be satisfied.
At least one of allowedSPKIs and allowedHashes must be set.
object no
crl defines the Certificate Revocation List (CRL) settings. object no
trustedCA defines which CA certificates are trusted. object no

SidecarGateway.spec.applications[].downstream.tls.clientCertificate.required.allowedSANs[]

Field Description Type Required Default Allowed Values
matcher defines the string matcher for the SAN value. object yes contains{}, exact{}, prefix{}, regex{}, suffix{}
sanType defines the type of SAN matcher. enum yes DNS, Email, IPAddress, URI

SidecarGateway.spec.applications[].downstream.tls.clientCertificate.required.allowedSANs[].matcher

Field Description Type Required Default Allowed Values
contains defines a substring match on the substring specified here. Empty contains match is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.
string no
exact defines an explicit match on the string specified here.
Only one of exact, prefix, suffix, regex or contains can be set.
string no
ignoreCase indicates whether the matching should be case-insensitive. In case of a regex match, the regex gets wrapped with a group (?i:...). bool no false true, false
prefix defines a prefix match on the prefix specified here. Empty prefix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.
string no
regex defines a regex match on the regular expression specified here. Google’s RE2 regex engine is used.
The regex matches only single-line by default, even with “.*”. To match a multi-line string prepend (?s) to your regex.
Only one of exact, prefix, suffix, regex or contains can be set.
string no
suffix defines a suffix match on the suffix specified here. Empty suffix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.
string no

SidecarGateway.spec.applications[].downstream.tls.clientCertificate.required.crl

Field Description Type Required Default Allowed Values
lists defines the list of secretRefs containing Certificate Revocation Lists. object[] no
validationMode defines whether only the leaf certificate or also the CA certs should be checked. enum no VerifyChain VerifyChain, VerifyLeafCertOnly

SidecarGateway.spec.applications[].downstream.tls.clientCertificate.required.crl.lists[]

Field Description Type Required Default Allowed Values
secretRef defines the reference to a secret containing one or more CRL’s (in PEM format) under the key ‘ca.crl’. object yes

SidecarGateway.spec.applications[].downstream.tls.clientCertificate.required.crl.lists[].secretRef

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

SidecarGateway.spec.applications[].downstream.tls.clientCertificate.required.certificatePinning

Field Description Type Required Default Allowed Values
allowedHashes is a list of hex-encoded SHA-256 hashes.
If specified, it will verify that the SHA-256 of the DER-encoded presented certificate matches one of the specified values.
string[] no
allowedSPKIs is a list of base64-encoded SHA-256 hashes.
If specified, it will verify that the SHA-256 of the DER-encoded Subject Public Key Information (SPKI) of the presented certificate matches one of the specified values.
string[] no

SidecarGateway.spec.applications[].downstream.tls.clientCertificate.required.trustedCA

Field Description Type Required Default Allowed Values
certificates defines the list of secretRefs containing trusted CA certificates. object[] yes
verificationDepth specifies the hops in the certificate chain at which validation is performed.
1 means that either the leaf or the signing CA must be in the set of trusted certificates.
int32 no 1 [0, 2147483647]

SidecarGateway.spec.applications[].downstream.tls.clientCertificate.required.trustedCA.certificates[]

Field Description Type Required Default Allowed Values
secretRef defines the reference to a secret containing one or more CA certificates under the key ‘ca.crt’. object yes

SidecarGateway.spec.applications[].downstream.tls.clientCertificate.required.trustedCA.certificates[].secretRef

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

SidecarGateway.spec.applications[].downstream.tls.protocol

Field Description Type Required Default Allowed Values
maximum supported TLS version. enum no TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3
minimum supported TLS version. enum no TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3

SidecarGateway.spec.applications[].downstream.tls.secretRef

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

SidecarGateway.spec.applications[].downstream.timeouts

Field Description Type Required Default Allowed Values
http defines the settings for HTTP timeouts. object no

SidecarGateway.spec.applications[].downstream.timeouts.http

Field Description Type Required Default Allowed Values
idle specifies the downstream HTTP idle timeout.
A value of 0 will completely disable the timeout.
Default: 5m
string (duration) no 5m See link
maxDuration defines the total duration for a HTTP request/response stream.
A value of 0 will completely disable the timeout.
Default: 5m
string (duration) no 5m See link
requestHeaders defines the duration before all request headers must be received.
A value of 0 will completely disable the timeout.
Default: 10s
string (duration) no 10s See link

SidecarGateway.spec.applications[].envoyHTTPFilterRefs

Field Description Type Required Default Allowed Values
append specifies EnvoyHTTPFilters to insert after the Airlock filters (i.e., after auth, deny rule filtering, header rewrites, etc.). object[] no
prepend specifies EnvoyHTTPFilters to insert before the Airlock filters (i.e, before auth, deny rule filtering, header rewrites, etc.). object[] no

SidecarGateway.spec.applications[].envoyHTTPFilterRefs.append[]

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

SidecarGateway.spec.applications[].envoyHTTPFilterRefs.prepend[]

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

SidecarGateway.spec.applications[].routes[]

Field Description Type Required Default Allowed Values
pathPrefix defines the path prefix used during route selection. string no /
secured enables WAF processing for this route. object no
unsecured disables all WAF functionality and therefore protection for this route.
WARNING: Using this setting when the application is exposed to untrusted downstream traffic is highly discouraged.
object no {}

SidecarGateway.spec.applications[].routes[].secured

Field Description Type Required Default Allowed Values
accessControlRef selects the relevant AccessControl configuration resource.
If undefined, Airlock Microgateway does not perform any access control.
object no
contentSecurityRef selects the relevant ContentSecurity configuration resource.
If undefined, default settings are applied, designed to work with most upstream web application services.
object no

SidecarGateway.spec.applications[].routes[].secured.accessControlRef

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

SidecarGateway.spec.applications[].routes[].secured.contentSecurityRef

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

SidecarGateway.spec.applications[].telemetryRef

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

SidecarGateway.spec.applications[].upstream

Field Description Type Required Default Allowed Values
protocol defines HTTP protocol version used to communicate with the upstream. At most one of http1, http2 and auto can be set.
Default: auto: {}
object no auto{...} auto{}, http1{}, http2{}
timeouts defines the timeout settings. object no
tls defines the TLS settings. object no

SidecarGateway.spec.applications[].upstream.protocol

Field Description Type Required Default Allowed Values
auto specifies to negotiate the protocol with TLS ALPN (if TLS is enabled) or, as a fallback, use the same protocol that is used by the downstream connection. object no
http1 specifies to use HTTP/1.1. object no {}
http2 specifies to use HTTP/2. object no

SidecarGateway.spec.applications[].upstream.protocol.auto

Field Description Type Required Default Allowed Values
http2 specifies the settings for when HTTP/2 is inferred. object no

SidecarGateway.spec.applications[].upstream.protocol.auto.http2

Field Description Type Required Default Allowed Values
allowConnect specifies whether to allow proxying Websocket and other upgrades over H2 CONNECT. bool no false true, false

SidecarGateway.spec.applications[].upstream.protocol.http2

Field Description Type Required Default Allowed Values
allowConnect specifies whether to allow proxying Websocket and other upgrades over H2 CONNECT. bool no false true, false

SidecarGateway.spec.applications[].upstream.tls

Field Description Type Required Default Allowed Values
ciphers defines a list of the supported TLS cipher suites. For details on cipher list refer to the envoy documentation on cipher_suites in common tls configuration. string[] no
enable defines if the upstream connection is encrypted. bool no false true, false
protocol defines the supported TLS protocol versions. object no

SidecarGateway.spec.applications[].upstream.tls.protocol

Field Description Type Required Default Allowed Values
maximum supported TLS version. enum no TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3
minimum supported TLS version. enum no TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3

SidecarGateway.spec.applications[].upstream.timeouts

Field Description Type Required Default Allowed Values
http defines the settings for HTTP timeouts. object no

SidecarGateway.spec.applications[].upstream.timeouts.http

Field Description Type Required Default Allowed Values
idle configures the upstream HTTP idle timeout. If this setting is not specified, the value of applications[].downstream.timeouts.http.idle is inherited.
A value of 0 will completely disable the timeout.
string (duration) no See link
maxDuration limits the total duration for an HTTP request/response stream.
Default: 15s
string (duration) no 15s See link

SidecarGateway.spec.envoyClusterRefs[]

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

SidecarGateway.spec.podSelector

Field Description Type Required Default Allowed Values
matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels. map[string]string no

SidecarGateway.spec.sessionHandlingRef

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

SidecarGateway.status

Field Description Type Required Default Allowed Values
conditions describe the status of the SidecarGateway. Condition[] no
pods selected by the SidecarGateway. object[] no
status indicates the overall status of the SidecarGateway. enum no Active, Error, Warning
unmanagedPods lists Pods which are selected by the SidecarGateway, but not managed by the reconciling Airlock Microgateway Operator instance. object[] no

SidecarGateway.status.pods[]

Field Description Type Required Default Allowed Values
envoyConfig indicates the name of the EnvoyConfig CR for the Pod. string no
name indicates the name of a Pod selected by the SidecarGateway. string yes

SidecarGateway.status.unmanagedPods[]

Field Description Type Required Default Allowed Values
managedBy indicates the Airlock Microgateway Operator instance which manages this Pod. string no
name indicates the name of a Pod selected by the SidecarGateway. string yes