Partner – Bellsoft – NPI (cat = Spring Boot/Docker)
announcement - icon

Just published a new writeup on how to run a standard Java/Boot application as a Docker container, using the Liberica JDK on top of Alpaquita Linux:

>> Spring Boot Application on Liberica Runtime Container.

Course – LS – All

Get started with Spring and Spring Boot, through the Learn Spring course:


1. Overview

Kubernetes (K8s) is an orchestrator that automates software development and deployment and is a trendy choice of API hosting today, running on-premises or on cloud services such as Google Cloud Kubernetes Service (GKS) or Amazon Elastic Kubernetes Service (EKS). On the other hand, Spring has become one of the most popular Java frameworks.

In this tutorial, we’ll demonstrate how we can set up a protected environment to deploy our Spring Boot application on Kubernetes using Kong Ingress Controller (KIC). We’ll also demonstrate the advanced use of KIC by implementing a simple rate limiter for our application without any coding.

2. Improved Security and Access Control

Modern application deployment, and especially APIs, have many challenges to deal with, like: privacy laws (for example, GPDR), security issues (DDOS), and usage tracking (API quotas and rate limits, for example). In this scenario, modern applications and APIs require extra protection levels against all these challenges, like firewalls, reverse proxies, rate limiters, and related services. Although the K8s environment protects our applications from many of these threats, there are still some measures that we need to adopt to keep our application secure. One of these measures is to deploy an ingress controller and set up its access rules to your application.

An ingress is an object that manages external access to the K8s cluster and the applications deployed on it by exposing HTTP / HTTPS routes to deployed applications and enforcing the access rules to it. In order to expose an application to allow external access, we need to define ingress rules and use an Ingress controller, which is a specialized reverse proxy and load balancer. Generally, ingress controllers are provided by third-party companies and vary in functionality, like Kong Ingress Controller used in this article.

3. Setting Up the Environment

To demonstrate the use of Kong Ingress Controller (KIC) with a Spring Boot application, we need to have access to a K8s cluster, so we can use a full Kubernetes, on-premises installation or cloud-provided, or develop our sample application using Minikube. After starting our K8s environment, we need to deploy Kong Ingress Controller on our cluster. Kong exposes an external IP, which we need to use to get access to our application, so it is a good practice to create an environment variable with that address:

export PROXY_IP=$(minikube service -n kong kong-proxy --url | head -1)

That’s it! Kong Ingress Controller is installed, and we can test if it is running by accessing that PROXY_IP:

curl -i $PROXY_IP

The response should be a 404 error, and that’s right, as we haven’t deployed any application yet, so it should say that no route matched with those values. It’s time to create a sample application, but before that, we may need to install Docker if it’s not available. In order to deploy our application to K8s, we need a way to create a container image, and we can do that using Docker.

4. Creating a Sample Spring Boot Application

Now we need a Spring Boot application and deploy it to a K8s cluster. To generate a simple HTTP server application with at least one exposed web resource, we can do just that:

curl -d dependencies=webflux,actuator -d type=maven-project | tar -xzvf -

One important thing is selecting the default Java version. If we need to use an older version, then a javaVersion property is needed:

curl -d dependencies=webflux,actuator -d type=maven-project -d javaVersion=11 | tar -xzvf -

In this sample application, we selected webflux, which generates a reactive web application with Spring WebFlux and Netty. But another important dependency was added. actuator, which is a monitoring tool for Spring applications and already exposes some web resources, which is exactly what we need to test with Kong. This way, our application already exposes some web resources that we can use. Let’s build it:

./mvnw install

The generated jar is executable, so we can test the application by running it:

java -jar target/*.jar

To test the application, we need to open another terminal and type this command:

curl -i http://localhost:8080/actuator/health

The response must be the application’s health status, provided by the actuator:

HTTP/1.1 200 OK
Content-Type: application/vnd.spring-boot.actuator.v3+json
Content-Length: 15


5. Generating a Container Image from the Application

The process of deploying an application to a Kubernetes cluster involves creating and deploying a container image to a repository accessible by the cluster. In real life, we would push our image to DockerHub or to our own private container image registry. But, as we are using Minikube, let’s just point our Docker client environment variables to Minikube’s Docker:

$(minikube docker-env)

And we can build the application image:

./mvnw spring-boot:build-image

6. Deploying the Application

Now it’s time to deploy the application on our K8s cluster. We’ll need to create some K8s objects to deploy and test our application, and all the required files can be found in the demonstration’s repository:

  • A deployment object for our application with container specification
  • A service definition that allocates a cluster IP address to our Pod
  • An ingress rule to use Kong’s proxy IP address with our routes

A deployment object just creates the necessary pods running our image, and this is the YAML file to create it:

apiVersion: apps/v1
kind: Deployment
  creationTimestamp: null
    app: demo
  name: demo
  replicas: 1
      app: demo
  strategy: {}
      creationTimestamp: null
        app: demo
      - image:
        name: demo
        resources: {}
        imagePullPolicy: Never

status: {}

We are pointing to the image created inside Minikube, getting its full name. Note that it is necessary to specify imagePullPolicy attribute as Never because we are not using an image registry server, so we don’t want K8s to try to download the image but use the one that is already on its internal Docker archive. We can deploy it with kubectl:

kubectl apply -f serviceDeployment.yaml

If the deployment is successful, we can see the message:

deployment.apps/demo created

To have a unified IP address for our application, we need to create a service, which allocates an internal cluster-wide IP address for it, and this is the YAML file to create it:

apiVersion: v1
kind: Service
  creationTimestamp: null
    app: demo
  name: demo
  - name: 8080-8080
    port: 8080
    protocol: TCP
    targetPort: 8080
    app: demo
  type: ClusterIP
  loadBalancer: {}

Now we can also deploy it with kubectl:

kubectl apply -f clusterIp.yaml

Note that we are selecting the label demo that points to our deployed app. To be externally accessible (outside the K8s cluster), we need to create an ingress rule, and in our case, we are pointing it to path /actuator/health and port 8080:

kind: Ingress
  name: demo
  ingressClassName: kong
  - http:
      - path: /actuator/health
        pathType: ImplementationSpecific
            name: demo
              number: 8080

Finally, we deploy it with kubectl:

kubectl apply -f ingress-rule.yaml

Now we have external access using Kong’s proxy IP address:

$ curl -i $PROXY_IP/actuator/health
HTTP/1.1 200 OK
Content-Type: application/vnd.spring-boot.actuator.v3+json
Content-Length: 49
Connection: keep-alive
X-Kong-Upstream-Latency: 325
X-Kong-Proxy-Latency: 1
Via: kong/3.0.0

7. Demonstrating a Rate Limiter

We managed to deploy a Spring Boot application on Kubernetes and use Kong Ingress Controller to provide access to it. But KIC does much more than that: authentication, load balancing, monitoring, rate limiting, and other functions. To demonstrate the real power of Kong, we’ll implement a simple rate limiter to our application, limiting access to only five requests per minute. To do that, we need to create an object named KongClusterPlugin in our K8s cluster. The YAML file does that:

kind: KongClusterPlugin
  name: global-rate-limit
  annotations: kong
    global: true
  minute: 5
  policy: local
plugin: rate-limiting

The plugin configuration allows us to specify extra access rules to our application, and we are limiting access to it to five requests per minute. Let’s apply this configuration and test the results:

kubectl apply -f rate-limiter.yaml

To test it, we can just repeat the CURL command we used before more than five times in a minute, and we’ll get a 429 error:

curl -i $PROXY_IP/actuator/health
HTTP/1.1 429 Too Many Requests
Date: Sun, 06 Nov 2022 19:33:36 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
RateLimit-Reset: 24
Retry-After: 24
X-RateLimit-Remaining-Minute: 0
X-RateLimit-Limit-Minute: 5
RateLimit-Remaining: 0
RateLimit-Limit: 5
Content-Length: 41
X-Kong-Response-Latency: 0
Server: kong/3.0.0

  "message":"API rate limit exceeded"

We can see the response HTTP headers informing the client about the rate limit.

8. Clean Up Resources

To clean up the demonstration, we need to delete all the objects in LIFO order:

kubectl delete -f rate-limiter.yaml
kubectl delete -f ingress-rule.yaml
kubectl delete -f clusterIp.yaml
kubectl delete -f serviceDeployment.yaml

And stop the Minikube cluster:

minikube stop

9. Conclusions

In this article, we demonstrated the use of the Kong Ingress Controller to manage access to a Spring Boot application deployed on a K8s cluster.

As always, the source code can be found over on GitHub.

Course – LS – All

Get started with Spring and Spring Boot, through the Learn Spring course:

res – REST with Spring (eBook) (everywhere)
Comments are closed on this article!