<

I just announced the new Spring 5 modules in REST With Spring:

>> CHECK OUT THE COURSE

1. Overview

In this previous article, we covered a theoretical introduction about Kubernetes.

In this tutorial, we’ll discuss how to deploy a Spring Boot application on a local Kubernetes environment, also known as Minikube.

As part of this article, we’ll:

  • Install Minikube on our local machine
  • Develop an example application consisting of two Spring Boot services
  • Set up the application on a one-node cluster using Minikube
  • Deploy the application using config files

2. Installing Minikube

The installation of Minikube basically consists of three steps: installing a Hypervisor (like VirtualBox), the CLI kubectl, as well as Minikube itself.

The official documentation provides detailed instructions for each of the steps, and for all popular operating systems.

After completing the installation, we can start Minikube, set VirtualBox as Hypervisor, and configure kubectl to talk to the cluster called minikube:

$> minikube start
$> minikube config set vm-driver virtualbox
$> kubectl config use-context minikube

After that, we can verify that kubectl communicates correctly with our cluster:

$> kubectl cluster-info

The output should look like this:

Kubernetes master is running at https://192.168.99.100:8443
To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

At this stage, we’ll keep the IP in the response close (192.168.99.100 in our case). We’ll later refer to that as NodeIP, which is needed to call resources from outside of the cluster, e. g. from our browser.

Finally, we can inspect the state of our cluster:

$> minikube dashboard

This command opens a site in our default browser, which provides an extensive overview about the state of our cluster.

4. Demo Application

As our cluster is now running and ready for deployment, we need a demo application.

For this purpose, we’ll create a simple “Hello world” application, consisting of two Spring Boot services, which we’ll call frontend and backend.

The backend provides one REST endpoint on port 8080, returning a String containing its hostname. The frontend is available on port 8081, it will simply call the backend endpoint and return its response.

After that, we have to build a Docker image from each app. All files necessary for that are also available on GitHub.

For detailed instructions how to build Docker images, have a look at Dockerizing a Spring Boot Application.

We have to make sure here that we trigger the build process on the Docker host of the Minikube cluster, otherwise, Minikube won’t find the images later during deployment. Furthermore, the workspace on our host must be mounted into the Minikube VM:

$> minikube ssh
$> cd /c/workspace/tutorials/spring-cloud/spring-cloud-kubernetes/demo-backend
$> docker build --file=Dockerfile \
  --tag=demo-backend:latest --rm=true .

After that, we can logout from the Minikube VM, all further steps will be executed on our host using kubectl and minikube command-line tools.

5. Simple Deployment Using Imperative Commands

In a first step, we’ll create a Deployment for our demo-backend app, consisting of only one Pod. Based on that, we’ll discuss some commands so we can verify the Deployment, inspect logs, and clean it up at the end.

5.1. Creating the Deployment

We’ll use kubectl, passing all required commands as arguments:

$> kubectl run demo-backend --image=demo-backend:latest \
  --port=8080 --image-pull-policy Never

As we can see, we create a Deployment called demo-backend, which is instantiated from an image also called demo-backend, with version latest.

With –port, we specify, that the Deployment opens port 8080 for its Pods (as our demo-backend app listens to port 8080).

The flag –image-pull-policy Never ensures, that Minikube doesn’t try to pull the image from a registry, but takes it from the local Docker host instead.

5.2. Verifying the Deployment

Now, we can check whether the deployment was successful:

$> kubectl get deployments

The output looks like this:

NAME           DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
demo-backend   1         1         1            1           19s

If we want to have a look at the application logs, we need the Pod ID first:

$> kubectl get pods
$> kubectl logs <pod id>

5.3. Creating a Service for the Deployment

To make the REST endpoint of our backend app available, we need to create a Service:

$> kubectl expose deployment demo-backend --type=NodePort

–type=NodePort makes the Service available from outside of the cluster. It will be available at <NodeIP>:<NodePort>, i. e. the service maps any request incoming at <NodePort> to port 8080 of its assigned Pods.

We use the expose command, so NodePort will be set by the cluster automatically (this is a technical limitation), the default range is 30000-32767. To get a port of our choice, we can use a configuration file, as we’ll see in the next section.

We can verify that the service was created successfully:

$> kubectl get services

The output looks like this:

NAME           TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
demo-backend   NodePort    10.106.11.133   <none>        8080:30117/TCP   11m

As we can see, we have one Service called demo-backend, of type NodePort, which is available at the cluster-internal IP 10.106.11.133.

We have to take a closer look at column PORT(S): as port 8080 was defined in the Deployment, the Service forwards traffic to this port. However, if we want to call the demo-backend from our browser, we have to use port 30117, which is reachable from outside of the cluster.

5.4. Calling the Service

Now, we can call our backend service for the first time:

$> minikube service demo-backend

This command will start our default browser, opening <NodeIP>:<NodePort>. In our example, that would be http://192.168.99.100:30117.

5.5. Cleaning up Service and Deployment

Afterward, we can remove Service and Deployment:

$> kubectl delete service demo-backend
$> kubectl delete deployment demo-backend

6. Complex Deployment Using Configuration Files

For more complex setups, configuration files are a better choice, instead of passing all parameters via command line arguments.

Configurations files are a great way of documenting our deployment, and they can be versioned controlled.

6.1. Service Definition for our Backend App

Let’s redefine our service for the backend using a config file:

kind: Service
apiVersion: v1
metadata:
  name: demo-backend
