This topic describes how to quickly get started using Spring Cloud Gateway for Kubernetes to provide an API gateway for a microservice architecture.

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

This will give an overview of managing route configurations for applications providing Application Programming Interfaces (API) via a Gateway instance. This overview assumes that Spring Cloud Gateway for Kubernetes management components have already been installed.

The components are

  • Gateway Instances - Represent each one of the Spring Cloud Gateways deployed

  • Route Configurations - Is a set of routes that can be applied to one or many gateways

  • Mappings - A mapping defines which route configurations go with which gateways

Create Gateway Instance

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

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

Next, apply this definition to your Kubernetes cluster:

$ kubectl apply -f gateway-config.yaml

This configuration will create a new Gateway instance. By default, the instance will be created alongside a ClusterIP service in the current namespace. To check the status of it, you can use the Kubernetes get command.

$ kubectl get scg my-gateway

NAME               READY   REASON
my-gateway         True    Created

To add routes and to map the routes to the gateway, we need to create a SpringCloudGatewayRouteConfig object describing the routes and a SpringCloudGatewayMapping object that maps the route config to the gateway.

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://github.com
    predicates:
      - Path=/github/**
    filters:
      - StripPrefix=1

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 both the definitions to your Kubernetes cluster.

The instance will include one route (test-route) that uses a Path predicate to define the path within the gateway, and the StripPrefix filter to remove the path before redirecting.

To validate that the gateway is functioning locally you can port-forward the ClusterIP service.

$ kubectl -n=spring-cloud-gateway port-forward service/my-gateway 8080:80

You should now be able to access the Gateway from localhost:8080/github.

For information about enabling external access to your Gateway instance, see Configure External Access.

Deploy Client App

In this section we will describe a sample scenario using the Animal Rescue backend API sample application. The following YAML describes the backend application deployment as a service on Kubernetes. For the sake of example we will assume that the target namespace is animal-rescue on the Kubernetes cluster.

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 there is an image available in your container 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 -f animal-rescue-backend.yaml --namespace animal-rescue

Add API Routes to Gateway

Now that the Animal Rescue backend application is running 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 SpringCloudGatewayMapping and SpringCloudGatewayRouteConfig object kinds are processed by the Spring Cloud Gateway for Kubernetes management components to update the desired Gateway instance provided in the spec.gatewayRef property value. The application to route traffic for the configured routes is supplied in the spec.service property value.

Apply both definitions to your Kubernetes cluster.

$ kubectl apply -f animal-rescue-backend-route-config.yaml
$ kubectl apply -f animal-rescue-backend-mapping.yaml

Assuming that my-gateway had an ingress applied already for FQDN 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 requests. This endpoint should now be accessible using the following command.

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

# Using curl
$ curl my-gateway.my-example-domain.com/api/animals

If you are not using an ingress, you can port forward the gateway:

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

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

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

# Using curl
$ curl localhost:8080/api/animals

For more information about adding API routes for an app to a Gateway instance, see Add Routes to Gateway.

Delete Gateway Instance

Gateway instances can be easily deleted using the Kubernetes cli delete command.

$ kubectl delete scg my-gateway

After that, if you list the existing Gateways with kubectl get scg you'll notice it's no longer running.

Note: Deleting a Gateway does not delete related Route Configuration or Mappings. For that, you can use kubectl delete scgrc <routeconfig-name> or kubectl delete scgm <mapping-name>.

check-circle-line exclamation-circle-line close-line
Scroll to top icon