CR SidecarGateway

SidecarGateway is the link between the protected application and Airlock Microgateway. It specifies the configuration of the Airlock Microgateway Engine injected into the application Pod including configuration options for topics like TLS and HTTP, remote IP identification and request normalization. Additional CRs cover different aspects of web application security are referenced.
If references are not explicitly configured, default settings designed to work with most upstream services will be applied.

Without a Custom Resource SidecarGateway referring to a Pod, the Microgateway Engine does not forward any traffic to the upstream application. This results in Connection Refused errors on access.

The status of referenced CRs (including nested CRs) is available via CR SidecarGateway status - missing references are reported with further information in the form of a message and a reason. This helps to find problems and solve them quickly.

Example configuration

The following example shows a simple Custom Resource SidecarGateway configuration.

  • It is important to understand how Airlock Microgateway Engine configuration and security settings are applied to web applications:
  • When a web application is deployed with an inject annotation (see example below), a Microgateway Engine sidecar is injected by the Microgateway Operator during Pod creation.
  • To apply Microgateway Engine settings to a web application Pod, a corresponding CR SidecarGateway is required.
  • When multiple web application pods with Microgateway Engine sidecars are deployed in the same namespace, multiple SidecarGateway CRs can be created.
  • Labels of the web application Pod can be added to the corresponding CR SidecarGateway under spec.podSelector.matchLabels. Reverse lookup determines the pod(s) whose labels match the matchLabels in the CR.

Example Deployment:

copy
apiVersion: apps/v1  
kind: Deployment  
metadata:  
  labels:  
    app: example-app    
    name: example-app  
spec:  
  selector:  
    matchLabels:  
      app: example-app  
  template:  
    metadata:  
      annotations:  
        sidecar.microgateway.airlock.com/inject: "true"      
      labels:  
        app: example-app     
    spec:
      ...

Example SidecarGateway:

copy
apiVersion: microgateway.airlock.com/v1alpha1 
kind: SidecarGateway 
metadata: 
  name: sidecar-gateway-example 
spec: 
  podSelector: 
    matchLabels: 
      app: example-app 
  applications: 
    - containerPort: 5051
      routes: 
        - pathPrefix: / 
          secured: 
            contentSecurityRef: 
              name: content-security-example
  • SidecarGateway configuration to protect a web application:
  • Our example uses a simple web application Pod with the label app: example-app.
  • The spec.applications.containerPort is the container port of the web application that has to be secured by Airlock Microgateway. The default 8080 can be overridden to connect to the application's HTTP port. In our example, the example-app Pod listens for requests on port 5051.
  • The security settings to be applied are referenced in the CR ContentSecurity named content-security-example.

For the default and an example configuration of the CR SidecarGateway, see CR Sidecar Gateway reference documentation. The example configuration in the API Reference documentation matches the label of our example deployment above.

TLS settings

TLS is disabled by default for both downstream and upstream traffic.

  • In the downstream section (receiving requests):
  • With TLS enabled, set the required secretRef to a TLS Secret that contains a server certificate.
  • Optionally, configure the TLS protocol version. However, the defaults should be fine for most cases and can be looked up at Envoy TLS minimum/maximum protocol settings.
  • The TLS ciphers can be configured, if required. However, the default ciphers should be fine for most cases. Additional information on envoy cipher suite configuration can be found at Envoy cipher suites (BoringSSL-based).

For more information, see also TLS secrets in Kubernetes.

  • In the upstream section (connections to the application):
  • Enabling TLS for upstream establishes TLS connections between the Microgateway Engine and the upstream application.
  • Optionally, configure the TLS protocol versions. However, the defaults should be fine for most cases and can be looked up at Envoy TLS minimum/maximum protocol settings.
  • The TLS ciphers can be configured, if required. However, the default ciphers should be fine for most cases. Additional information on envoy cipher suite configuration can be found at Envoy cipher suites (BoringSSL-based).

For the default and a simple example configuration, see CR Sidecar Gateway reference documentation, spec.applications.downstream.tls or spec.applications.upstream.tls.

Client certificate settings for downstream mTLS

To secure access to the application with mutual TLS (mTLS), Airlock Microgateway needs to instruct clients to provide a valid client certificate during a TLS handshake. The exact behavior can be configured using the downstream.tls.clientCertificate option.

Client certificate handling options

Description

ignored: {}

  • Disables the verification of client certificates (default).

optional:

  • Client certificates will be verified if presented by the client.
  • A client certificate is not required to access the application.

required:

  • Clients must present a valid client certificate.
  • Additional settings for client certificate verification can be configured.

The following example shows available client certificate verification settings:

