Simplified Configuration

Spring historically was a nightmare to configure. Although the framework improved upon other high-ceremony component models (EJB 1.x, 2.x, etc.), it did come along with its own set of heavyweight usage patterns. Namely, Spring required a lot of XML configuration and a deep understanding of the individual beans needed to construct JdbcTemplates , JmsTemplates , BeanFactory lifecycle hooks, servlet listeners, and many other components. In fact, writing a simple “Hello World” with Spring MVC required understanding of DispatcherServlet and a whole host of Model–View–Controller classes. Spring Boot aims to eliminate all of this boilerplate configuration with some implied conventions and simplified annotations—although, you can still finely tune the underlying beans if you need to.

Starter Dependencies

Spring was used in large enterprise applications that typically leveraged lots of different technologies to do the heavy lifting: JDBC databases, message queues, file systems, application-level caching, etc. Developers often had to stop what they were doing, switch cognitive contexts, figure out what dependencies belonged to which piece of functionality (“Oh, I need the JPA dependencies!”), and spend lots of time sorting out versioning mismatches and other issues that arose when trying to use these various pieces together. Spring Boot offers a large collection of curated sets of libraries for adding these pieces of functionality. These starter modules allow you to add things like:

• Java Persistence API (JPA)

• NoSQL databases like MongoDB, Cassandra, and Couchbase

• Redis caching

• Tomcat/Jetty/Undertow servlet engines

• Java Transaction API (JTA)

Adding a submodule to an application brings in a curated set of transitive dependencies and versions that are known to work together, saving developers from having to sort out dependencies themselves.

Application Packaging

Spring Boot really is a set of bootstrap libraries with some convention for configurations, but there’s no reason why you couldn’t run a Spring Boot application inside your existing application servers as a Web Application Archive (WAR). The idiom that most developers who use Spring Boot prefer for their applications is the self-contained Java Archive (JAR) packaging, where all dependencies and application code are bundled together with a flat class loader in a single JAR. This makes it easier to understand application startup, dependency ordering, and log statements. More importantly, it also helps reduce the number of moving pieces required to take an app safely to production. You don’t take an app and chuck it into an app server; the app, once it’s built, is ready to run as is—standalone—including embedding its own servlet container if it uses servlets. That’s right, a simple java -jar <name.jar> is enough to start your application now! Spring Boot, MicroProfile/Thorntail, and many other frameworks like Vert.x and Dropwizard all follow this pattern of packaging everything into an executable uber-AR.

But what about the management things we typically expect out of an application server?

Production-Ready Features

Spring Boot ships with a module called spring boot actuator that enables things like metrics and statistics about your application. For example, you can collect logs, view metrics, perform thread dumps, show environment variables, understand garbage collection, and show which beans are configured in the BeanFactory. You can expose this information via HTTP or Java Management Extensions (JMX), or you can even log in directly to the process via SSH.

With Spring Boot, you can leverage the power of the Spring framework and reduce boilerplate configuration and code to more quickly build powerful, production-ready microservices. Let’s see how.

Add the HTTP Endpoints

At this point, this piece of code is just a POJO (plain old Java object), and you could (and should) write a unit test that verifies its behavior. To expose this as a REST endpoint, we’re going to make use of the following annotations in Example 2-2 :

@RestController

Tells Spring this is an HTTP controller capable of exposing HTTP endpoints (GET, PUT, POST, etc.)

@RequestMapping

Maps specific parts of the HTTP URI path to classes, methods, and parameters in the Java code

Note that import statements are omitted.

@RestController
@RequestMapping("/api")
public class HelloRestController {

    @RequestMapping(method = RequestMethod.GET, value = "/hello",
            produces = "text/plain")
    public String hello(){
        String hostname = null;
        try {
            hostname = InetAddress.getLocalHost()
                    .getHostAddress();
        } catch (UnknownHostException e) {
            hostname = "unknown";
        }
        return "Hello Spring Boot from " + hostname;
    }

}

In this code, all we’ve done is add the aforementioned annotations. For example, @RequestMapping("/api") at the class level says “map any method-level HTTP endpoints under this root URI path.” When we add @RequestMapping(method = RequestMethod.GET, value = "/hello", produces = "text/plain") , we are telling Spring to expose an HTTP GET endpoint at /hello (which will really be /api/hello ) and map requests with a media type of Accept: text/plain to this method. Spring Boot defaults to using an embedded Tomcat servlet container, but this can be switched to other options like Undertow or Jetty.

If you build the application and run spring-boot:run again, you should be able to reach your HTTP endpoint:

$ mvn clean spring-boot:run

Now if you point your browser to http://localhost:8080/api/hello , you should see a response similar to Figure 2-2 .

Figure 2-2. Successful hello

What if we want to add some environment-aware configuration to our application? For example, instead of saying “Hello,” maybe you want to say “Guten Tag” if we deploy our app in production for German users. We need a way to inject properties into our app.

Externalize Configuration

Spring Boot makes it easy to use external property sources like properties files, command-line arguments, the OS environment, or Java system properties. We can even bind entire “classes” of properties to objects in our Spring context. For example, if we want to bind all helloapp.* properties to the HelloRestController , we can add @ConfigurationProperties(prefix="helloapp") , and Spring Boot will automatically try to bind helloapp.foo and helloapp.bar to Java Bean properties in the HelloRestController class. We can define new properties in src/main/resources/application.properties . The application.properties file was automatically created for us when we created our project. (Note that we could change the filename to application.yml and Spring would still recognize the YAML file as the source of properties.)

Let’s add a new property to our src/main/resources/application.properties file:

helloapp.saying=Guten Tag aus

Next we add the @ConfigurationProperties annotation and our new saying field to the HelloRestController class, as shown in Example 2-3 . Note we also need setters.

@RestController
@RequestMapping("/api")
@ConfigurationProperties(prefix="helloapp")
public class HelloRestController {

    private String saying;

    @RequestMapping(method = RequestMethod.GET, value = "/hello",
            produces = "text/plain")
    public String hello(){
        String hostname = null;
        try {
            hostname = InetAddress.getLocalHost()
                    .getHostAddress();
        } catch (UnknownHostException e) {
            hostname = "unknown";
        }
        return saying + " " + hostname;
    }

    public void setSaying(String saying) {
        this.saying = saying;
    }
}

Stop the application from running (if you haven’t already) and restart it:

$ mvn clean spring-boot:run

Now if you navigate to http://localhost:8080/api/hello , you should see the German version of the saying as shown in Figure 2-3 .

Figure 2-3. Successful German greeting

