SidecarGateway

microgateway.airlock.com/v1alpha1


SidecarGateway contains the configuration how to configure the Airlock Microgateway Engine when used as Sidecar Container within the Pod of an application.

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

      telemetryRef:
        name: telemetry-example

  envoyClusterRefs:
    - name: envoy-cluster-example-1
apiVersion: microgateway.airlock.com/v1alpha1
kind: SidecarGateway
metadata:
  name: default

SidecarGateway

Field Type Description Required Default Allowed Values
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata yes
spec object Specification of the desired sidecar gateway behavior. no
status object Most recently observed status of the SidecarGateway which is populated by the system. This data is read-only and may not be up to date. yes

SidecarGateway.spec

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

SidecarGateway.spec.applications[]

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

SidecarGateway.spec.applications[].downstream

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

SidecarGateway.spec.applications[].downstream.protocol

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

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

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

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

Field Type Description Required Default Allowed Values
allowConnect bool Allows proxying Websocket and other upgrades over H2 connect. no false true, false

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

Field Type Description Required Default Allowed Values
allowConnect bool Allows proxying Websocket and other upgrades over H2 connect. no false true, false

SidecarGateway.spec.applications[].downstream.remoteIP

Field Type Description Required Default Allowed Values
connectionIP object ConnectionIP configures to use the source IP address of the direct downstream connection. no
customHeader object CustomHeader specifies to use a custom header for remote IP extraction. no
xff object XFF configures to use the standard ‘X-Forwarded-For’ header for IP extraction. no

SidecarGateway.spec.applications[].downstream.remoteIP.customHeader

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

SidecarGateway.spec.applications[].downstream.remoteIP.xff

Field Type Description Required Default Allowed Values
numTrustedHops uint32 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. no 1 [1, 4294967295]

SidecarGateway.spec.applications[].downstream.requestNormalizations

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

SidecarGateway.spec.applications[].downstream.restrictions

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

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

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

SidecarGateway.spec.applications[].downstream.tls

Field Type Description Required Default Allowed Values
ciphers string[] 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. no
clientCertificate object ClientCertificate defines the TLS settings for verification of client certificates.
At most one of ignored, optional and required can be set.
Default: ignored: {}
no ignored{...} ignored{}, optional{}, required{}
enable bool Enable defines if the downstream connection is encrypted. no false true, false
protocol object Protocol defines the supported TLS protocol versions. no
secretRef object SecretRef defines the reference to the TLS server certificate (secret of type kubernetes.io/tls). no
xfcc enum 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)
no Sanitize, ForwardOnly, AppendAndForward, SanitizeAndSet, AlwaysForwardOnly

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

Field Type Description Required Default Allowed Values
ignored object Ignored disables verification of the client certificate. no
optional object 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.
no
required object Required contains settings for client certificate verification. A client must present a valid certificate.
At least one of trustedCA and certificatePinning must be set.
no

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

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

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

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

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

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

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

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

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

Field Type Description Required Default Allowed Values
certificates object[] Certificates defines the list of secretRefs containing trusted CA certificates. yes
verificationDepth uint32 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.
no 1 [0, 4294967295]

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

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

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

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

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

Field Type Description Required Default Allowed Values
allowedSANs object[] 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.
no
crl object CRL defines the Certificate Revocation List (CRL) settings. no
certificatePinning object 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.
no
trustedCA object TrustedCA defines which CA certificates are trusted. no

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

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

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

Field Type Description Required Default Allowed Values
contains string 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.
no
exact string Exact defines an explicit match on the string specified here.
Only one of exact, prefix, suffix, regex or contains can be set.
no
ignoreCase bool IgnoreCase indicates whether the matching should be case-insensitive. In case of a regex match, the regex gets wrapped with a group (?i:...). no false true, false
prefix string 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.
no
regex string 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.
no
suffix string 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.
no

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

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

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

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

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

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

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

Field Type Description Required Default Allowed Values
allowedHashes string[] 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.
no
allowedSPKIs string[] 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.
no

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

Field Type Description Required Default Allowed Values
certificates object[] Certificates defines the list of secretRefs containing trusted CA certificates. yes
verificationDepth uint32 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.
no 1 [0, 4294967295]

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

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

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

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

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

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

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

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

SidecarGateway.spec.applications[].downstream.timeouts

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

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

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

SidecarGateway.spec.applications[].envoyHTTPFilterRefs

Field Type Description Required Default Allowed Values
prepend object[] Prepend selects the relevant EnvoyHTTPFilters which are added before those configured by the Airlock Microgateway. no

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

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

SidecarGateway.spec.applications[].routes[]

Field Type Description Required Default Allowed Values
pathPrefix string PathPrefix defines the path prefix used during route selection. no /
secured object Secured enables WAF processing for this route. no
unsecured object 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.
no

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

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

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

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

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

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

SidecarGateway.spec.applications[].telemetryRef

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

SidecarGateway.spec.applications[].upstream

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

SidecarGateway.spec.applications[].upstream.protocol

Field Type Description Required Default Allowed Values
auto object 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. no
http1 object HTTP1 specifies to use HTTP/1.1. no
http2 object HTTP2 specifies to use HTTP/2. no

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

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

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

Field Type Description Required Default Allowed Values
allowConnect bool Allows proxying Websocket and other upgrades over H2 connect. no false true, false

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

Field Type Description Required Default Allowed Values
allowConnect bool Allows proxying Websocket and other upgrades over H2 connect. no false true, false

SidecarGateway.spec.applications[].upstream.tls

Field Type Description Required Default Allowed Values
ciphers string[] 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. no
enable bool Enable defines if the upstream connection is encrypted. no false true, false
protocol object Protocol defines the supported TLS protocol versions. no

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

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

SidecarGateway.spec.applications[].upstream.timeouts

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

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

Field Type Description Required Default Allowed Values
idle string (duration) Timeout defines the settings for http timeouts. 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.
no See link
maxDuration string (duration) MaxDuration defines the total duration for a HTTP request/response stream.
Default: 15s
no 15s See link

SidecarGateway.spec.envoyClusterRefs[]

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

SidecarGateway.spec.podSelector

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

SidecarGateway.spec.sessionHandlingRef

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

SidecarGateway.status

Field Type Description Required Default Allowed Values
conditions object[] no
pods object[] no
status string yes
unmanagedPods object[] no

SidecarGateway.status.conditions[]

Field Type Description Required Default Allowed Values
lastTransitionTime string (timestamp) Last time the condition transitioned from one status to another. no rfc3339 timestamp
message string A human-readable message indicating details about the transition. no
reason string The reason for the condition’s last transition. no
status enum Status of the condition, one of True, False, Unknown. yes True, False, Unknown
type string Type of SidecarGateway condition. yes

SidecarGateway.status.pods[]

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

SidecarGateway.status.unmanagedPods[]

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