...
      downstream:
        tls:
          enable: true
          secretRef:
            name: server-cert-secret
          clientCertificate:
            required: 
              trustedCA:
                verificationDepth: 1
                certificates:
                  - secretRef:
                      name:  trusted-ca-secret 
              crl:
                validationMode: VerifyChain
                lists:                                   
                  - secretRef:
                      name: crl-secret  
              allowedSANs:
                - sanType: DNS
                  matcher: 
                    exact: "api.example.com"
                                            
              certificatePinning: 
                allowedHashes: 
                - a434460ca545...
                allowedSPKIs: 
                - seFTOlIPG28LywSNn6wbPqRiV6GRJ66z+0J0Cwt2lMQ=
...

Use the following table as a starting point when configuring the Secret files required for mTLS.

Resource:

Description:

Example:

trustedCA

  • List of secrets containing trusted CA certificates.

The certificate is expected in a generic secret with the key ca.crt:

apiVersion: v1
kind: Secret
metadata:
  name: trusted-ca-secret
data:
  ca.crt: <base64 encoded ca certificate>

crl

  • List of secrets containing a Certificate Revocation List (CRL) in PEM format.

The CRLs are expected in a generic secret with the key ca.crl:

apiVersion: v1
kind: Secret
metadata:
  name: crl-secret
data:
  ca.crl: <base64 encoded crl>

For the default and example configuration, see CR Sidecar Gateway reference documentation, spec.applications.downstream.tls.

HTTP protocol settings

The HTTP protocol version used for downstream and upstream traffic is automatically selected by default based on the capabilities of upstream and downstream systems.

If the default HTTP auto selection does not work as expected, try an explicit protocol version configuration instead.

  • In the downstream section (connections from clients):
  • The default ​auto setting allows requests with all HTTP protocol versions.
  • Protocol versions can be configured explicitly. Note that with an explicit protocol version, non-matching requests may be blocked.
  • In the upstream section (connections to application):
  • With the default auto setting, the Microgateway Engine selects the most appropriate HTTP protocol version.
  • Protocol versions can be configured explicitly. Note that the application may block requests with an explicit protocol version due to a version mismatch.

To forward gRPC requests through Microgateway Engine, set the downstream.protocol and the upstream.protocol to http2{}.

For the default and example configuration, see CR Sidecar Gateway reference documentation, spec.applications.downstream.protocol or spec.applications.upstream.protocol.

Downstream remote IP settings

In Kubernetes/Openshift environments, it is extremely unlikely for an external client to have a direct connection to an application. Usually, requests pass through one or more reverse proxy layers, hiding the client's real IP address. Sometimes, the client remote IP is an input parameter to Microgateway features like deny rule exceptions based on a client IP range. Other times, it is simply important to log the correct client IP.

Therefore, the remoteIP settings define how the remote IP address of a client is identified.

  1. The remote IP extraction may be configured with either of these options:
  2. With connectionIP: {} the remoteIP address of the directly connected client will be used.
  3. The alternative customHeader option can only hold a single client IP address (IPv4/IPv6).
    If required is set to true, the Microgateway Engine will block the request if the custom header is missing.
  4. The default and most common option is to have upfront reverse proxies include the client IP address in an xff (X-Forwarded-For) header. The standard actually allows the header to hold multiple IPv4/IPv6 addresses.
    If a request passes through a proxy, it may add its IP address to the right side of the address list in the xff header.
    The numTrustedHops defines which item in the list will be selected as the remote IP address. It counts from right and defaults to 1, which selects the rightmost entry in the IP list in the header.
    Example:
    203.0.113.59 would be selected by default for the header X-Forwarded-For: 203.0.113.182,150.172.238.178,203.0.113.59.

    5. Note that the connectionIP will be used as a fallback in case the XFF header contains fewer IPs than configured as numTrustedHops.

For the default and example configuration, see CR Sidecar Gateway reference documentation, spec.applications.downstream.

Limiting request headers length

The maximum size of the request header block, encompassing all headers and their values, can be restricted by setting a header length limit.

Additional limits on requests can be configured in the CR Limits.

For the default and example configuration, see CR Sidecar Gateway reference documentation, spec.applications.downstream.restrictions.http.

Routes settings

By default, all traffic is filtered and secured using reasonable default security settings. However, with todays web applications consisting of different parts, for example HTML pages and REST APIs, with different requirements, specific security policies can be applied using ContentSecurity CRs.

  • Microgateway Engine filtering can even be bypassed completely by explicitly setting a route to unsecured{}.
  • Since the first matching route will be applied to every request, the order of route configuration entries is significant, i.e., a fallback path has to be placed at the end of the routes list.

If you exclude a route by setting it unsecured{}, the target application is exposed to untrusted downstream traffic. Use this option with caution!

For the default and example configuration, see CR Sidecar Gateway reference documentation.