Spring Into Kubernetes

Here, we’re setting the jkube.generator.name property to the exact same image name we’re using for the spring-boot-maven-plugin. By default, JKube tries to push the latest tag for any SNAPSHOT project. However, since we aren’t building a latest tag locally, it will not be able to find it. We use the docker.skip.tag property to turn that feature off.

JKube supports various authentication options, for Docker Hub, but we are going to use the credentials stored in our ~/.docker/config.json file. Since we established these credentials earlier via docker login, we can use the kubernetes-maven-plugin to push our image to Docker Hub:

./mvnw k8s:push

Once it is finished, the output should look like this (using your Docker Hub repository name, of course):

Congratulations! The Spring Boot application image is now published on Docker Hub for all the world to use. We now need to create some Kubernetes resources to run our application.

Creating Kubernetes Resources

This is where JKube really starts to shine. With zero configuration, we can use the kubernetes-maven-plugin to create Kubernetes Deployment and Service resource definitions to run our application:

./mvnw k8s:resource

Once that command is complete, we should see something similar to the following output:

JKube will generate the resource definitions in the target/classes/META-INF/jkube/kubernetes directory. Let’s take a look at the generated service:

If not specified, a Service will be of type ClusterIP which means it is only accessible from within the cluster. Let’s update our settings so that the generatedService is of type LoadBalancer:

Here, we set the jkube.enricher.jkube-service.type property to LoadBalancer. Let’s regenerate the resource definitions so that we pick up that change:

./mvnw k8s:resource

Our resources should be ready now, let’s deploy them to Kubernetes.

Deploying to Kubernetes

To deploy our application to Kubernetes, we will ask JKube to “apply” the resource definitions to our cluster:

./mvnw k8s:apply

After this build completes, we should see output similar to this:

We have successfully deployed our application to our Kubernetes cluster! Let’s verify that it is running. First, we need to figure out the LoadBalancer address in use for our Service using the following command:

kubectl describe service spring-k8s

We can see that our LoadBalancer has an ingress IP address set to 192.168.64.100, so we can verify our application is running properly by visiting http://192.168.64.100:8080/hello. We now have a working Kubernetes application! Let’s automate all of these steps a bit to make it easier to make changes to our application.

Creating a Delivery Pipeline

We now have all the pieces in place to create a delivery pipeline. Using the following script, we can quickly deliver our changes to the Kubernetes cluster:

This script loosely mimics the normal Java release process by:

1. Cutting off the SNAPSHOT from our version number in the pom.xml file.
2. Clearing the output directory.
3. Building the image using the spring-boot-maven-plugin.
4. Push the image to Docker Hub.
5. Build the resources necessary to run our application using the kubernetes-maven-plugin.
6. Apply the resources to our Kubernetes cluster using kubernetes-maven-plugin.
7. Update the version number to use the next patch version as SNAPSHOT in the pom.xml file.

Changing the version number each time will force Kubernetes to update our application. Let’s save this script in a file called pipeline.sh (make sure it’s executable) and execute it:

./pipeline.sh

With this handy delivery pipeline at our disposal, now it’s time adapt our Spring Boot application to its new Kubernetes home.

Kube-ifying the Application

To take advantages of some of the features Kubernetes has to offer in our Spring Boot application, we will be using the Spring Cloud Kubernetes library. To do that, first we need to import the Spring Cloud Bill of Materials, or BOM to our project as a dependencyManagement entry:

This imports all Spring Cloud dependencies as dependencyManagement entries, so we don’t have to specify their versions. Thus, all we have to do to incorporate the Spring Cloud Kubernetes library into our project is:

Because of the magic of Spring Boot auto-configuration, that’s all we have to do to activate the library and trigger it to start helping us take advantage of Kubernetes features like ConfigMaps.

Configuring the Application

To build cloud-native, twelve-factor applications, we need to make sure the application can be configured externally. Kubernetes provides ConfigMaps for storing non-sensitive application configuration data. In order to leverage ConfigMaps in our application, we will first need to modify it to use an externalized property. Let’s revisit our HelloController:

Here, we’re injecting the greeting member variable with the configuration property named hello.greeting. Let’s provide a default value for the property in the application.properties file (located in src/main/resources):

