Standalone Gateway with Spring Cloud Gateway for K8s

Here you will learn how to run the Gateway application component of Spring Cloud Gateway for Kubernetes as a standalone process, by directly running the application jar file. This process can be used to run the product outside a Kubernetes environment.

Important SSO and TokenRelay are configured differently in standalone mode. See the following sections for details.

Prepare Gateway configuration

The Gateway application is very configurable, and like all Spring Boot applications supports a wide range of methods for externalizing configuration. The following is a suggestion for how you might choose to set out the configuration, but you are free to choose different methods if these are better suited to your deployment.

Routes

For simplicity, we recommend creating a separate configuration file to hold the route definitions you would like to load into the Gateway application, for example routes.yaml:

# ####################################################
# routes.yaml
# ####################################################
spring:
  cloud:
    gateway:
      routes:
        - id: example_basic_auth_route
          uri: https://host.example.com
          predicates:
            - Path=/example-a/**
          filters:
            - StripPrefix=1 # StripPrefix is defaulted to 1 if not specified when using Spring Cloud Gateway on Kubernetes
            - BasicAuth=[base64 encoded username]:[base64 encoded password] # add this filter to activate basic auth on this route
        - id: example_token_relay_route
          uri: https://host.example.com
          predicates:
            - Path=/example-b/**
          filters:
            - SsoLogin # add this filter to activate SSO login on this route
            - StripPrefix=1
            - TokenRelay # add this filter to activate token relay on this route
        - id: example_response_cache_route
          uri: https://host.example.com
          predicates:
            - Path=/example-c/**
          filters:
            - StripPrefix=1
            - LocalResponseCache
            - AddRequestHeader=X-Request-red, blue # an example Spring Cloud Gateway OSS filter

For more information on the available per-route configuration supported by Spring Cloud Gateway for Kubernetes, see the available predicates and available filters documentation.

Routes can also be queried and set at runtime using the Spring Cloud Gateway OSS Actuator API.

Application configuration

The rest of the application configuration can be stored separately in an application.yaml file. This example uses Spring Boot's activation properties feature to allow parts of the application to be switched on and off using profiles.

---
# ####################################################
# application.yaml
#
# Provides default settings, along with configuration for optional features
# which can be activated using Spring Boot profiles.
#
# Available profiles:
# - prometheus            exposure of metrics in Prometheus endpoint
# - redis                 storage of session and rate limiting data in Redis
# - response-cache-local  HTTP request caching
# - sso                   OIDC configuration
# - tls-server            TLS server termination configuration
# - wavefront             publication of metrics and tracing information to Wavefront
# - zipkin                publication of tracing information to Zipkin
#
# Activating the prometheus or wavefront profiles will turn on metrics features
# Activating the wavefront or zipkin profiles will turn on tracing features
# ####################################################
management:
  wavefront:
    metrics:
      export:
        enabled: false
  endpoint:
    gateway:
      enabled: true # Toggles the Gateway Actuator on or off
  endpoints:
    web:
      exposure:
        include:
          - gateway
          - health
          - info
          - conditions
          - configprops
          - metrics
          - prometheus
  server:
    port: 8090 # actuators port
  tracing:
    enabled: false
spring:
  application:
    name: spring-cloud-gateway-for-kubernetes # application name

---
# Local response cache configuration (for activating LocalResponseCache filter)
spring:
  config:
    activate:
      on-profile: response-cache-local
  cloud:
    gateway:
      filter:
        local-response-cache:
          enabled: true
          time-to-live: 42s # Time-to-live before a cache entry is expired (300s, 5m, ..)
          size: 100MB     # Maximum size of cache (10MB, 900KB, 1GB,..)

---
# Metrics configuration
spring:
  config:
    activate:
      on-profile: prometheus|wavefront
  cloud:
    gateway:
      metrics:
        enabled: true
        tags:
          path:
            enabled: true
management:
  endpoint:
    metrics:
      enabled: true # Toggles metrics on or off

---
# Prometheus configuration
spring:
  config:
    activate:
      on-profile: prometheus
management:
  prometheus:
    metrics:
      export:
        enabled: true # Toggles publication of Prometheus metrics on or off

---
# Redis configuration
spring:
  config:
    activate:
      on-profile: redis
  cloud:
    gateway:
      k8s:
        redis:
          trustedCertificate: /path/to/trusted-ca-certificate.pem # Set to trust a custom CA when 'spring.data.redis.ssl' is true
  data:
    redis:
      host: localhost
      port: 6379
      ssl: false
      username: default
      password: password123
  session:
    redis:
      namespace: spring:session:my-unique-gateway-identifier
      repository-type: default # 'default' or 'indexed' for WebSockets

---
# SSO configuration
spring:
  config:
    activate:
      on-profile: sso
  security:
    oauth2:
      client:
        provider:
          sso:
            issuer-uri:  http://localhost:30200/oauth/token
            authorization-uri:  http://localhost:30200/oauth/authorize
        registration:
          sso:
            client-id: animal-rescue     # SSO client id
            client-secret: springone2020 # SSO client secret
            scope: openid,profile        # SSO scopes
sso:
  roles-attribute-name: roles # Roles attribute name used to extract user roles for Roles filter

---
# Tracing configuration
spring:
  config:
    activate:
      on-profile: zipkin|wavefront
management:
  tracing:
    enabled: true # Enable tracing

---
# TLS server configuration
spring:
  config:
    activate:
      on-profile: tls-server
  cloud:
    gateway:
      k8s:
        tls:
          port: 8443 # Port to listen on for HTTPS requests
          servers:   # Set a list of hosts for which TLS is activated
            - hosts: # Array of hostnames for which to perform TLS termination using the specified certificate
                - host-a.tls.spring.animalrescue.online
                - host-b.tls.spring.animalrescue.online
              secret: src/test/resources/certs/secret-1 # Path to directory containing `tls.crt` and `tls.key` files to load certificate and key from

---
# Wavefront configuration
spring:
  config:
    activate:
      on-profile: wavefront
management:
  wavefront:
    api-token: 44444-34this-45is-123a-sampletoken # Wavefront API token
    uri: https://example.wavefront.com # Wavefront instance URI
    source: ${spring.application.name} # Wavefront source identifier
    metrics:
      export:
        enabled: true # Toggles publication of Wavefront metrics on or off

---
# Zipkin Tracing configuration
spring:
  config:
    activate:
      on-profile: zipkin
management:
  zipkin:
    tracing:
      endpoint: https://zipkin.default.svc.cluster.local:9411/api/v2/spans # Zipkin server url

The Spring Cloud Gateway for Kubernetes Gateway application is based on the Spring Cloud Gateway OSS project. See the OSS reference documentation for a complete list of configuration properties that can be passed to the OSS Gateway library.

Download the Gateway jar file

Download the Spring Cloud Gateway for Kubernetes Gateway executable jar file:

Visit the Broadcom Support portal and log in.
Navigate to the Spring Cloud Gateway for Kubernetes product listing.
In the Releases list, select the version that you wish to install or upgrade to.
Download "Spring Cloud Gateway for Kubernetes Gateway executable jar file."

Launch the Gateway

You are now ready to run the Gateway application.

Copy the downloaded jar file to a location (such as a virtual machine, server or local machine) where it can be run using a suitable Java VM.
Copy your configuration files (routes.yaml and application.yaml) into the same directory.

Start the Gateway application using the following command:

java -jar gateway-<version>.jar \
  --add-exports java.base/jdk.internal.ref=ALL-UNNAMED \
  --add-exports java.base/sun.security.x509=ALL-UNNAMED \
  --add-opens java.base/java.lang=ALL-UNNAMED \
  --add-opens java.base/java.nio=ALL-UNNAMED \
  --add-opens java.base/sun.nio.ch=ALL-UNNAMED \
  --add-opens java.management/sun.management=ALL-UNNAMED \
  --add-opens jdk.management/com.sun.management.internal=ALL-UNNAMED \
  --spring.config.additional-location=file:./application.yaml,file:./routes.yaml

The Spring Boot profile activations in the example application.yaml file allow for optional features to be switched on and off by specifying the set of profiles to activate. You can do this by providing a comma-separated list of profiles on the command line. For example, to activate the Prometheus and SSO features:
```
java -jar gateway-<version>.jar \
  ...other arguments... \
  --spring.profiles.active="prometheus,sso"
```
If you want to add an extension to the instance, you can use the Spring Boot loader.path feature. No extra changes in the extension jar are required. Note only the gateway jar is set as part of the classpath (-cp) and the starting class needs to be PropertiesLauncher.
```
java -cp gateway-<version>.jar \
  -Dloader.path="my-extensions" \
  org.springframework.boot.loader.PropertiesLauncher
  ...other arguments... \
  --spring.profiles.active="prometheus,sso"
```

SSO Standalone Configuration

SSO features are supported in a Standalone instance, but because the configuration is not handled automatically, there are some things to consider about the filter setup on top of the required configurations, including:

Add the filter named SsoLogin to the route's filters list.
SsoLogin filter should always be placed first in the filters list of a route.

If used with TokenRelay filter, SsoLogin must be placed before TokenRelay.

spring:
  cloud:
    gateway:
      routes:
      - id: token-relay
        uri: https://example.org
        filters:
        - SsoLogin
        - TokenRelay

Token Relay Standalone Configuration

The token relay feature is supported when running Spring Cloud Gateway in standalone mode outside of Kubernetes. However, in standalone mode, the Gateway must be configured manually, rather than by the Spring Cloud Gateway for Kubernetes Operator.

This means are some extra things to be considered:

The TokenRelay filter must be explicitly added to the route's filters list.

If used in conjunction with OpenID Connect Single Sign-On, the TokenRelay filter must be placed after the SsoLogin filter.

spring:
  cloud:
    gateway:
      routes:
      - id: token-relay
        uri: https://example.org
        filters:
        - SsoLogin
        - TokenRelay