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, as well as the applied contentSecurityRef.

• In addition, SidecarGateway ties the security rules and other functionality to the application by referencing the following other CRs:
• CR ContentSecurity
• CR EnvoyHTTPFilter
• CR EnvoyCluster
• CR Telemetry

General tips for working with CRs

• CLI:
• Use kubectl explain <replace with CRD name> --recursive to list all available options and the YAML structure.
• Check the CRD description texts with kubectl explain <replace with CRD name and path> of the available options for more details.

• API Reference documentation:
• Click on the link to open the CR-related documentation in a new browser tab or window: CRD Reference documentation. See also the API Reference documentation links at the end article.

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, 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 is used to determine the pod(s) whose labels match the matchLabels in the CR.

Example Deployment:

copy

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

Example SidecarGateway:

copy

apiVersion: microgateway.airlock.com/v1alpha1 
kind: SidecarGateway 
metadata: 
  name: example-sidecargateway 
spec: 
  podSelector: 
    matchLabels: 
      app: echo-server 
  applications: 
    - containerPort: 5051
      routes: 
        - pathPrefix: / 
          secured: 
            contentSecurityRef: 
              name: content-security-sample 

• SidecarGateway configuration to protect a web application:
• Our example uses a simple echo application Pod with the label app: echo-server.
• 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 echo-server Pod listens for requests on port 5051.
• The security settings to be applied are referenced in the CR ContentSecurity named content-security-sample.

See also the API Reference documentation link at the end of this article.

TLS is disabled by default for both downstream and upstream traffic. Enable it in the SidecarGateway configuration.

Example:

...
    downstream: 
      tls: 
        enable: true 
        secretRef: 
          name: server-cert-secret
    upstream: 
      tls: 
        enable: true
...  

• 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).

See also the API Reference documentation link at the end of this article.

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.

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>

See also the API Reference documentation link at the end of this article.

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.

Example:

...

      downstream: 
        protocol: 
          auto: {}

...    

• 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 with an explicit protocol version, the application may block requests due to a version mismatch.

See also the API Reference documentation link at the end of this article.

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. Othertimes, 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.

Example:

...

      downstream: 
        remoteIP: 
          xff: 
            numTrustedHops: 1

...    

0. The remote IP extraction may be configured with either of these options:
1. 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.
    

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

2. 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.
3. With connectionIP: {} the remote address of the directly connected client will be used.

See also the API Reference documentation link at the end of this article.

With the option requestNormalizations it is possible to transform the request path before it is matched or routed.

Example:

...

      downstream: 
          requestNormalizations: 
            mergeSlashes: true 
            normalizePath: true

...    

See Envoy path transformation for more information.

See also the API Reference documentation link at the end of this article.

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

...
  applications:
    downstream:
      restrictions: 
        http:                
          headersLength: 60Ki 
... 

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

See also the API Reference documentation link at the end of this article.

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.
By explicitly setting a route to unsecured, Microgateway Engine filtering can even be bypassed completely.

...
      routes: 
      - pathPrefix: /healthz 
        unsecured: {} 
      - pathPrefix: /api 
        secured: 
          contentSecurityRef: 
            name: api-content-security 
      - pathPrefix: /ui 
        secured: 
          contentSecurityRef: 
            name: ui-content-security 
      - pathPrefix: / 
        secured: 
          contentSecurityRef: 
            name: fallback-content-security
...  

In this example, the healthz path (a typical health-check endpoint for applications) is left 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!

See also the API Reference documentation link at the end of this article.

• API Reference:
• CR Sidecar Gateway reference documentation

• Internal links:
• Annotations for Microgateway Engine injection
• CR ContentSecurity

• External links:
• TLS secrets in Kubernetes
• Envoy cipher suites (BoringSSL-based)
• Envoy path transformation