Spring Cloud Kubernetes will need access to the Kubernetes API, so the service account used by the Deployment will need elevated permissions. JKube allows us to define resource fragments in the src/main/jkube directory which will be enriched with other data and generated as resource definitions. Let’s define a Role resource fragment named role.yml in the src/main/jkube directory that sets up the permissions required by Spring Cloud Kubernetes:

A Role by itself doesn’t really affect anything. The Role must be bound to a “subject” (in our case, a ServiceAccount) in order for it to be used. Let’s define a RoleBinding resource fragment in the src/main/jkube directory named rolebinding.yml:

Here, we’re binding the spring-cloud-k8s role to the spring-k8s service account (defined using a Maven property reference in the resource fragment). But, where did the spring-k8s service account come from? We will need to define it in the pom.xml file under the kubernetes-maven-plugin configuration using JKube’s XML configuration mechanism:

We again use the Maven project’s artifactId to reference both the ServiceAccount and Deployment names. Now that the we have assigned the correct permissions to our application, we should be able to read the ConfigMap correctly. There’s only one problem, we don’t have a ConfigMap yet. Let’s define another resource fragment in the src/main/jkube directory named configmap.yml:

Normally, we wouldn’t necessarily store environment-specific configuration data (i.e. ConfigMaps) in the same source code repository as our project, but for the purposes of this tutorial, it’s totally fine. There’s only one last piece of the puzzle to put in place before we can start using the ConfigMap ; we need to tell Spring Cloud Kubernetes the name of the ConfigMap to use. By default, Spring Cloud Kubernetes will look for a ConfigMap with the name equal to the spring.application.name property. Let’s set that in our application.properties file:

We now should be able to run our pipeline to take advantage of the ConfigMap we have created:

./pipeline.sh

Once the pipeline is complete, we should be able to visit the /hello endpoint of our service and see the new greeting “Howdy, Spring-K8S!”. Using a ConfigMap is great for non-sensitive configuration data, but sometimes we have configuration data we don’t want anyone to see.

Keeping a Secret

Let’s update our application to use a RESTful service which requires an API Key. Let’s use this Numbers API hosted at Rakuten RapidAPI (you’ll need to sign up to get an API key) to add a little “color” to our greeting responses. First, let’s create a NumberFactsService class (located in the hello package at src/main/java/hello/NumberFactsService.java):

The details of this service aren’t terribly important, other than that it requires a configuration property named hello.apiKey in order to successfully call the API. Let’s add a default value to our application.properties file:

This will allow the project to build without errors, since the hello.apiKey value is required by NumberFactsService. Next, let’s update our HelloController to use this new service:

Now, a fact about a random number will be included with every response. In order to make this work, we need to supply this API key to our application, but we don’t want to use a ConfigMap since it is sensitive information (anyone with our API key could use our account to make API calls).

Once you login to RapidAPI (I used my GitHub account to authenticate), you should see your API key automatically included in the X-RapidAPI-Key field in the API explorer interface for the Numbers API. We need this value to create a secret to be used by our application:

kubectl create secret generic spring-k8s-secret \
         --from-literal=hello.apiKey=[YOUR_API_KEY]

One option to inject this value into our application is to use an environment variable. We do this by using a resource deployment resource fragment located in src/main/jkube/deployment.yml :

Here, we inject the hello.apiKey value from the spring-k8s-secret as an environment variable named HELLO_APIKEY where it will automatically be detected by Spring’s PropertySource abstraction and matched with the hello.apiKey property required by our application.

Another option, however, is to have Kubernetes mount our secrets as a volume and let Spring Cloud Kubernetes automatically scan the secrets volume directory for our properties (again using the deployment.yml resource fragment):

Kubernetes will create a directory named /etc/hello in our container. Inside that directory, there will be a single file named hello.apiKey where the entire contents of the file is the secret’s value. We don’t really need to concern ourselves with these details, as long as we name our properties inside our secrets consistent with what we require in our application and we use Spring Cloud Kubernetes to load them. We do have to tell Spring Cloud Kubernetes where to look and we must do this using a property in a new bootstrap.properties file (located in the src/main/resources directory):

Spring Cloud Kubernetes will scan the /etc/hello directory recursively for secret files and automatically include them as properties in your application.

Now that we have wired everything together, it’s time to run our pipeline again:

./pipeline.sh

