| tags | projects | |||||
|---|---|---|---|---|---|---|
|
|
When it comes to building Java apps that run in the cloud, Spring and Spring Boot are clear favorites. It is also increasingly clear that technologies such as Docker and Kubernetes play an important role in the Spring community.
Packing your Spring Boot app in a Docker container and deploying that application to Kubernetes has been possible for a while now and took very little effort. Due to the “make jar not war” motto, all that was required to containerize a Spring Boot app was a container with a JRE to run the jar. Once you had a Docker container, running the containerized Spring Boot application in Kubernetes was just a matter of running the container.
That said, as more and more of you deployed Spring Boot applications to Kubernetes, it became clear we could do better. To that end, we have made several enhancements in Spring Boot 2.3 and are making even more in the forthcoming Spring Boot 2.4 release to make running Spring Boot on Kubernetes an even better experience.
The goal of this guide is to show you how you can run a Spring Boot application on Kubernetes and take advantage of several of the platform features that let you build cloud-native applications.
So what do you need to get started running a Spring Boot app on Kubernetes?
Nothing more than a quick trip to “everyone’s favorite place on the internet: start.spring.io”.
Create a directory for your application. Then run the following cURL command to generate an application from start.spring.io:
$ curl https://start.spring.io/starter.tgz -d dependencies=webflux,actuator | tar -xzvf -Alternatively, click here to open start.spring.io with the correct configuration and click Generate to download the project.
With a basic Spring Boot web application, we now need to create a Docker container. With Spring Boot 2.3, we can use the Spring Boot Maven or Gradle plugin to do this for us, without us needing to modify the application. In order for the build image plugin to work you will need to have Docker installed locally.
$ ./mvnw spring-boot:build-image -Dspring-boot.build-image.imageName=spring-k8s/gs-spring-boot-k8sAfter the build finishes, we should now have a Docker image for our application, which we can check with the following command:
$ docker images spring-k8s/gs-spring-boot-k8s
REPOSITORY TAG IMAGE ID CREATED SIZE
spring-k8s/gs-spring-boot-k8s latest 21f21558c005 40 years ago 257MBNow we can start the container image and make sure it works:
$ docker run -p 8080:8080 --name gs-spring-boot-k8s -t spring-k8s/gs-spring-boot-k8sWe can test that everything is working by making an HTTP request to the actuator/health endpoint:
$ curl http://localhost:8080/actuator/health; echo
{"status":"UP"}Before moving on be sure to stop the running container.
$ docker stop gs-spring-boot-k8sWith a container image for our application (with nothing more than a visit to start.spring.io!) we are ready to get our application running on Kubernetes. To do this, we need two things:
-
The Kubernetes CLI (kubectl)
-
A Kubernetes cluster to which to deploy our application
Follow these instructions to install the Kubernetes CLI.
Any Kubernetes cluster can work, but, for the purpose of this post, we spin one up locally to make it as simple as possible. The easiest way to run a Kubernetes cluster locally is with a tool called Kind. Follow these instructions to install Kind. With Kind installed, we can now create a cluster.
$ kind create clusterAfter Kind creates the cluster, it automatically configures the Kubernetes CLI to point at that cluster. To make sure everything is setup properly, run:
$ kubectl cluster-infoIf you do not see any errors, you are ready to deploy your application to Kubernetes.
To deploy our application to Kubernetes, we need to generate some YAML that Kubernetes can use to deploy, run, and manage our application as well as expose that application to the rest of the cluster.
First create a directory for our YAML:
$ mkdir k8sNow we can use kubectl to generate the basic YAML we need:
$ kubectl create deployment gs-spring-boot-k8s --image spring-k8s/gs-spring-boot-k8s:snapshot -o yaml --dry-run=client > k8s/deployment.yamlThe deployment.yaml file tells Kubernetes how to deploy and manage our application, but it does not let our
application be a network service to other applications. To do that, we need a service resource. Kubectl can help us
generate the YAML for the service resource:
$ kubectl create service clusterip gs-spring-boot-k8s --tcp 80:8080 -o yaml --dry-run=client > k8s/service.yamlBefore applying these YAML files to our Kubernetes cluster, we need to load our Docker image into the Kind cluster. If we do not do this, Kubernetes tries to find the container for our image in Docker Hub, which, of course, does not exist.
$ docker tag spring-k8s/gs-spring-boot-k8s spring-k8s/gs-spring-boot-k8s:snapshot
$ kind load docker-image spring-k8s/gs-spring-boot-k8s:snapshot|
Note
|
We create a new tag for the image, because the default Kubernetes pull policy for images using the latest tag is
Always. Since the image does not exist externally in a Docker repository, we want to use an image pull policy of
Never or IfNotPresent. When a tag other than latest is used, the default Kubernetes pull policy is IfNotPresent.
|
Now we are ready to apply the YAML files to Kubernetes:
$ kubectl apply -f ./k8sThen you can run:
$ kubectl get allYou should see our newly created deployment, service, and pod running:
NAME READY STATUS RESTARTS AGE
pod/gs-spring-boot-k8s-779d4fcb4d-xlt9g 1/1 Running 0 3m40s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/gs-spring-boot-k8s ClusterIP 10.96.142.74 <none> 80/TCP 3m40s
service/kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 4h55m
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/gs-spring-boot-k8s 1/1 1 1 3m40s
NAME DESIRED CURRENT READY AGE
replicaset.apps/gs-spring-boot-k8s-779d4fcb4d 1 1 1 3m40sUnfortunately, we cannot make an HTTP request to the service in Kubernetes directly, because it is not exposed outside of the cluster network. With the help of kubectl we can forward HTTP traffic from our local machine to the service running in the cluster:
$ kubectl port-forward svc/gs-spring-boot-k8s 9090:80With the port-forward command running, we can now make an HTTP request to localhost:9090, and it is forwarded to the service running in Kubernetes:
$ curl http://localhost:9090/actuator; echo{
"_links":{
"self":{
"href":"http://localhost:9090/actuator",
"templated":false
},
"health-path":{
"href":"http://localhost:9090/actuator/health/{*path}",
"templated":true
},
"health":{
"href":"http://localhost:9090/actuator/health",
"templated":false
},
"info":{
"href":"http://localhost:9090/actuator/info",
"templated":false
}
}
}Before moving on be sure to stop the port-forward command above.
Our application runs on Kubernetes, but, in order for our application to run optimally, we recommend implementing several best practices:
Open k8s/deployment.yaml in a text editor and add the readiness, liveness, and lifecycle properties to your file:
apiVersion: apps/v1
kind: Deployment
metadata:
creationTimestamp: null
labels:
app: gs-spring-boot-k8s
name: gs-spring-boot-k8s
spec:
replicas: 1
selector:
matchLabels:
app: gs-spring-boot-k8s
strategy: {}
template:
metadata:
creationTimestamp: null
labels:
app: gs-spring-boot-k8s
spec:
containers:
- image: spring-k8s/gs-spring-boot-k8s:snapshot
name: gs-spring-boot-k8s
resources: {}
livenessProbe:
httpGet:
path: /actuator/health/liveness
port: 8080
readinessProbe:
httpGet:
path: /actuator/health/readiness
port: 8080
lifecycle:
preStop:
exec:
command: ["sh", "-c", "sleep 10"]
status: {}This takes care of best practices 1 and 2.
To address the third best practice, we need to add a property to our application configuration. Since we run our application on Kubernetes, we can take advantage of Kubernetes ConfigMaps to externalize this property, as a good cloud developer should. We now take a look at how to do that.
To enable graceful shutdown in a Spring Boot application, we need to set server.shutdown=graceful.
We can create a properties file that enables graceful shutdown and also exposes all of the Actuator endpoints. We can use the Actuator endpoints as a way of verifying that our application is adding the properties file from our ConfigMap to the list of PropertySources.
Create a new file called application.properties in the k8s directory. In that file add the following properties.
link:app/k8s/application.properties[role=include]Alternatively you can do this in one easy step from the command line by running the following command.
$ cat <<EOF >./k8s/application.properties
server.shutdown=graceful
management.endpoints.web.exposure.include=*
EOFWith our properties file created, we can now create a ConfigMap with kubectl.
$ kubectl create configmap gs-spring-boot-k8s --from-file=./k8s/application.propertiesWith our ConfigMap created, we can see what it looks like:
$ kubectl get configmap gs-spring-boot-k8s -o yamlapiVersion: v1
data:
application.properties: |
server.shutdown=graceful
management.endpoints.web.exposure.include=*
kind: ConfigMap
metadata:
creationTimestamp: "2020-09-10T21:09:34Z"
name: gs-spring-boot-k8s
namespace: default
resourceVersion: "178779"
selfLink: /api/v1/namespaces/default/configmaps/gs-spring-boot-k8s
uid: 9be36768-5fbd-460d-93d3-4ad8bc6d4dd9The last step is to mount this ConfigMap as a volume in the container.
To do this, we need to modify our deployment YAML to first create the volume and then mount that volume in the container:
link:app/k8s/deployment.yaml[role=include]With all of our best practices implemented, we can apply the new deployment to Kubernetes. This deploys another Pod and stops the old one (as long as the new one starts successfully).
$ kubectl apply -f ./k8sIf your liveness and readiness probes are configured correctly, the Pod starts successfully and transitions to a ready state. If the Pod never reaches the ready state, go back and check your readiness probe configuration. If your Pod reaches the ready state but Kubernetes constantly restarts the Pod, your liveness probe is not configured properly. If the pod starts and stays up, everything is working fine.
You can verify that the ConfigMap volume is mounted and that the application is using the properties file by hitting
the /actuator/env endpoint.
$ kubectl port-forward svc/gs-spring-boot-k8s 9090:80Now if you visit http://localhost:9090/actuator/env you will see property sources contributed from our mounted volume.
{
"name":"applicationConfig: [file:./config/application.properties]",
"properties":{
"server.shutdown":{
"value":"graceful",
"origin":"URL [file:./config/application.properties]:1:17"
},
"management.endpoints.web.exposure.include":{
"value":"*",
"origin":"URL [file:./config/application.properties]:2:43"
}
}
}Before continuing, be sure to stop the port-forward command.
For this part of the guide, you should install Kustomize. Kustomize is a useful tool when working with Kubernetes and targeting different environments (dev, test, staging, production). We use it to generate YAML to deploy another application to Kubernetes that we will then be able to call using service discovery.
Run the following command to deploy an instance of the name-service:
$ kustomize build "github.com/ryanjbaxter/k8s-spring-workshop/name-service/kustomize/multi-replica/" | kubectl apply -f -This should deploy the name-service to your Kubernetes cluster. The deployment should create two replicas for the
name-service:
$ kubectl get pods --selector app=k8s-workshop-name-service
NAME READY STATUS RESTARTS AGE
k8s-workshop-name-service-56b986b664-6qt59 1/1 Running 0 7m26s
k8s-workshop-name-service-56b986b664-wjcr9 1/1 Running 0 7m26sTo demonstrate what this service does, we can make a request to it:
$ kubectl port-forward svc/k8s-workshop-name-service 9090:80
$ curl http://localhost:9090 -i; echo
HTTP/1.1 200
k8s-host: k8s-workshop-name-service-56b986b664-6qt59
Content-Type: text/plain;charset=UTF-8
Content-Length: 4
Date: Mon, 14 Sep 2020 15:37:51 GMT
PaulIf you make multiple requests, you should see different names returned. Also note the header: k8s-host. This should
align with the ID of the pod servicing the request.
|
Note
|
When using the port-forwarding command, it makes only a request to a single pod, so you will only see one host in the response. |
Be sure to stop the port-forward command before moving on.
With our service running, we can modify our application to make a request to the name-service.
Kubernetes sets up DNS entries so that we can use the service ID for the name-service to make an HTTP request to the
service without knowing the IP address of the pods. The Kubernetes service also load balances these requests between
all the pods.
In your application, open DemoApplication.java in src/main/java/com/example/demo. Modify the code as follows:
link:app/src/main/java/com/example/demo/DemoApplication.java[role=include]Notice the URL in the WebClient request is k8s-workshop-name-service. That is the ID of our service in Kubernetes.
Since we updated the application code, we need to build a new image and deploy it to Kubernetes:
$ ./mvnw clean spring-boot:build-image -Dspring-boot.build-image.imageName=spring-k8s/gs-spring-boot-k8s
$ docker tag spring-k8s/gs-spring-boot-k8s:latest spring-k8s/gs-spring-boot-k8s:snapshot
$ kind load docker-image spring-k8s/gs-spring-boot-k8s:snapshotAn easy way to deploy the new image is to delete the application pod. Kubernetes automatically creates another pod with the new image we just loaded into the cluster.
$ kubectl delete pod --selector app=gs-spring-boot-k8sOnce the new pod is up and running, you can port forward requests to the service:
$ kubectl port-forward svc/gs-spring-boot-k8s 9090:80Now, if you make a request to the service, you should see which pod of the name-service the request was sent to:
$ curl http://localhost:9090; echo
Hello Paul from k8s-workshop-name-service-56b986b664-wjcr9Verifying load balancing can be a bit more challenging. You can continually make the same cURL request and watch to see if the pod ID changes. A tool such as watch can be quite useful for this:
$ watch -n 1 curl http://localhost:9090The watch command makes the cURL request every second. The downside is that you have to watch your terminal and wait. Eventually, though, you should notice the pod ID change.
A quicker way to see things switch is to run the watch command and then delete the pod that is currently servicing requests:
$ kubectl delete pod k8s-workshop-name-service-56b986b664-wjcr9When you do this, you should immediately notice the pod ID change in the watch command.
Getting a Spring Boot application running on Kubernetes requires nothing more than a visit to start.spring.io. The goal of Spring Boot has always been to make building and running Java applications as easy as possible, and we try to enable that, no matter how you choose to run your application. Building cloud-native applications with Kubernetes involves nothing more than creating an image that uses Spring Boot’s built-in image builder and taking advantage of the capabilities of the Kubernetes platform. In part two of our look at Spring Boot and Kubernetes, we will look at how Spring Cloud fits into this story.