We can now externalize properties that will change depending on the environment in which we are running. Things like service URIs, database URIs and passwords, and message queue configurations would all be great candidates for external configuration. Don’t overdo it, though; not everything needs to change depending on the environment! Ideally an application would be configured exactly the same in all environments, including timeouts, thread pools, retry thresholds, etc.

Expose Application Metrics and Information

If we want to put this microservice into production, how will we monitor it? How can we get any insight about how things are running? Often our microservices are black boxes unless we explicitly think through how we want to expose metrics to the outside world. Fortunately, Spring Boot comes with a prepackaged starter ( spring-boot-starter-actuator ) that makes doing this a breeze.

Let’s see what it takes to enable the actuator. Open up the pom.xml file for your hello-springboot microservice and add the following Maven dependency in the <dependencies>...</dependencies> section:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Because we’ve added the actuator dependency, our application now can expose a lot of information that will be very handy for debugging or general microservice insight.

Not all endpoints provided by the actuator dependency are exposed by default, however. We need to manually specify which endpoints will be exposed.

Add the following property to src/main/resources/application.properties to expose some technology-agnostic endpoints:

#Enable management endpoints
management.endpoints.web.exposure.include=
        beans,env,health,metrics,httptrace,mappings

Now restart your microservice by stopping it and running:

$ mvn clean spring-boot:run

Try hitting the following URLs and examine what gets returned:

• http://localhost:8080/actuator/beans

• http://localhost:8080/actuator/env

• http://localhost:8080/actuator/health

• http://localhost:8080/actuator/metrics

• http://localhost:8080/actuator/httptrace

• http://localhost:8080/actuator/mappings

Figure 2-4 shows an example of what the http://localhost:8080/env endpoint looks like.

Figure 2-4. Actuator response

Exposing runtime insights like this frees up the developer to just focus on writing code for the microservice that delivers business value. Delegating the heavy lifting and boilerplate to frameworks is definitely a good idea.

Running Outside of Maven

Up to this point we’ve been thinking about development and building our Hello World microservice from the perspective of a developer’s laptop using Maven. But what if you want to distribute your microservice to others or run it in a live environment (development, QA, production)?

Luckily, with Spring Boot it only takes a few steps to get ready for shipment and production. Spring Boot prefers atomic, executable JARs with all dependencies packed into a flat classpath. This means the JAR that we create as part of a call to mvn clean package is executable and contains all we need to run our microservice in a Java environment. To test this out, go to the root of the hello-springboot microservice project and run the following commands:

$ mvn clean package
$ ava -jar target/hello-springboot-1.0.jar

If your project was named demo instead of hello-springboot , then substitute the properly named JAR file ( demo-1.0.jar ).

That’s it!

We’ll notice this sort of idiom when we explore MicroProfile in the next chapter, too.

Add the HTTP Endpoints

You might have noticed that the POJO class HelloRestController in the MicroProfile project has exactly the same implementation as the HelloRestController class in the Spring Boot project. The only exception will be the HTTP endpoint annotations, which we add in Example 3-2 :

@Path

Maps specific parts of the HTTP URI path to classes and methods.

@GET

Specifies that any HTTP GET method will invoke the annotated method. The method won’t be called if the path is the same but the HTTP method is anything other than GET.

@Produces

Specifies the MIME type of the response.

Again, note that import statements are omitted in the following example.

@Path("/api")
public class HelloRestController {

    @GET
    @Produces("text/plain")
    @Path("/hello")
    public String hello() {
        String hostname = null;
        try {
            hostname = InetAddress.getLocalHost()
                    .getHostAddress();
        } catch (UnknownHostException e) {
            hostname = "unknown";
        }
        return "Hello MicroProfile from " + hostname;
    }

}

In this code, all we’ve done is add the aforementioned annotations. For example, @Path("/api") at the class level says “map any method-level HTTP endpoints under this root URI path.” When we add @Path("/hello") and @GET , we are telling MicroProfile to expose an HTTP GET endpoint at /hello (which will really be /api/hello ). The annotation @Produces("text/plain") maps requests with a media type of Accept: text/plain to this method.

If you build the application and run thorntail:run again, you should be able to reach the HTTP endpoint:

$ mvn clean thorntail:run

Now if you point your browser to http://localhost:8080/api/hello , you should see a response similar to the one shown in Figure 3-4 .

Figure 3-4. Successful hello

Now, the same way as we did for Spring Boot, we will see how to inject external properties into our app using MicroProfile’s Config API.

Externalize Configuration

Like Spring Boot, MicroProfile defines a mechanism to externalize configuration. It uses different ConfigSource s to consume configuration from system properties, environment variables, or even from a META-INF/microprofile-config.properties file. Each of these sources has a different priority, so configuration values can be overwritten.

To see how simple it is to consume external configuration, let’s add a new property to our src/main/resources/META-INF/microprofile-config.properties file (remember to create the folder structure and the file if they don’t exist):

helloapp.saying=Guten Tag aus

Now, as shown in Example 3-3 , let’s add the @Inject and @ConfigProperty("helloapp.saying") annotations and our new saying field to the HelloRestController class. Note that, unlike with Spring Boot, we don’t need setters or getters.

@Path("/api")
public class HelloRestController {

    @Inject
    @ConfigProperty(name="helloapp.saying")
    private String saying;

    @GET
    @Produces("text/plain")
    @Path("/hello")
    public String hello() {
        String hostname = null;
        try {
            hostname = InetAddress.getLocalHost()
                                  .getHostAddress();
        } catch (UnknownHostException e) {
            hostname = "unknown";
        }
        return saying + " " + hostname;
    }

}

Because we’ve started using the CDI API in our examples, we’ll also need to add the beans.xml file, with the contents shown in Example 3-4 .

<?xml version="1.0" encoding="UTF-8"?>
<beans
        xmlns="http://xmlns.jcp.org/xml/ns/javaee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
                http://xmlns.jcp.org/xml/ns/javaee/beans_1_1.xsd"
        bean-discovery-mode="all">
</beans>

This file will instruct the CDI API to process all the injection points marked with the @Inject annotation.

Let’s stop our application from running (if we haven’t) and restart it:

$ mvn clean thorntail:run

Now if we navigate to http://localhost:8080/api/hello we should see the German version of the saying, as shown in Figure 3-5 .

Figure 3-5. Successful German hello

Expose Application Metrics and Information

Another similarity with Spring Boot is the ability of MicroProfile applications to expose endpoints that can be used to monitor our applications. To enable this, we need to add the MicroProfile Metrics dependency to our pom.xml file.

Open up the pom.xml file for the hello-microprofile microservice and add the following Maven dependency within the <dependencies>…</dependencies> section:

<dependency>
    <groupId>io.thorntail</groupId>
    <artifactId>microprofile-metrics</artifactId>
