Configuring Gateway Routes

This topic describes how to add, update, and manage API routes for apps that use a Spring Cloud Gateway for Kubernetes instance.

What are API routes

Spring Cloud Gateway instances match requests to target endpoints using configured API routes. A route is assigned to each request by evaluating a number of conditions, called predicates. Each predicate may be evaluated against request headers and parameter values. All of the predicates associated with a route must evaluate to true for the route to be matched to the request. The route may also include a chain of filters, to modify the request before sending it to the target endpoint, or the received response.

Add Routes to Gateway

To add an API route to a Spring Cloud Gateway for Kubernetes instance, you must create a resource of type SpringCloudGatewayMapping and a resource of type SpringCloudGatewayRouteConfig.

Define Route Config

The definition for SpringCloudGatewayRouteConfig specifies:

apiVersion: ""
kind: SpringCloudGatewayRouteConfig
  name:            # Name given to this route configuration (required)
  service:         # Kubernetes Service to route traffic to for specified `spec.routes`.
    name:          # Name of the service, required unless route defines `uri`.
    namespace:     # If not set will use the RouteConfig's namespace.
    port:          # If not set will use one of the available service ports.
  routes:          # Array of API routes.
    - uri:         # Optional full uri, will override ``
      ssoEnabled:  # Enable sso validation. See "Using Single Sign-On"
      predicates:  # See Available Predicates below
      filters:     # See Available Filters below
      order:       # Route processing order, same as Spring Cloud Gateway
      tags:        # Classification tags, will be applied to methods in the generated OpenAPI documentation

As example, create a file called myapp-route-config.yaml, with the following YAML definition:

apiVersion: ""
kind: SpringCloudGatewayRouteConfig
  name: myapp-route-config
    name: myapp
  - predicates:
      - Path=/api/**
      - StripPrefix=1

Note: To simplify configuration, `StripPrefix=1` is applied by default when no value for StripPrefix is set.

Map Routes to Gateway

The definition for SpringCloudGatewayMapping specifies:

  • A Gateway instance, which will serve traffic to the provided API routes
  • A RouteConfig instance, which will define the routes

Create a file called myapp-mapping.yaml, with the following YAML definition:

apiVersion: ""
kind: SpringCloudGatewayMapping
  name: myapp-mapping
    name: my-gateway
    namespace: my-gateway-ns
    name: myapp-route-config

For the value, substitute your Gateway instance name. For the value, substitute your client app Kubernetes service name. The gatewayRef.namespace and routeConfigRef.namespace parameters are both optional; if you do not specify a value for either parameter, the mapping namespace will be used.

Apply the two definitions to your Kubernetes cluster:

$ kubectl apply -f myapp-route-config.yaml
$ kubectl apply -f myapp-mapping.yaml

Spring Cloud Gateway for Kubernetes processes the two objects and updates the Gateway instance named in the spec.gateway property value (in this example, the my-gateway instance). For the routes configured in the spec.routes section, the Gateway instance will route traffic to the app named in the spec.service property value (in this example, the myapp app).

After creating the mapping and route config resources, you should be able to access the myapp app at the fully qualified domain name (FQDN) used by the Gateway instance and the path /api/*. For example, if your Gateway instance is exposed by an Ingress resource at the domain, you can access the myapp app at the following URL:

Available Predicates

For more detailed documentation on how to use the OSS Spring Cloud Gateway predicates, see the Spring Cloud Gateway OSS predicates documentation.

Predicate Description
After matches requests made after a certain datetime
Before matches requests made before a certain datetime
Between matches requests made between two certain datetimes
Cookie matches requests with a certain cookie
Header matches requests with a certain header
Host matches requests with a certain host pattern
Method matches requests to HTTP method (GET/POST)
Path matches requests with path of certain pattern(s)
Query matches requests with certain query parameter (optional with value pattern)
RemoteAddr matches requests of a certain remote IP address
Weight Split requests between a set of targets in a group

Available Filters

For more detailed documentation on how to use the OSS Spring Cloud Gateway filters, see the Spring Cloud Gateway OSS filters documentation. The detailed documentation on additional filters provided by Spring Cloud Gateway for Kubernetes commercial product are listed on the Commercial Route Filters page.

Filter Description
AddRequestHeader Adds a header to a request
AddRequestParameter Adds a request parameter to a request query string
AddResponseHeader Adds a header to a matching response
DeDupeResponseHeader Removes duplicates of certain headers
CircuitBreaker Wraps routes in a circuit breaker
FallbackHeaders Adds circuit breaker exception to a header
ClientCertificateHeader Validate X-Fowarded-Client-Cert header certificate (optional fingerprint)
MapRequestHeader Maps a header from another one
PrefixPath Adds a prefix to a matching request path
PreserveHostHeader Preserves original host header when sending a request
RateLimit Determines if a matching request is allowed to proceed base on volume
RedirectTo Redirects a matching request with certain HTTP code to a certain URL
RemoveRequestHeader Removes a header from a matching request.
RemoveResponseHeader Removes a header from a response
RemoveRequestParameter Removes a query parameter from a matching request
RewritePath Replaces a matching request path using regular expression
RewriteLocationResponseHeader Modifies the value of the location response header
RewriteResponseHeader Rewrite the response header value
Roles List authorized roles needed to access route
Scopes List scopes needed to access route
SecureHeaders Adds some headers to a response per a security recommendation.
SetPath Manipulates a matching request path
SetResponseHeader Replaces a certain response header
SetStatus Sets HTTP status of a response
SSO Login Redirects to authenticate if no valid Authorization token
StripPrefix Strips parts from a path of a matching request (default: 1)
Retry Retries a matching request
RequestSize Constrains a matching request with a certain request size
SetRequestHostHeader Overrides host header value of a matching request
TokenRelay Forwards OAuth2 access token to downstream resources