Getting Started with Spring Cloud Gateway for Kubernetes

Here you will find information about how you can quickly get started with Spring Cloud Gateway for Kubernetes. These instructions assume that Spring Cloud Gateway for Kubernetes has already been installed.

Before starting the configuration of the product, it's useful to define some key terms used throughout the guide.

Spring Cloud Gateway for Kubernetes is, at its core, a configurable matching, transformation, and routing engine for requests and responses.

Requests can be routed to multiple targets.

route: Gateway instances match incoming requests to target destinations using API routes.
predicate: A route is assigned to each request by evaluating a number of conditions, known as predicates. All of the predicates associated with a route must evaluate to true for the route to be matched to the request.
filter: A route may also include a chain of filters, to modify matching requests before forwarding them to the destination, or the received responses before returning them to the gateway client.

Operator and custom resources

Installing Spring Cloud Gateway for Kubernetes deploys the Spring Cloud Gateway for Kubernetes Operator application to your cluster, along with three custom resource definitions. The Operator's role is to watch for and react to changes to instances of these three custom resource types:

SpringCloudGateway resources describe the deployed gateway instances.
SpringCloudGatewayRouteConfig resources describe a set of API routes that can be applied to one or more gateways.
- API routes determine which requests are sent to a which destinations, and contain a destination URI, a collection of predicates, and a collection of filters. A route is matched to an inbound request if all of its predicates return true when applied to that request.
- Predicates control which routes are applied to which requests, by matching against properties of those requests, such as their HTTP headers or query parameters.
- Filters allow you to modify inbound requests before they are forwarded to their destinations, and the returned responses before returning them back to gateway clients.
SpringCloudGatewayMapping resources define which route configurations are applied to which gateways.

Setting up your first Gateway

This section demonstrates using Spring Cloud Gateway for Kubernetes to route to https://httpbingo.org. You create the following:

a SpringCloudGateway instance to do the routing
a SpringCloudGatewayRouteConfig to describe the route, its predicate, and its filters
a SpringCloudGatewayMapping to map the SpringCloudGatewayRouteConfig to the SpringCloudGateway

Create a Gateway instance

To create a Spring Cloud Gateway for Kubernetes instance, create a file called gateway-config.yaml containing the following YAML definition:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGateway
metadata:
  name: my-gateway
spec:
  count: 1

Next, apply this definition to your Kubernetes cluster:

kubectl apply --filename gateway-config.yaml

This configuration creates a new gateway instance. By default, the instance is created alongside a ClusterIP service in the current namespace. To check the status of the gateway, you can use the Kubernetes get command.

$ kubectl get springcloudgateway my-gateway

NAME               READY   REASON
my-gateway         True    Created

Create a route configuration

Next, create SpringCloudGatewayRouteConfig to define the route configuration.

Create a file called route-config.yaml with the following YAML definition:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGatewayRouteConfig
metadata:
  name: my-gateway-routes