</dependency>

Adding this dependency will cause the application to expose a lot of information that will be very handy for debugging and general insight.

Now stop your microservice and restart it by running:

$ mvn clean thorntail:run

Try hitting the URL http://localhost:8080/metrics and examine what gets returned. You should see something like the result in Figure 3-6 .

Figure 3-6. MicroProfile metrics

Easy, right?

Running Outside of Maven

Remember how easy it was to run Spring Boot outside Maven? Luckily, with MicroProfile it just takes the exact same few steps to get a microservice ready for shipment and production.

Just like Spring Boot, MicroProfile prefers atomic, executable JARs with all dependencies packed into a flat classpath. This means the JAR that we create as part of a call to mvn clean package is executable and contains all we need to run our microservice in a Java environment! To test this out, go to the root of the hello-microprofile microservice project and run the following commands:

$ mvn clean package
$ java -jar target/demo-thorntail.jar

That’s it! Exactly the same approach used by Spring Boot.

Configuring the API Gateway

The API gateway needs to connect to hello-microprofile and hello-springboot . The addresses of these microservices must not be hardcoded and should be configured externally. For that reason, we used the variables springbootsvcurl and microprofilesvcurl to provide those “service URLs.”

Another configuration that we need provide to our application is the context path that Camel will use for the REST endpoints. By default, Camel will bind the REST endpoints to /camel/* , but we want to use /api/* instead. For that reason, we will also configure the property camel.component.servlet.mapping.context-path in the src/main/resources/application.properties file.

Let’s add all these properties to that file now:

gateway.springbootsvcurl=localhost:8180
gateway.microprofilesvcurl=localhost:8280

# to reconfigure the camel servlet context-path mapping
# to use /api/* instead of /camel/*
camel.component.servlet.mapping.context-path=/api/*

Calling All Microservices

Now that our API gateway is ready, we will start all four microservices locally using different ports:

• backend : 8080

• hello-springboot : 8180

• hello-microprofile : 8280

• api-gateway : 8380

To start up the backend service on port 8080 , navigate to the backend directory and run the following:

$ mvn clean wildfly:run

To start up the hello-springboot service on port 8180 , navigate to the hello-springboot directory and run the following:

$ mvn clean spring-boot:run -Dserver.port=8180

To start up the hello-microprofile service on port 8280 , navigate to the hello-microprofile directory and run the following:

$ mvn thorntail:run \
  -Dswarm.network.socket-binding-groups.standard-sockets
  .port-offset=200

Finally, start the api-gateway service on port 8380 . Navigate to the api-gateway directory and run the following:

$ mvn spring-boot:run  -Dserver.port=8380

Now, point your browser to http: //localhost:8380/api/gateway to verify that the API gateway calls the two microservices and aggregates both responses in a JSON array, as shown in Figure 4-2 .

Figure 4-2. Successful API gateway

Pods

A pod is a grouping of one or more Docker containers (like a pod of whales?). A typical deployment of a pod, however, will often be one-to-one with a Docker container. If you have sidecar, ambassador, or adapter deployments that must always be colocated with the application, a pod is the way to group them . This abstraction is also a way to guarantee container affinity (i.e., Docker container A will always be deployed alongside Docker container B on the same host).

Kubernetes orchestrates, schedules, and manages pods. When we refer to an application running inside of Kubernetes, it’s running within a Docker container inside of a pod. A pod is given its own IP address, and all containers within the pod share this address (which is different from plain Docker, where each container gets an IP address). When volumes are mounted to the pod, they are also shared between the individual Docker containers running in the pod.

One last thing to know about pods: they are fungible. This means they can disappear at any time (either because the service crashed or because the cluster killed it). They are not like VMs, which you care for and nurture. Pods can be destroyed at any point. This falls within our expectation in a microservice world that things will (and do) fail, so we are strongly encouraged to write our microservices with this premise in mind. This is an important distinction to keep in mind as we talk about some of the other concepts in the following sections.

Labels

Labels are simple key/value pairs that we can assign to pods, like release=stable or tier=backend . Pods (and other resources, but we’ll focus on pods) can have multiple labels that group and categorize them in a loosely coupled fashion, making it easier to build powerful clusters at scale. After we’ve labeled our pods, we can use label selectors to find which pods belong in which group. For example, if we had some pods labeled tier=backend and others labeled tier=frontend , using a label selector expression of tier != frontend we could select all of the pods that are not labeled “frontend.” Label selectors are used under the covers for the next two concepts: replication controllers and services.

ReplicationControllers and Deployments

When talking about running microservices at scale, we will probably be talking about multiple instances of any given microservice. Kubernetes has a concept called the ReplicationController that manages the number of replicas for a given set of microservices. For example, let’s say we wanted to manage the number of pods labeled with tier=backend and release=stable . We could define a ReplicationController with the appropriate label selector, and we would then be able to control the number of those pods in the cluster by adjusting the value of the replicas field in the definition. If we set the replica count equal to 10, then Kubernetes will reconcile its current state to reflect 10 pods running for a given ReplicationController . If there are only five running at the moment, Kubernetes will spin up five more. If there are 20 running, Kubernetes will kill 10 (which 10 it kills is nondeterministic, as far as your app is concerned). Kubernetes will do whatever it needs to converge with the desired state of 10 replicas. You can imagine controlling the size of a cluster very easily with a ReplicationController .

Later, the Kubernetes project introduced another concept called a Deployment that watches the configuration of the replicas (like environment variables, CPU and memory limits, labels, arguments, etc.). If you update any of these configurations, Kubernetes will perform a rolling update to replace the previously declared number of replicas with new ones with the new configuration provided.

We will see examples of Deployment s in action in the next chapter.

Services

The last Kubernetes concept you should understand is the Kubernetes Service . We’ve seen that ReplicationController s can control the number of replicas of a service we have. We also saw that pods die (either crash on their own or be killed, maybe as part of a ReplicationController scale-down event). Therefore, when we try to communicate with a group of pods, we should not rely directly on their IP addresses (each pod will have its own IP address), as pods can come and go. What we need is a way to group pods to discover where they are and how to communicate with them, and possibly load balance against them. That’s exactly what the Kubernetes Service does. It allows us to use a label selector to group our pods and abstract them with a single virtual (cluster) IP that we can then use to discover them and interact with them. We’ll show some concrete examples in the next chapter.

With these simple concepts—pods, labels, ReplicationController s, and Service s, we can manage and scale our microservices the way Google has learned to (or learned not to). It takes many years and many failures to identify simple solutions to complex problems, so we highly encourage you to familiarize yourself with these concepts and experience the power of managing containers with Kubernetes for your microservices.

Minishift

To get started developing microservices with Docker and Kubernetes, we’re going to leverage a free developer tool called Minishift . Minishift is a small tool that runs on a developer’s machine, that contains Docker, Kubernetes, and a web console (actually, it runs Red Hat OpenShift, which is basically a version of Kubernetes with some other developer self-service and application lifecycle management features, but for this book we’ll just be using the Kubernetes APIs).

OpenShift

Red Hat OpenShift 3.x is an Apache v2 licensed open source developer self-service platform, OpenShift Origin , that has been revamped to use Docker and Kubernetes. OpenShift at one point had its own cluster management and orchestration engine, but with the knowledge, simplicity, and power that Kubernetes brings to the world of container cluster management, it would have been silly to try to compete. The broader community is converging around Kubernetes, and Red Hat is all in with Kubernetes.

OpenShift has many features, but one of the most important is that it’s still native Kubernetes under the covers and supports role-based access control, out-of-the-box software defined networking, security, logins, developer builds, and many other things. We mention it here because the flavor of Kubernetes that we’ll use for the rest of this book is based on OpenShift. We’ll also use the oc OpenShift command-line tools, which give us a better user experience and allow us to easily log in to our Kubernetes clusters and control which project we’re deploying into. Minishift has both vanilla Kubernetes and OpenShift. For the rest of this book, we’ll be referring to OpenShift and Kubernetes interchangeably but using OpenShift.

Getting Started with Minishift

With Minishift, you can build, deploy, and run your microservices as Docker containers right on your laptop and then opt to deliver them in a pipeline through other application lifecycle management features inside of OpenShift or with your own tooling.

To continue with the examples and idioms in the rest of this report, please install Minishift now, following the instructions . There are multiple flavors of virtualization (e.g., xhyve, Hyper-V, Linux KVM/libvirtd, and VirtualBox) that you can use with Minishift. The installation instructions contain all of the details you need to get up and running.

To start Minishift, type the following:

$ minishift start

This should take you through the provisioning process and boot the VM. The VM will expose a Docker daemon, the Kubernetes API, and the oc command-line tools. The oc command-line tools will allow you to log in to OpenShift/Kubernetes and manage your projects/namespaces. You could use the kubectl commands yourself, but logging in is easier with the oc login command, so for these examples, we’ll use oc . To have oc available in your path, type:

$ eval $(minishift oc-env)

You might also need to configure OpenShift to enable some Docker images to be executed by any user. This is done by running the following command:

$ minishift addon apply anyuid
-- Applying addon 'anyuid':.

When Minishift starts, you will be logged in as a user called developer . To log in as admin , type:

$ minishift addon apply admin-user
-- Applying addon 'admin-user':..

$ oc login -u admin -p admin
Logged into "https://192.168.64.30:8443" as "admin"
using existing credentials.

You don't have any projects. You can try to create
a new project, by running

    oc new-project 	<projectname>

Next, let’s create a new project/namespace into which we’ll deploy our microservices:

$ oc new-project tutorial
Now using project "tutorial" on server
"https://192.168.64.30:8443".

Although not required to run these examples, installing the Docker CLI for your native developer laptop, is useful as well. This will allow you to list Docker images and Docker containers right from your developer laptop as opposed to having to log in to the Minishift VM. Once you have the Docker CLI installed, you should be able to run Docker directly from your command-line shell:

$ eval $(minishift docker-env)
$ docker ps
$ docker images

Packaging Our Microservices as Docker Images

Navigate to the hello-springboot directory, and create a Dockerfile there with the following contents:

FROM fabric8/java-alpine-openjdk8-jdk
ENV JAVA_APP_JAR hello-springboot-1.0.jar
ENV AB_OFF true
ADD target/hello-springboot-1.0.jar /deployments/

You can then run the following command to build the Docker image:

$ docker build -t rhdevelopers/hello-springboot:1.0 .
Sending build context to Docker daemon  111.3MB
Step 1/4 : FROM fabric8/java-alpine-openjdk8-jdk
 ---> 4353c2196b11
Step 2/4 : ENV JAVA_APP_JAR demo-thorntail.jar
 ---> Running in 777ae0de6868
 ---> 220aece2f437
Removing intermediate container 777ae0de6868
Step 3/4 : ENV AB_OFF true
 ---> Running in 02b3780c59a3
 ---> fc1bc50fc932
Removing intermediate container 02b3780c59a3
Step 4/4 : ADD target/demo-thorntail.jar /deployments/
 ---> 3a4e91b41727
Removing intermediate container b291546e0725
Successfully built 3a4e91b41727

The switch -t specifies the tag name, in the following format: <organization-name>/<image-name>:<version> .

If you want to try your newly built image, you can create a container using the command:

$ docker run -it --rm  \
-p 8080:8080 rhdevelopers/hello-springboot:1.0

The -it switch instructs Docker to create an interactive process and assign a terminal to it. The --rm switch instructs docker to delete this container when we stop it. The -p 8080:8080 instructs Docker to assign port 8080 from the container to port 8080 in the Docker daemon host.

Once your container starts, you can open a new terminal and access it using the curl command:

$ curl $(minishift ip):8080/api/hello
Guten Tag aus 172.17.0.6

These are the basics steps to deploy your application in a Docker container and try it. However, we will not focus on pure Docker containers. Instead, in the next chapter, we will see how to use Kubernetes to run these microservices at scale. Before moving on, don’t forget to stop the running hello-springboot Docker container by pressing Ctrl-C.

Deploying to Kubernetes

There are several ways that we could deploy our microservices/containers inside a Kubernetes/OpenShift cluster. However, for didatic purposes, we will use YAML files that express very well what behavior we expect from the cluster.

In the source code for this report , for each microservice example there is a folder called kubernetes containing two files: deployment.yml and service.yml . The deployment file will create a Deployment object with one replica.

The Deployment also provides at least two environment variables. The one called JAVA_OPTIONS specifies the JVM arguments, like -Xms and -Xmx . The one called GREETING_BACKENDSERVICEHOST replaces the values we defined in our first two microservices to find the BACKEND service, as you’ll see in “Service discovery” .

Here is the deployment.yml file used for the hello-springboot microservice.

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: hello-springboot
  labels:
    app: hello-springboot
    book: microservices4javadev
    version: v1
spec:
  replicas: 1
  selector:
    matchLabels:
      app: hello-springboot
      version: v1
  template:
    metadata:
      labels:
        app: hello-springboot
        book: microservices4javadev
        version: v1
    spec:
      containers:
      - env:
        - name: JAVA_OPTIONS
          value: -Xmx256m -Djava.net.preferIPv4Stack=true
        - name: GREETING_BACKENDSERVICEHOST
          value: backend
        image: rhdevelopers/hello-springboot:1.0
        imagePullPolicy: IfNotPresent
        livenessProbe:
          httpGet: # make an HTTP request
            port: 8080 # port to use
            path: /actuator/health # endpoint to hit
            scheme: HTTP # or HTTPS
          initialDelaySeconds: 20
          periodSeconds: 5
          timeoutSeconds: 1
        name: hello-springboot
        ports:
        - containerPort: 8080
          name: http
          protocol: TCP
        readinessProbe:
          httpGet: # make an HTTP request
            port: 8080 # port to use
            path: /actuator/health # endpoint to hit
            scheme: HTTP # or HTTPS
          initialDelaySeconds: 10
          periodSeconds: 5
          timeoutSeconds: 1

Since the deployment.yml and service.yml files are stored together with the source code for this report, you can deploy the microservices by pointing directly to those files using the following commands. First, deploy the backend microservice:

$ oc create -f http://raw.githubuserconoc create -f http://
  raw.githubusercontent.com/redhat-developer/
  microservices-book/master/backend/kubernetes/deployment.yml

$ oc create -f http://raw.githubuserconoc create -f http://
  raw.githubusercontent.com/redhat-developer/
  microservices-book/master/backend/kubernetes/service.yml

Then deploy the hello-springboot microservice:

$ oc create -f http://raw.githubusercontent.com/
  redhat-developer/microservices-book/master/
  hello-springboot/kubernetes/deployment.yml

$ oc create -f http://raw.githubusercontent.com/
  redhat-developer/microservices-book/
  master/hello-springboot/kubernetes/service.yml

and the hello-microprofile microservice:

$ oc create -f http://raw.githubusercontent.com/
  redhat-developer/microservices-book/
  master/hello-microprofile/kubernetes/deployment.yml

$ oc create -f http://raw.githubusercontent.com/
  redhat-developer/microservices-book/
  master/hello-microprofile/kubernetes/service.yml

Finally, deploy the api-gateway microservice:

$ oc create -f http://raw.githubusercontent.com/
  redhat-developer/
  microservices-book/master/api-gateway/kubernetes/deployment.yml

$ oc create -f http://raw.githubusercontent.com/
  redhat-developer/
  microservices-book/master/api-gateway/kubernetes/service.yml

The deployment files will create four pods (one replica for each microservice). The service files will make each of these replicas visible to each other. You can check the pods that have been created through the command:

$ oc get pods
NAME                                 READY     STATUS
api-gateway-5985d46fd5-4nsfs         1/1       Running
backend-659d8c4cb9-5hv2r             1/1       Running
hello-microprofile-844c6c758-mmx4h   1/1       Running
hello-springboot-5bf5c4c7fd-k5mf4    1/1       Running

What advantages does Kubernetes bring as a cluster manager? Let’s start by exploring the first of many. Let’s kill a pod and see what happens:

$ oc delete pod hello-springboot-5bf5c4c7fd-k5mf4
pod "hello-springboot-5bf5c4c7fd-k5mf4" deleted

Now let’s list our pods again:

$ oc get pods
NAME                                 READY     STATUS
api-gateway-5985d46fd5-4nsfs         1/1       Running
backend-659d8c4cb9-5hv2r             1/1       Running
hello-microprofile-844c6c758-mmx4h   1/1       Running
hello-springboot-5bf5c4c7fd-28mpk    1/1       Running

Wow! There are still four pods! Another pod was created after we deleted the previous one. Kubernetes can start/stop/auto-restart your microservices for you. Can you imagine what a headache it would be to manually determine whether your services are started/stopped at any kind of scale? Let’s continue exploring some of the other valuable cluster management features Kubernetes brings to the table for managing microservices.

External access

Now that all our microservices have been deployed inside the cluster, we need to provide external access. Since we have an API Gateway defined, only this microservice needs to be exposed; it will be the single point of access to invoke the hello-microprofile and hello-springboot microservices. For a refresher on our microservices architetcure, take a look at Figure 6-1 .

Figure 6-1. Calling another service

To enable external access using OpenShift, we need to run the oc expose service command, followed by the name of the service that we want to expose (in this case, api-gateway ):

$ oc expose service api-gateway
route.route.openshift.io/api-gateway exposed

Now you can try the curl command to test all microservices.

$ curl http://api-gateway-tutorial.$(minishift ip).nip.io
  /api/gateway
["Hello from cluster Backend at host: 172.17.0.7",
  "Hello Spring Boot from cluster Backend at host: 172.17.0.7"]

The output should show that you reached both microservices through the API gateway and both of them accessed the backend microservice, which means that everything is working as expected.

 $ oc get deployments
NAME                 DESIRED   CURRENT   UP-TO-DATE   AVAILABLE
api-gateway          1         1         1            1
backend              1         1         1            1
hello-microprofile   1         1         1            1
hello-springboot     1         1         1            1

$ oc scale deployment hello-springboot --replicas=3
deployment.extensions/hello-springboot scaled

$ oc get pods
NAME                                 READY     STATUS
api-gateway-76649cffc-dgr84          1/1       Running
backend-659d8c4cb9-5hv2r             1/1       Running
hello-microprofile-844c6c758-mmx4h   1/1       Running
hello-springboot-5bf5c4c7fd-j77lj    1/1       Running
hello-springboot-5bf5c4c7fd-ltv5p    1/1       Running
hello-springboot-5bf5c4c7fd-w4z7c    1/1       Running

$ oc get services
NAME                 TYPE        CLUSTER-IP       PORT(S)
api-gateway          ClusterIP   172.30.227.148   8080/TCP
backend              ClusterIP   172.30.169.193   8080/TCP
hello-microprofile   ClusterIP   172.30.31.211    8080/TCP
hello-springboot     ClusterIP   172.30.200.142   8080/TCP

apiVersion: v1
kind: Service
metadata:
  name: backend
  labels:
    app: backend
    book: microservices4javadev
spec:
  ports:
  - name: http
    port: 8080
  selector:
    app: backend

Cluster Self-Healing

If a service begins to misbehave, how will we know about it? Ideally, you might think, our cluster management solution could detect and alert us about failures and let human intervention take over. This is the approach we typically take in traditional environments. But when running microservices at scale, where we have lots of services that are supposed to be identical, do we really want to have to stop and troubleshoot every possible thing that can go wrong with a service? Long-running services may experience unhealthy states. An easier approach is to design our microservices such that they can be terminated at any moment, especially when they appear to be behaving incorrectly.

Kubernetes has a couple of health probes we can use out of the box to allow the cluster to administer and self-heal itself. The first is a readiness probe, which allows Kubernetes to determine whether or not a pod should be considered in any service discovery or load-balancing algorithms. For example, some Java apps may take a few seconds to bootstrap the containerized process, even though the pod is technically up and running. If we start sending traffic to a pod in this state, users may experience failures or inconsistent states. With readiness probes, we can let Kubernetes query an HTTP endpoint (for example) and only consider the pod ready if it gets an HTTP 200 or some other response. If Kubernetes determines a pod does not become ready within a specified period of time, the pod will be killed and restarted.

Another health probe we can use is a liveness probe. This is similar to the readiness probe; however, it’s applicable after a pod has been determined to be “ready” and is eligible to receive traffic. Over the course of the life of a pod or service, if the liveness probe (which could also be a simple HTTP endpoint) starts to indicate an unhealthy state (e.g., HTTP 500 errors), Kubernetes can automatically kill the pod and restart it.

In the deployment.yml file shown earlier we declared both of these, with livenessProbe and readinessProbe :

livenessProbe:
  httpGet: # make an HTTP request
      port: 8080 # port to use
      path: /actuator/health # endpoint to hit
      scheme: HTTP # or HTTPS
...
readinessProbe:
  httpGet: # make an HTTP request
      port: 8080 # port to use
      path: /actuator/health # endpoint to hit
      scheme: HTTP # or HTTPS

This means the “readiness” of a hello-springboot pod will be determined by periodically polling the /actuator/health endpoint of the pod (the endpoint was added when we added the actuator to our Spring Boot microservice earlier). If the pod is ready, it returns:

{"status":"UP"}

The same thing can be done with MicroPorfile/Thorntail and Apache Camel.

Circuit Breaker

As a service provider, your responsibility is to your consumers to provide the functionality you’ve promised. Following promise theory, a service provider may depend on other services or downstream systems but cannot and should not impose requirements upon them. A service provider is wholly responsible for its promise to consumers. Because distributed systems can and do fail, however, there will be times when service promises can’t be met or can be only partly met. In our previous examples, we showed our “hello” microservices reaching out to a backend service to form a greeting at the /api/greeting endpoint. What happens if the backend service is not available? How do we hold up our end of the promise?

We need to be able to deal with these kinds of distributed systems faults. A service may not be available; a network may be experiencing intermittent connectivity; the backend service may be experiencing enough load to slow it down and introduce latency; a bug in the backend service may be causing application-level exceptions. If we don’t deal with these situations explicitly; we run the risk of degrading our own service; holding up threads, database locks, and resources, and contributing to rolling, cascading failures that can take an entire distributed network down. The following subsections present two different approaches to help us account for these failures (one for each technology, Spring Boot and MicroProfile).

<dependency>
    <groupId>io.thorntail</groupId>
    <artifactId>microprofile-fault-tolerance</artifactId>
</dependency>

@RestController
@RequestMapping("/api")
@ConfigurationProperties(prefix="greeting")
public class GreeterRestController {

    // Not showing variables

    @GET
    @Produces("text/plain")
    @Path("greeting")
    @CircuitBreaker
    @Timeout
    @Fallback(fallbackMethod = "fallback")
    public String greeting(){
      // greeting implementation
    }

    public String fallback(){
        return saying + " at host "  +
            System.getenv("HOSTNAME") + " - (fallback)";
    }

}

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-netflix-hystrix</artifactId>
  <version>2.0.2.RELEASE</version>
</dependency>

@RestController
@RequestMapping("/api")
@ConfigurationProperties(prefix="greeting")
public class GreeterRestController {

    // Not showing variables and setters

    @RequestMapping(value = "/greeting",
    method = RequestMethod.GET, produces = "text/plain")
    @HystrixCommand(fallbackMethod = "fallback")
    public String greeting(){

        String backendServiceUrl = String.format(
            "http://%s:%d/api/backend?greeting={greeting}",
            backendServiceHost, backendServicePort);

        System.out.println("Sending to: " + backendServiceUrl);

        BackendDTO response = template.getForObject(
        backendServiceUrl, BackendDTO.class, saying);

        return response.getGreeting() + " at host: " +
        response.getIp();
    }

    public String fallback(){
        return saying + " at host "  +
                System.getenv("HOSTNAME") + " - (fallback)";
    }

}

@EnableCircuitBreaker
@SpringBootApplication
public class HelloSpringbootApplication {

	public static void main(String[] args) {
		SpringApplication
                .run(HelloSpringbootApplication.class, args);
	}

}

$ cd <PROJECT_ROOT>/hello-springboot
$ mvn clean package
$ docker build -t rhdevelopers/hello-springboot:1.0 .

$ cd <PROJECT_ROOT>/hello-microprofile
$ mvn clean package
$ docker build -t rhdevelopers/hello-microprofile:1.0 .

$ oc delete pod -l app=hello-springboot
$ oc delete pod -l app=hello-microprofile

$ oc scale deployment backend --replicas=0

$ curl http://api-gateway-tutorial.$(minishift ip).nip.io
  /api/gateway
["Hello at host hello-
  microprofile-57c9f8f9f4-24c2l- (fallback)",
"Hello Spring Boot at host hello-
 springboot-f797878bd-24hxm- (fallback)"]

Kubernetes Load Balancing

The great thing about Kubernetes is that it provides a lot of distributed systems features out of the box; no need to add any extra components (server side) or libraries (client side). Kubernetes Service s provided a means to discover microservices, and they also provide server-side load balancing. If you recall, a Kubernetes Service is an abstraction over a group of pods that can be specified with label selectors. For all the pods that can be selected with the specified selector, Kubernetes will load balance any requests across them. The default Kubernetes load-balancing algorithm is round robin, but it can be configured for other algorithms, such as session affinity. Note that clients don’t have to do anything to add a pod to the Service ; just adding a label to your pod will enable it for selection and make it available. Clients reach the Kubernetes Service by using the cluster IP or cluster DNS service provided out of the box by Kubernetes. Also recall the cluster DNS service is not like traditional DNS and does not fall prey to the DNS caching TTL problems typically encountered with using DNS for discovery/load balancing. Furthermore, there are no hardware load balancers to configure or maintain; it’s all just built in.

To demonstrate load balancing, let’s scale up the backend services in our cluster and scale our hello-springboot service back to one replica to reduce the resource usage:

$ oc scale deployment hello-springboot --replicas=1
deployment.extensions/hello-springboot scaled

$ oc scale deployment backend --replicas=3
deployment.extensions "backend" scaled

Now if we check our pods, we should see three backend pods:

$ oc get pods
NAME                                  READY     STATUS
api-gateway-9786d4977-2jnfm           1/1       Running
backend-859bbd5cc-ck68q               1/1       Running
backend-859bbd5cc-j46gj               1/1       Running
backend-859bbd5cc-mdvcs               1/1       Running
hello-microprofile-57c9f8f9f4-24c2l   1/1       Running
hello-springboot-f797878bd-24hxm      1/1       Running

If we describe the Kubernetes services backend , we should see the the selector used to select the pods that will be eligible for taking requests. The Service will load balance to the pods listed in the Endpoints field:

$ oc describe service backend
Name:              backend
Namespace:         microservices4java
Labels:            app=backend
Annotations:       <none>
Selector:          app=backend
Type:              ClusterIP
IP:                172.30.169.193
Port:              http  8080/TCP
TargetPort:        8080/TCP
Endpoints:         172.17.0.11:8080,172.17.0.13:8080,
                   172.17.0.14:8080
Session Affinity:  None
Events:            <none>

We can see here that the backend service will select all pods with the label app=backend . Let’s take a moment to see what labels are on one of the backend pods:

$ oc describe pod/backend-859bbd5cc-ck68q | grep Labels
Labels:                     app=backend

The backend pods have a label that matches what the service is looking for, so any communication with the service will be load-balanced over these matching pods.

Let’s make a few calls to our api-gateway service. We should see the responses contain different IP addresses for the backend service:

$ curl http://api-gateway-tutorial.$(minishift ip).nip.io
  /api/gateway
 ["Hello from cluster Backend at host: 172.17.0.11",
 "Hello Spring Boot from cluster Backend at host: 172.17.0.14"]

$ curl http://api-gateway-tutorial.$(minishift ip).nip.io
  /api/gateway
 ["Hello from cluster Backend at host: 172.17.0.13",
"Hello Spring Boot from cluster Backend at host: 172.17.0.14"]

We used curl here, but you can use your favorite HTTP/REST tool, including your web browser. Just refresh your browser a few times; you should see that the backend that gets called is different each time, indicating that the Kubernetes Service is load balancing over the respective pods as expected.

When you’re done experimenting, don’t forget to reduce the number of replicas in your cluster to reduce the resource consumption:

$ oc scale deployment backend --replicas=1
deployment.extensions/backend scaled

Modifying the API gateway

The first microservice that we will modify is the api-gateway service. Since it was built using Camel, we will make use of a Camel component called camel-opentracing . This component is used for tracing incoming and outcoming Camel messages.

To use this Camel component, we just need to add the dependency camel-opentracing-starter that enables the integration of Camel, Spring Boot, and OpenTracing to our pom.xml file. We will also need to add two Jaeger libraries-- jaeger-tracerresolver gets the Tracer object and configures it from environment variables, and jaeger-thrift is a set of components that send data to the backend:

<!-- OpenTracing -->
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-opentracing-starter</artifactId>
</dependency>
<dependency>
    <groupId>io.jaegertracing</groupId>
    <artifactId>jaeger-tracerresolver</artifactId>
    <version>0.32.0</version>
</dependency>
<dependency>
    <groupId>io.jaegertracing</groupId>
    <artifactId>jaeger-thrift</artifactId>
    <version>0.32.0</version>
</dependency>

Now we can “turn on” the OpenTracing feature by annotating the main class with @CamelOpenTracing as shown in Example 7-1 .

@SpringBootApplication
@CamelOpenTracing
public class MySpringBootApplication {

    /**
     * A main method to start this application.
     */
    public static void main(String[] args) {
        SpringApplication.run(MySpringBootApplication.class, args);
    }

}

