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
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
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
$ 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.
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
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
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
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
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
# 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.
Gateway instances can be easily deleted using the Kubernetes cli
$ 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>.