When we access the /hello endpoint, we now see our greeting as well as some enlightening information about a random number! We now know how to externalize configurations for our application, but we still need to make sure our application behaves like a true Kubernetes application from cradle to grave.

Controlling the Application Lifecycle

For the most part, Kubernetes will take care of our application’s lifecycle needs automatically. However, a Kubernetes application can provide certain “hints” and behave in certain ways to make Kubernetes’ job much easier.

As a Spring Boot application starts, there is quite a bit of initialization that takes place and it can take a few seconds before the actual web server (in our case Apache Tomcat) is running and responding to requests. To let Kubernetes know when our application is actually “alive”, we can register a liveness probe for its container within the Pod. Spring Cloud Kubernetes automatically configures a new actuator endpoint /actuator/health/liveness (implemented using health groups) for us to use as our liveness probe. To register the liveness probe, we will use a deployment resource fragment, located at src/main/jkube/deployment.yml:

Here, we’re telling Kubernetes to wait 5 seconds before it begins calling our liveness probe and that it should wait 15 seconds between each call. If the liveness probe fails 3 times in a row, our application container will be considered “dead” (not alive) and Kubernetes will kill it. At that point, the container subject to the Pod restart policy (defaults to Always). This liveness probe will run perpetually on the container every 15 seconds throughout the lifecycle of the container. Sometimes, we might want to treat the initial liveness check differently than the ongoing liveness checks. Version 1.16 of Kubernetes introduced the notion of a startup probe which we can use for this purpose:

The startup probe will begin after an initial delay of 10 seconds and check the container every 3 seconds. If it fails for 20 times in a row, the container will be killed. Just because a container is alive doesn’t necessarily mean that it is ready to accept incoming requests.

Kubernetes provides readiness probes as a means to determine whether the Pod should be considered eligible to serve traffic for the application’s Service. Again, Spring Cloud Kubernetes provides an actuator endpoint /actuator/health/readiness purpose-built for this occasion:

The readiness probe will begin checking the application after an initial delay of 5 seconds (after the startup probe is complete of course) and it will continue checking it every 30 seconds. If the readiness probe fails 3 times in a row, the Pod will be removed its Service until the readiness probe succeeds at least once again. By default, only the readinessState health indicator is included in the readiness probe group, but we can implement our own custom health indicator and add it to this group:

A custom readiness health indicator may check external dependencies or include some gating for startup requirements (warming a cache or loading configuration data). The key is that it’s up to the application to know whether or not it is ready to serve traffic. By default, the readinessState health indicator only guarantees that the application context has been fully initialized. People are often confused by the naming, but a readiness probe continues to monitor the readiness of your application throughout its lifecycle and will move it in and out of the Service accordingly. Kubernetes will attempt to keep your Pod running, but at some point, it will decide to terminate it.

Kubernetes applications need to shut down gracefully. When using a HorizontalPodAutoscaler, Kubernetes will be intentionally shutting down instances of applications in order to scale down its resource usage when not needed. As an instance is shutting down, it should try to complete any in-flight transactions. Luckily, there’s a property we can use to turn on this behavior:

Here’, we set the server.shutdown property to graceful and Spring Boot will make sure our application performs a graceful shutdown. But, what happens if an application is gracefully shut down and there is no instance to service traffic?

In order to achieve high availability, we must run multiple instances or “replicas” of our application Pod. Let’s update the configuration of the maven-kubernetes-plugin to tell it to run 3 replicas:

With all of these reliability improvements in place, we can now run our pipeline to redeploy our application:

./pipeline.sh

After the pipeline completes, we can use the following command to see that everything is in place:

kubectl get all

We now see that our application is running, with three pods in service!

Conclusion

We have started from a vanilla Spring Boot application and developed it into a real Kubernetes application. We used the Spring Boot Maven plugin to generate our application images. We used JKube’s Kubernetes Maven plugin to push the image to Docker Hub, generate resources, and apply those resources to our local Minikube cluster. Thank you for following along!

Cleaning Up

We have likely gathered up a bit of clutter along the way. Docker Hub has a bulk delete feature:

To remove your application from the Kubernetes cluster:

./mvnw k8s:undeploy

To shut down Minikube:

minikube stop

To completely remove all traces of Minikube:

minikube delete

To clean up your local Docker system:

docker system prune -a