As mentioned previously, the Tracer object will be configured using several environment variables. Because the only one that is required is JAEGER_SERVICE_NAME , we will add this to our Dockerfile with the value API-Gateway :

FROM fabric8/java-alpine-openjdk8-jdk
ENV JAVA_APP_JAR api-gateway-1.0.jar
ENV AB_OFF true
ENV JAEGER_SERVICE_NAME API-Gateway
ADD target/api-gateway-1.0.jar /deployments/

Now we can rebuild the JAR file and the Docker image and restart the Kubernetes pod with the following commands:

$ mvn clean package
$ docker build -t rhdevelopers/api-gateway:1.0 .
$ oc delete pod -l app=api-gateway

Modifying the Spring Boot microservice

For our hello_springboot microservice, we need to add the same jaeger-tracerresolver and jaeger-thrift libraries that we included in the api-gateway service, plus the opentracing-spring-web-starter dependency that will be responsible for providing the integration with Spring Boot and OpenTracing:

<!-- OpenTracing -->
<dependency>
    <groupId>io.opentracing.contrib</groupId>
    <artifactId>opentracing-spring-web-starter</artifactId>
    <version>1.0.1</version>
</dependency>
<dependency>
    <groupId>io.jaegertracing</groupId>
    <artifactId>jaeger-tracerresolver</artifactId>
    <version>0.32.0</version>
