Gateway instances in Spring Cloud Gateway for K8s

The Getting started guide describes the creation of an initial Spring Cloud Gateway instance to get you up and running with routes and route mappings quickly, and this guide describes more features that are available on each Spring Cloud Gateway instance. Configuration for these features is picked up from your SpringCloudGateway resource definitions by the Spring Cloud Gateway for Kubernetes Operator, and applied to the respective gateway pods that underpin each gateway instance.

Configuring environment variables

You can define a map of environment variables to pass to the gateway using the spec.env property. As with any Spring application, this provides a flexible means to override configuration which is not explicitly exposed in the SpringCloudGateway resource definition. The following example uses environment variables to configure the timeout for connections from the gateway to downstream services, and the Spring Framework web package logging level.

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGateway
metadata:
  name: gateway-demo
spec:
  ...
  env:
    - name: spring.cloud.gateway.httpclient.connect-timeout
      value: "90s"
    - name: logging.level.org.springframework.web
      value: debug

The following environment variables are considered invalid and will be removed:

• JAVA_*: like JAVA_OPTS or JAVA_TOOL_OPTIONS, use spec.java-opts instead.
• JDK_JAVA_OPTIONS: used by Spring Cloud Gateway for Kubernetes.

Deactivating the SecureHeaders global filter

Spring Cloud Gateway for Kubernetes activates a custom SecureHeaders filter globally by default. This filter adds the following security best-practise headers to responses:

Activated Secure Header	Default Value
Cache-Control	no-cache, no-store, max-age=0, must-revalidate
Pragma	no-cache
Expires	0
X-Content-Type-Options	nosniff
Strict-Transport-Security	max-age=631138519
X-Frame-Options	DENY
X-XSS-Protection	1; mode=block

If you do not want these headers to be added to responses, you can deactivate this global filter behavior by setting the spring.cloud.gateway.secure-headers.disabled environment variable to true:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGateway
metadata:
  name: my-gateway
spec:
  env:
    - name: spring.cloud.gateway.secure-headers.disabled
      value: "true"

To deactivate a specific header for a specific route, you can apply the RemoveResponseHeader filter to the route. For example, to remove the X-Frame-Options header, you would define:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGatewayRouteConfig
metadata:
  name: my-gateway-routes
spec:
  routes:
    - uri: https://httpbingo.org
      predicates:
        - Path=/remove-x-frame-options/**
      filters:
        - RemoveResponseHeader=X-Frame-Options

To deactivate a specific header globally for all routes, you can pass the header name in the spring.cloud.gateway.secure-headers.disabled environment variable, as described in the SecureHeaders filter documentation:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGateway
metadata:
  name: my-gateway
spec:
  env:
    - name: spring.cloud.gateway.filter.secure-headers.disable
      value: "x-frame-options"

Configuring Java environment options

To allow for Gateway instance Java VM tuning, JVM options can be specified in the SpringCloudGateway resource:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGateway
metadata:
  name: my-gateway
spec:
  java-opts: -XX:+PrintFlagsFinal -Xmx512m

The Spring Cloud Gateway for Kubernetes Operator will apply these options to the underlying gateway instance pods and restart them.

Configuring session expiration

If you want to discard inactive sessions after a certain time (e.g. 10 minutes), add the inactive-session-expiration-in-minutes configuration:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGateway
metadata:
  name: my-gateway
spec:
  sso:
    secret: my-sso-credentials
    inactive-session-expiration-in-minutes: 10

This does not modify any authorization server token expiration ('time to live') configuration. It only affects the session information managed inside the gateway.

Configuring hardware resources

Similarly to other Kubernetes resource types, you can optionally override the required memory and CPU for a Gateway under spec.resources:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGateway
metadata:
  name: my-gateway
spec:
  resources:
    requests:
      memory: "512Mi"
      cpu: "1"
    limits:
      memory: "1Gi"
      cpu: "2"

By default each instance is initialized with:

Resource	Requested	Limit
Memory	1Gi	1Gi
CPU	0.5	(no limit)

Note that requesting less than the suggested values may cause issues and is not recommended.

Configuring probes

Similarly to other Kubernetes resources, you can optionally configure the livenessProbe, readinessProbe and startupProbe for a Gateway to suit your requirements.

By default each instance is initialized with the following configuration:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGateway
metadata:
  name: my-gateway
spec:
  podOverrides:
    containers:
      - name: gateway
        livenessProbe:
          initialDelaySeconds: 5
          failureThreshold: 10
          periodSeconds: 3
          timeoutSeconds: 1
          successThreshold: 1
          httpGet:
            port: 8090
            path: actuator/health/liveness
            scheme: HTTP
        readinessProbe:
          initialDelaySeconds: 5
          failureThreshold: 10
          periodSeconds: 3
          timeoutSeconds: 1
          successThreshold: 1
          httpGet:
            port: 8090
            path: actuator/health/readiness
            scheme: HTTP
        startupProbe:
          initialDelaySeconds: 10
          failureThreshold: 30
          periodSeconds: 3
          timeoutSeconds: 1
          successThreshold: 1

Applying custom labels to the Gateway pods

Custom labels can be added to the Gateway configuration. These labels will be propagated to the pods created by the Operator.

For example:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGateway
metadata:
  name: test-gateway-tracing
  labels:
    test-label: test
spec:
  count: 2

Then the pods can be listed by specifying the label:

kubectl get pods --selector=test-label=test

Customizing the service type

By default, the gateway is exposed with a ClusterIP service. You can change the type of this service to a NodePort or a LoadBalancer by specifying spec.service.type. You can also configure the exposed port by specifying spec.service.nodePort. If not specified, the port will be assigned automatically.

For example:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGateway
metadata:
  name: my-gateway
spec:
  service:
    type: NodePort
    nodePort: 32222

Note that for local development, your cluster needs to be configured to expose your chosen nodePort before you can send traffic to the nodes from the host.

Configuring path predicates to match on more specific paths first

In the case where a request matches the predicates of multiple routes, Spring Cloud Gateway for Kubernetes will select the first matching route it encounters in its internal ordered list.

You can use the route type's order field to prioritize specific routes, however it still might be difficult to coordinate the correct order, especially if different teams manage the routes.

Alternatively, Spring Cloud Gateway for Kubernetes provides an environment variable to control the ordering of routes by path length:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGateway
metadata:
  name: my-gateway
spec:
  env:
    - name: spring.cloud.gateway.k8s.route.order
      value: pathlength

By setting this flag on the gateway, it will order the routes by the more specific path. For example, Path=/org/users/** will be preferred over Path=/org/**.

Note the following behavior:

• With this flag set, if multiple paths are provided in Path predicates, then the routes are ordered by the first path in their Path predicate. For example, if we have route A with Path=/org/**,/abc/123/** and route B with Path=/org/users/**,/abc/**, then internally, route B would be ordered before route A, because the first path in route B's Path predicate (/org/users/**) is more specific than that of route A (/org/**). Therefore a request to /abc/123, would match with route B.
• A route's explicit order value, if provided, takes precedence over path specificity ordering. A route with a lower order value (lower values have higher precedence) and less specific path will match before a route with a higher order value and more specific path.