spec:
  routes:
    - uri: https://httpbingo.org
      predicates:
        - Path=/httpbingo/**
      filters:
        - AddRequestHeader=X-Request-Extra, Hello from Spring Cloud Gateway!

Here you specify a single route to https://httpbingo.org, with a Path predicate matching on /httpbingo/**.

You also specify a single filter, AddRequestHeader, which adds an extra header to the forwarded requests, X-Request-Extra, with the value "Hello from Spring Cloud Gateway!".

The gateway implicitly adds a default filter, StripPrefix=1, to each route, unless an alternative is explicitly specified. This is for convenience because it's often a requirement, and removes the first segment of the path from the incoming request before it is forwarded to the destination.

As a result, when calling {gateway-url}/httpbingo/ with this example configuration, the request is routed to https://httpbingo.org, and requests to {gateway-url}/httpbingo/anything are redirected to https://httpbingo.org/anything.

Apply the route configuration:

kubectl apply --filename route-config.yaml

And check the status:

$ kubectl get springcloudgatewayrouteconfig my-gateway-routes

NAME                AGE
my-gateway-routes   13s

Create a mapping

Finally, create a SpringCloudGatewayMapping object that maps the route config to the gateway.

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

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGatewayMapping
metadata:
  name: test-gateway-mapping
spec:
  gatewayRef:
    name: my-gateway
  routeConfigRef:
    name: my-gateway-routes

Apply the route configuration:

kubectl apply --filename mapping.yaml

And check the status:

$ kubectl get springcloudgatewaymapping test-gateway-mapping

NAME                   AGE
test-gateway-mapping   11s

To validate that the gateway is functioning from your local machine, you can set up port-forwarding to the ClusterIP service by running:

kubectl port-forward service/my-gateway 8080:80

Access the gateway with the URL http://localhost:8080/httpbingo/anything. You should see the response from https://httpbingo.org/anything, with the HTTP headers containing "X-Request-Extra": ["Hello from Spring Cloud Gateway!"].

For information about activating external access to your Gateway instance, see the Activating External Access guide.

Cleaning up

After you've finished with a Gateway instance, you can delete it using the Kubernetes cli delete command:

kubectl delete springcloudgateway my-gateway

Route Configurations and Mappings must be deleted separately. To do this, run:

kubectl delete springcloudgatewayrouteconfig my-gateway-routes
kubectl delete springcloudgatewaymapping test-gateway-mapping

Spring Cloud Gateway for Kubernetes as an API gateway

This section describes how to use Spring Cloud Gateway for Kubernetes as an API gateway for a microservice architecture.

This scenario uses the Animal Rescue backend API sample application, and reuses the SpringCloudGateway instance named my-gateway defined above.

Note This topic uses sample apps from the spring-cloud-services-samples / animal-rescue repository on GitHub. To follow along, clone the repository and check the instructions in README.md.

Deploy the backend app

The following YAML file describes the backend application deployment, and exposure through a service on Kubernetes:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: animal-rescue-backend
spec:
  selector:
    matchLabels:
      app: animal-rescue-backend
  template:
    metadata:
      labels:
        app: animal-rescue-backend
    spec:
      containers:
        - name: animal-rescue-backend
          image: springcloudservices/animal-rescue-backend
          env:
            - name: spring.profiles.active
              value: k8s
          resources:
            requests:
              memory: "256Mi"
              cpu: "100m"
            limits:
              memory: "512Mi"
              cpu: "500m"
---
apiVersion: v1
kind: Service
metadata:
  name: animal-rescue-backend
spec:
  ports:
    - port: 80
      targetPort: 8080
  selector:
    app: animal-rescue-backend

This assumes that the Animal Rescue backend application is available to be pulled by Kubernetes from an image repository named springcloudservices/animal-rescue-backend.

To deploy the application, save the YAML into a file named animal-rescue-backend.yaml and run the following command:

kubectl apply --filename animal-rescue-backend.yaml

Add API Routes to the Gateway

Now that the Animal Rescue backend application is running and is exposed as a service named animal-rescue-backend, you can describe the route configuration to be applied to my-gateway.

Create a file called animal-rescue-backend-route-config.yaml with the following definition:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGatewayRouteConfig
metadata:
  name: animal-rescue-backend-route-config
spec:
  service:
    name: animal-rescue-backend
  routes:
    - predicates:
        - Path=/api/**
      filters:
        - StripPrefix=1

Create another file called animal-rescue-backend-mapping.yaml with the following definition:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGatewayMapping
metadata:
  name: animal-rescue-backend-mapping
spec:
  gatewayRef:
    name: my-gateway
  routeConfigRef:
    name: animal-rescue-backend-route-config

The SpringCloudGatewayRouteConfig and SpringCloudGatewayMapping object kinds are processed by the Spring Cloud Gateway for Kubernetes Operator to update the Gateway instance referenced in the spec.gatewayRef property value.

The destination to route traffic to for the configured routes is supplied in the spec.service property value. Using spec.service is an alternative to specifying the uri field on each route, as shown in the httpbin example earlier. Using spec.service is the recommended approach to use when you want to route to destination applications that are exposed as services in the Kubernetes cluster, whereas uri is useful when you need to route off-cluster to external services.

Apply both definitions to your Kubernetes cluster:

kubectl apply --filename animal-rescue-backend-route-config.yaml
kubectl apply --filename animal-rescue-backend-mapping.yaml

If your cluster has an ingress configured, then assuming that my-gateway is accessible using the ingress with a fully-qualified domain name of my-gateway.my-example-domain.com, the Animal Rescue backend API will be available under the path my-gateway.my-example-domain.com/api/....

One of the endpoints available in the sample application is GET /api/animals, which lists all of the animals available for adoption. This endpoint should now be accessible using the following command:

# Using httpie (https://httpie.io):
http my-gateway.my-example-domain.com/api/animals

# Or using curl:
curl my-gateway.my-example-domain.com/api/animals

If you are not using an ingress, you can forward a port from your local machine to the gateway service:

kubectl port-forward service/my-gateway 8080:80

And in another terminal window, call the /api/animals endpoint:

# Using httpie (https://httpie.io):
http localhost:8080/api/animals

# Or using curl:
curl localhost:8080/api/animals

Benefits of a Gateway in a microservice architecture

In the example above, the gateway routes to a single API. If you have multiple backend services, you can configure separate routes and paths for each one, while your frontend app only needs to be configured with the gateway URL.

Using route filters you can modify the requests to your backend apps, as well as adjust the responses that are returned to the frontend. Route filters provided by Spring Cloud Gateway for Kubernetes support rate limiting, response caching, and circuit breaker patterns among many others.

You can also easily secure your endpoints with single-sign on (SSO) by configuring it on the gateway, instead of re-implementing it across your separate microservices. You can fine-tune the access control per-route with the Scopes or Roles filters.