</dependency>
<dependency>
    <groupId>io.jaegertracing</groupId>
    <artifactId>jaeger-thrift</artifactId>
    <version>0.32.0</version>
</dependency>

To enable the tracing headers to be forwarded from this microservice to the backend, the RestTemplate needs an interceptor called TracingRestTemplateInterceptor .

Let’s modify the GreeterRestController class to add this interceptor, as shown in Example 7-2 .

@RestController
@RequestMapping("/api")
@ConfigurationProperties(prefix="greeting")
public class GreeterRestController {

    private RestTemplate template = new RestTemplate();

    private String saying, backendServiceHost;

    private int backendServicePort;

    @RequestMapping(value = "/greeting",
            method = RequestMethod.GET, produces = "text/plain")
    @HystrixCommand(fallbackMethod = "fallback")
    public String greeting(){
        template.setInterceptors(
                Collections.singletonList(
                        new TracingRestTemplateInterceptor(
                                TracerResolver.resolveTracer())));

        String backendServiceUrl = String.format(
                "http://%s:%d/api/backend?greeting={greeting}",
                backendServiceHost, backendServicePort);

        System.out.println("Sending to: " + backendServiceUrl);


        BackendDTO response = template.getForObject(
                backendServiceUrl, BackendDTO.class, saying);

        return response.getGreeting() + " at host: " +
                response.getIp();
    }