spec:
  selector:
    app: demo-backend
  ports:
  - protocol: TCP
    port: 8080
  type: ClusterIP

We create a Service named demo-backend, indicated by the metadata: name field.

It targets TCP port 8080 on any Pod with the app=demo-backend label.

Finally, type: ClusterIP indicates that it is only available from inside of the cluster (as we want to call the endpoint from our demo-frontend app this time, but not directly from a browser anymore, as in the previous example).

6.2. Deployment Definition for Backend App

Next, we can define the actual Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-backend
spec:
  selector:
      matchLabels:
        app: demo-backend
  replicas: 3
  template:
    metadata:
      labels:
        app: demo-backend
    spec:
      containers:
        - name: demo-backend
          image: demo-backend:latest
          imagePullPolicy: Never
          ports:
            - containerPort: 8080

We create a Deployment named demo-backend, indicated by the metadata: name field.

The spec: selector field defines how the Deployment finds which Pods to manage. In this case, we merely select on one label defined in the Pod template (app: demo-backend).

We want to have three replicated Pods, which we indicate by the replicas field.

The template field defines the actual Pod:

  • The Pods are labeled as app: demo-backend
  • The template: spec field indicates that each Pod replication runs one container, demo-backend, with version latest
  • The Pods open port 8080

6.3. Deployment of the Backend App

We can now trigger the deployment:

$> kubectl create -f backend-deployment.yaml

Let’s verify that the deployment was successful:

$> kubectl get deployments

The output looks like this:

NAME           DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
demo-backend   3         3         3            3           25s

We can also check whether the Service is available:

$> kubectl get services

The output looks like this:

NAME            TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
demo-backend    ClusterIP   10.102.17.114   <none>        8080/TCP         30s

As we can see, the Service is of type ClusterIP, and it doesn’t provide an external port in the range 30000-32767, different from our previous example in section 5.

6.4. Deployment and Service Definition for our Frontend App

After that, we can define Service and Deployment for the frontend:

kind: Service
apiVersion: v1
metadata:
  name: demo-frontend
spec:
  selector:
    app: demo-frontend
  ports:
  - protocol: TCP
    port: 8081
    nodePort: 30001
  type: NodePort
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-frontend
spec:
  selector:
      matchLabels:
        app: demo-frontend
  replicas: 3
  template:
    metadata:
      labels:
        app: demo-frontend
    spec:
      containers:
        - name: demo-frontend
          image: demo-frontend:latest
          imagePullPolicy: Never
          ports:
            - containerPort: 8081

Both frontend and backend are almost identical, the only difference between backend and frontend is the spec of the Service:

For the frontend, we define the type as NodePort (as we want to make the frontend available to outside of the cluster). The backend only has to be reachable from within the cluster, therefore, the type was ClusterIP.

As said before, we also specify NodePort manually, using the nodePort field.

6.5. Deployment of the Frontend App

We can now trigger this deployment the same way:

$> kubectl create -f frontend-deployment.yaml

Let’s quickly verify that the deployment was successful and the Service is available:

$> kubectl get deployments
$> kubectl get services

After that, we can finally call the REST endpoint of the frontend application:

$> minikube service demo-frontend

This command will again start our default browser, opening <NodeIP>:<NodePort>, which is http://192.168.99.100:30001 for this example.

6.6. Cleaning up Services and Deployments

In the end, we can clean up by removing Services and Deployments:

$> kubectl delete service demo-frontend
$> kubectl delete deployment demo-frontend
$> kubectl delete service demo-backend
$> kubectl delete deployment demo-backend

7. Conclusion

In this article, we had a quick look at how to deploy a Spring Boot “Hello world” app on a local Kubernetes cluster using Minikube.

We discussed in detail, how to:

  • Install Minikube on our local machine
  • Develop and build an example consisting of two Spring Boot apps
  • Deploy the services on a one-node cluster, using imperative commands with kubectl as well as configuration files

As always, the full source code of the examples is available over on GitHub.

I just announced the new Spring 5 modules in REST With Spring:

>> CHECK OUT THE LESSONS

  Subscribe  
newest oldest most voted
Notify of
Scott
Guest
Scott

trouble with the minikube start on high sierra. I’ve tried twice now, removing the .minikub dir in between. It creates the virtual, and it is running in virtualbox, and showing VBoxHeadless taking up around 13% cpu in OS X. I can minikube ssh and run top but it is taking up <0.1% on the few top processses. here's the output where its stuck: minikube start Starting local Kubernetes v1.10.0 cluster… Starting VM… Downloading Minikube ISO 150.53 MB / 150.53 MB [============================================] 100.00% 0s Getting VM IP address… Moving files into cluster… Downloading kubeadm v1.10.0 Downloading kubelet v1.10.0 Finished Downloading kubelet… Read more »

Scott
Guest
Scott

turns out minikube 0.26 is the problem, works if you install 0.25.2.

Loredana Crusoveanu
Editor

That’s odd. Thanks for posting the solution.

Devi Das
Guest
Devi Das

Hi I have tried deploying my sample spring boot REST application on kubernetes. It’s deployed successfully as I can see from the pod logs however while opening in browser it’s giving me WHITE LABEL(404) error. However I tested it running in docker its works without any issue. Please can you help me out on this as I am struggling in this .

Loredana Crusoveanu
Editor

Hey Devi,

It’s difficult to say. I suggest checking the configuration and running the get services command to see what IP and ports your application is running on, and if you’re accessing the correct ones from your browser. Note that the external port is different than the internal cluster port.