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
`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
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
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
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
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
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
`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
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	Required
conditions	object[]	no
pods	object[]	no
`status`	string	yes
unmanagedPods	object[]	no

SidecarGateway.status.conditions[]

Field	Type	Description	Required	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