    //fallback method and setters
}

Now let’s add the declaration of the JAEGER_SERVICE_NAME environment variable in the Dockerfile:

FROM fabric8/java-alpine-openjdk8-jdk
ENV JAVA_APP_JAR hello-springboot-1.0.jar
ENV AB_OFF true
ENV JAEGER_SERVICE_NAME hello-springboot
ADD target/hello-springboot-1.0.jar /deployments/

Then we can rebuild the JAR file and the Docker image and restart the Kubernetes pod with the following commands:

$ mvn clean package -DskipTests
$ docker build -t rhdevelopers/hello-springboot:1.0 .
$ oc delete pod -l app=hello-springboot

Modifying the MicroProfile microservice

For our hello_microprofile , we will follow the same recipe:

1. Add a Maven dependency.

2. Modify the source code.

3. Add the JAEGER_SERVICE_NAME environment variable to the Dockerfile.

Let’s start by adding the Maven dependencies related to OpenTracing and Jaeger, respectively. MicroProfile has support for OpenTracing and Thorntail has integration with Jaeger, so we will need both dependencies:

<!-- OpenTracing -->
<dependency>
    <groupId>io.thorntail</groupId>
    <artifactId>microprofile-opentracing</artifactId>
</dependency>
<dependency>
    <groupId>io.thorntail</groupId>
    <artifactId>jaeger</artifactId>
</dependency>

MicroProfile has an API for accessing an OpenTracing-compliant Tracer object within a JAX-RS application. We just need to add the @Traced annotation to the methods that will be “traced.” We also need to use the class ClientTracingRegistrar to configure tracing features into the JAX-RS client. Let’s perform these modifications to the greeting() method in the GreeterRestController class in Example 7-3 .

@Path("/api")
public class GreeterRestController {

    @Inject
    @ConfigProperty(name="greeting.saying",
        defaultValue = "Hello")
    private String saying;

    @Inject
    @ConfigProperty(name = "greeting.backendServiceHost",
        defaultValue = "localhost")
    private String backendServiceHost;

    @Inject
    @ConfigProperty(name = "greeting.backendServicePort",
        defaultValue = "8080")
    private int backendServicePort;

    @GET
    @Produces("text/plain")
    @Path("greeting")
    @CircuitBreaker
    @Timeout
    @Fallback(fallbackMethod = "fallback")
    @Traced(operationName = "greeting")
    public String greeting() {
        String backendServiceUrl = String.format("http://%s:%d",
                backendServiceHost,backendServicePort);

        System.out.println("Sending to: " + backendServiceUrl);

        Client client = ClientTracingRegistrar
                .configure(ClientBuilder.newBuilder()).build();

        BackendDTO backendDTO = client.target(backendServiceUrl)
                .path("api")
                .path("backend")
                .queryParam("greeting", saying)
                .request(MediaType.APPLICATION_JSON_TYPE)
                .get(BackendDTO.class);

        return backendDTO.getGreeting()
                + " at host: " + backendDTO.getIp();
    }

    public String fallback(){
        return saying + " at host "  +
        System.getenv("HOSTNAME") + " - (fallback)";
    }

}

That’s it! Just one annotation and we are good to go. But let’s not forget about the JAEGER_SERVICE_NAME in the Dockerfile:

FROM fabric8/java-alpine-openjdk8-jdk
ENV JAVA_APP_JAR demo-thorntail.jar
ENV AB_OFF true
ENV JAEGER_SERVICE_NAME hello-microprofile
ADD target/demo-thorntail.jar /deployments/

We can then rebuild the JAR file and the Docker image and restart the Kubernetes pod with the following commands:

$ mvn clean package -DskipTests
$ docker build -t rhdevelopers/hello-microprofile:1.0 .
$ oc delete pod -l app=hello-microprofile

Modifying the Servlet backend

Finally, we will add tracing capabilities to our backend application. To make this happen, we will add the dependency jaeger-client to our pom.xml file:

<!-- OpenTracing -->
<dependency>
    <groupId>io.jaegertracing</groupId>
    <artifactId>jaeger-client</artifactId>
    <version>0.32.0</version>
</dependency>

With this library, the backend application using OpenTracing’s TracerResolver can continue using the Jaeger Java client without any hardcoded dependency; we can configure it via environment variables just like we did for the previous microservice.

On the source code side, it will require a little bit more work as we need to extract the parent Span coming from the microservice’s request headers and create a new child Span . This can be done using the following code snippet:

//Extract the parent Span from the headers
SpanContext parentSpan = tracer
        .extract(Format.Builtin.HTTP_HEADERS,
                new TextMapExtractAdapter(headers));

//Start a new Span as a child of the Parent Span
Scope scope = tracer
        .buildSpan("backend-servlet")
        .asChildOf(parentSpan)
        .startActive(true);

//Perform work

 scope.span().finish();

Example 7-4 shows the necessary modifications in the BackendHttpServlet class.

@WebServlet(urlPatterns = {"/api/backend"})
public class BackendHttpServlet extends HttpServlet {

    private Tracer tracer = TracerResolver.resolveTracer();

    @Override
    protected void doGet(HttpServletRequest req,
        HttpServletResponse resp)
            throws ServletException, IOException {

        //Place the HTTP headers in a HashMap
        final HashMap<String, String> headers = new HashMap<>();
        Enumeration<String> headerNames = req.getHeaderNames();
        while (headerNames.hasMoreElements()){
            String name = headerNames.nextElement();
            String value = req.getHeader(name);
            headers.put(name, value);
        }
        //Extract the parent Span from the headers
        SpanContext parentSpan = tracer
                .extract(Format.Builtin.HTTP_HEADERS,
                        new TextMapExtractAdapter(headers));

        //Start a new Span as a child of the parent Span
        Scope scope = tracer
                .buildSpan("backend-servlet")
                .asChildOf(parentSpan)
                .startActive(true);

        resp.setContentType("application/json");

        ObjectMapper mapper = new ObjectMapper();
        String greeting = req.getParameter("greeting");

        ResponseDTO response = new ResponseDTO();
        response.setGreeting(greeting + " from cluster Backend");
        response.setTime(System.currentTimeMillis());
        response.setIp(getIp());

        PrintWriter out = resp.getWriter();
        mapper.writerWithDefaultPrettyPrinter()
                .writeValue(out, response);

        scope.span().finish();
    }

    private String getIp() {
        String hostname = null;
        try {
            hostname = InetAddress.getLocalHost()
                                    .getHostAddress();
        } catch (UnknownHostException e) {
            hostname = "unknown";
        }
        return hostname;
    }
}

We must also to add the declaration of the JAEGER_SERVICE_NAME environment variable in the Dockerfile:

FROM jboss/wildfly:10.0.0.Final
ENV JAEGER_SERVICE_NAME backend
ADD target/ROOT.war /opt/jboss/wildfly/standalone/deployments/

Now we can rebuild the JAR file and the Docker image and restart the Kubernetes pod with the following commands:

$ mvn clean package -DskipTests
$ docker build -t rhdevelopers/backend:1.0 .
$ oc delete pod -l app=backend