TL;DR: In this chapter, you'll learn how to create a local Kubernetes cluster and deploy an application.
If you use Docker containers and wish to deploy your app into production, you might have a few options.
You could:
- Run the container in the server manually with a docker run.
- Use a tool such as docker-compose to run and manage several containers at the same time.
- Or you could use a container orchestrator — a tool designed to manage and run containers at scale.
In this chapter, you will learn how to use Kubernetes (the most popular container orchestrator) to deploy your Spring Boot apps as Docker containers.
To demonstrate, we're going to deploy an app called Knote on a Kubernetes cluster.
The application comes already prepackaged as a Docker container. If you wish to learn how to build your own, you might want to check out this other article that goes into [how to design a Spring Boot application that can be containeraised]. (https://learnk8s.io/spring-boot-kubernetes-guide)
Here's how you're going to proceed.
- Deploying containerised applications
- Container orchestrators
- Creating a local Kubernetes cluster
- Kubernetes resources
- The application
- Defining a Deployment
- Defining a Service
- Defining the database tier
- Deploying the application
- Recap and next steps
There're several services where you can deploy Docker containers, for example, AWS Elastic Beanstalk or Azure App Service.
Those services are excellent if you wish to deploy a single or a small number of containers.
However, when you're building production-grade applications, it's common to have a large number of components that are all connected.
This is especially true if you follow the microservices pattern.
Each component, or "microservice", should be scalable independently.
Solutions such as AWS Elastic Beanstalk and Azure App Service aren't designed to run those kinds of workloads.
So how do you run complex containerised applications?
With a container orchestrator.
Container orchestrators are designed to run complex applications with large numbers of scalable components.
They work by inspecting the underlying infrastructure and determining the best server to run each container.
They can scale to thousands of computers and tens of thousands of containers and still work efficiently and reliably.
You can imagine a container orchestrator as a highly-skilled Tetris player.
Containers are the blocks, servers are the boards, and the container orchestrator is the player.
{
"description": "Kubernetes is the best tetris player",
"animation": "assets/tetris.svg",
"fallback": "assets/tetris-fallback.svg"
}
Some existing container orchestrators include Apache Mesos, Hashicorp Nomad, and Kubernetes.
So which one should you choose?
It's not a fair fight.
Kubernetes is the de-facto standard when it comes to orchestrating containers at a large scale.
Have a look at this Google Trends chart:
{
"description": "Popular orchestrators",
"animation": "assets/chart.svg",
"fallback": "assets/chart-fallback.svg"
}
Popularity is not the only factor, though.
Kubernetes is:
- Open-source: you can download and use it without paying any fee. You're also encouraged to contribute to the official project with bug fixes and new features
- Battle-tested: there're plenty of examples of companies running it in production. There's even a website where you can learn from the mistake of others.
- Well-looked-after: Redhat, Google, Microsoft, IBM, Cisco are only a few of the companies that have heavily invested in the future of Kubernetes by creating managed services, contributing to upstream development and offering training and consulting.
Kubernetes is an excellent choice to deploy your containerised application.
But how do you do that?
It all starts by creating a Kubernetes cluster.
There are several ways to create a Kubernetes cluster:
- Using a managed Kubernetes service like Google Kubernetes Service (GKE), Azure Kubernetes Service (AKS), or Amazon Elastic Kubernetes Service (EKS)
- Installing Kubernetes yourself on cloud or on-premises infrastructure with a Kubernetes installation tool like kubeadm or kops
- Creating a Kubernetes cluster on your local machine with a tool like Minikube, MicroK8s, or k3s
In this section, you are going to use Minikube.
Minikube creates a single-node Kubernetes cluster running in a virtual machine.
A Minikube cluster is only intended for testing purposes, not for production. Later in this course, you will create an Amazon EKS cluster, which is suited for production.
Before you install Minikube, you have to install kubectl.
kubectl is the primary Kubernetes CLI — you use it for all interactions with a Kubernetes cluster, no matter how the cluster was created.
Once kubectl is installed, go on and install Minikube according to the official documentation.
If you're on Windows, you can follow our handy guide on how to install Minikube on Windows and if you have issues, you might find this instructions relevant.
With Minikube installed, you can create a cluster as follows:
minikube start --vm
The command creates a virtual machine and installs Kubernetes.
Starting the virtual machine and cluster may take a couple of minutes, so please be patient!
When the command completes, you can verify that the cluster is created with:
kubectl cluster-info
You have a fully-functioning Kubernetes cluster on your machine now.
Time to learn about some fundamental Kubernetes concepts.
Kubernetes has a declarative interface.
In other words, you describe how you want the deployment of your application to look like, and Kubernetes figures out the necessary steps to reach this state.
The "language" that you use to communicate with Kubernetes consists of so-called Kubernetes resources.
There are many different Kubernetes resources — each is responsible for a specific aspect of your application.
You can find the full list of Kubernetes resources in the Kubernetes API reference.
Kubernetes resources are defined in YAML files and submitted to the cluster through the Kubernetes HTTP API.
Kubernetes resource definitions are also sometimes called "resource manifests" or "resource configurations".
As soon as Kubernetes receives your resource definitions, it takes the necessary steps to reach the target state.
Similarly, to query the state of your applications, you retrieve Kubernetes resources through the Kubernetes HTTP API.
In practice, you do all these interactions with kubectl - your primary client for the Kubernetes API.
It's time to experience Kubernetes first-hand.
The resources that you will use are the Deployment and the Service.
Let's have a look at the app.
The application that you will deploy on Kubernetes is the following:
The application is made of two parts:
- A Spring Boot application.
- A MongoDB to persist the data.
The application is already packaged as a container and it's available from Docker Hub as learnk8s/knote-java:1.0.0.
If you want to learn how to develop and package applications in container, you should check out the previous chapter in this series.
Here's a quick refresher on what happened in the previous chapter.
- You created an application using Spring Boot.
- You packaged the app as a container using Docker.
- You uploaded the container to Docker Hub — a container registry.
- You run the app and the databases locally using Docker.
In the remainder of this chapter, you will define a set of Kubernetes resources that describe your application, and in the end, you will submit them to your Kubernets cluster.
All the code is available in this repository.
First of all, create a folder named kube in your application directory:
mkdir kube
The purpose of this folder is to hold all the Kubernetes YAML files that you will create.
It's a best practice to group all resource definitions for an application in the same folder because this allows to submit them to the cluster with a single command.
The first Kubernetes resource is a Deployment.
A Deployment creates and runs containers and keeps them alive.
Here is the definition of a Deployment for your Knote app:
apiVersion: apps/v1
kind: Deployment
metadata:
name: knote
spec:
replicas: 1
selector:
matchLabels:
app: knote
template:
metadata:
labels:
app: knote
spec:
containers:
- name: app
image: learnk8s/knote-java:1.0.0
ports:
- containerPort: 3000
env:
- name: MONGO_URL
value: mongodb://mongo:27017/dev
imagePullPolicy: AlwaysThat looks complicated, but we will break it down and explain it in detail.
For now, save the above content in a file named knote.yaml in the kube folder.
You must be wondering how you can you find out about the structure of a Kubernetes resource.
The answer is, in the Kubernetes API reference.
The Kubernetes API reference contains the specification for every Kubernetes resource, including all the available fields, their data types, default values, required fields, and so on.
Here is the specification of the Deployment resource.
If you prefer to work in the command-line, there's an even better way.
The kubectl explain command can print the specification of every Kubernetes resource directly in your terminal:
kubectl explain deployment
The command outputs exactly the same information as the web-based API reference.
To drill down to a specific field use:
kubectl explain deployment.spec.replicas
Now that you know how to look up the documentation of Kubernetes resources, let's turn back to the Deployment.
The first four lines define the type of resource (Deployment), the version of this resource type (apps/v1), and the name of this specific resource (knote):
apiVersion: apps/v1
kind: Deployment
metadata:
name: knote
spec:
replicas: 1
selector:
matchLabels:
app: knote
template:
metadata:
labels:
app: knote
spec:
containers:
- name: knote
image: learnk8s/knote-java:1.0.0
ports:
- containerPort: 3000
env:
- name: MONGO_URL
value: mongodb://mongo:27017/dev
imagePullPolicy: AlwaysNext, you have the desired number of replicas of your container:
apiVersion: apps/v1
kind: Deployment
metadata:
name: knote
spec:
replicas: 1
selector:
matchLabels:
app: knote
template:
metadata:
labels:
app: knote
spec:
containers:
- name: knote
image: learnk8s/knote-java:1.0.0
ports:
- containerPort: 3000
env:
- name: MONGO_URL
value: mongodb://mongo:27017/dev
imagePullPolicy: AlwaysYou don't usually talk about containers in Kubernetes.
Instead, you talk about Pods.
What is a Pod?
A Pod is a wrapper around one or more containers.
Most often, a Pod contains only a single container — however, for advanced use cases, a Pod may contain multiple containers.
If a Pod contains multiple containers, they are treated by Kubernetes as a unit — for example, they are started and stopped together and executed on the same node.
A Pod is the smallest unit of deployment in Kubernetes — you never work with containers directly, but with Pods that wrap containers.
Technically, a Pod is a Kubernetes resource, like a Deployment or Service.
Let's turn back to the Deployment resource.
The next part ties together the Deployment resource with the Pod replicas:
apiVersion: apps/v1
kind: Deployment
metadata:
name: knote
spec:
replicas: 1
selector:
matchLabels:
app: knote
template:
metadata:
labels:
app: knote
spec:
containers:
- name: knote
image: learnk8s/knote-java:1.0.0
ports:
- containerPort: 3000
env:
- name: MONGO_URL
value: mongodb://mongo:27017/dev
imagePullPolicy: AlwaysThe template.metadata.labels field defines a label for the Pods that wrap your Knote container (app: knote).
The selector.matchLabels field selects those Pods with a app: knote label to belong to this Deployment resource.
Note that there must be at least one shared label between these two fields.
The next part in the Deployment defines the actual container that you want to run:
apiVersion: apps/v1
kind: Deployment
metadata:
name: knote
spec:
replicas: 1
selector:
matchLabels:
app: knote
template:
metadata:
labels:
app: knote
spec:
containers:
- name: knote
image: learnk8s/knote-java:1.0.0
ports:
- containerPort: 3000
env:
- name: MONGO_URL
value: mongodb://mongo:27017/dev
imagePullPolicy: AlwaysIt defines the following things:
- A name for the container (
knote) - The name of the Docker image (
learnk8s/knote-java:1.0.0) - The port that the container listens on (3000)
- An environment variable (
MONGO_URL) that will be made available to the process in the container
The above arguments should look familiar to you: you used similar ones when you ran your app with docker run in the previous section.
That's not a coincidence.
When you submit a Deployment resource to the cluster, you can imagine Kubernetes executing docker run and launching your container in one of the computers.
The container specification also defines an imagePullPolicy of Always — the instruction forces the Docker image to be downloaded, even if it was already downloaded.
A Deployment defines how to run an app in the cluster, but it doesn't make it available to other apps.
To expose your app, you need a Service.
A Service resource makes Pods accessible to other Pods or users outside the cluster.
Without a Service, a Pod cannot be accessed at all.
A Service forwards requests to a set of Pods:
In this regard, a Service is akin to a load balancer.
Here is the definition of a Service that makes your Knote Pod accessible from outside the cluster:
apiVersion: v1
kind: Service
metadata:
name: knote
spec:
selector:
app: knote
ports:
- port: 80
targetPort: 3000
type: LoadBalancerAgain, to find out about the available fields of a Service, look it up in the API reference, or, even better, use
kubectl explain service.
Where should you save the above definition?
It is a best-practice to save resource definitions that belong to the same application in the same YAML file.
To do so, paste the above content at the beginning of your existing knote.yaml file, and separate the Service and Deployment resources with three dashes like this:
# ... Deployment YAML definition
---
# ... Service YAML definitionYou can find the final YAML files for this section in this repository.
Let's break down the Service resource.
It consists of three crucial parts.
The first part is the selector:
apiVersion: v1
kind: Service
metadata:
name: knote
spec:
selector:
app: knote
ports:
- port: 80
targetPort: 3000
type: LoadBalancerIt selects the Pods to expose according to their labels.
In this case, all Pods that have a label of app: knote will be exposed by the Service.
Note how this label corresponds exactly to what you specified for the Pods in the Deployment resource:
apiVersion: apps/v1
kind: Deployment
metadata:
name: knote
spec:
# ...
template:
metadata:
labels:
app: knote
# ...It is this label that ties your Service to your Deployment resource.
The next important part is the port:
apiVersion: v1
kind: Service
metadata:
name: knote
spec:
selector:
app: knote
ports:
- port: 80
targetPort: 3000
type: LoadBalancerIn this case, the Service listens for requests on port 80 and forwards them to port 3000 of the target Pods:
The last important part is the type of the Service:
apiVersion: v1
kind: Service
metadata:
name: knote
spec:
selector:
app: knote
ports:
- port: 80
targetPort: 3000
type: LoadBalancerIn this case, the type is LoadBalancer, which makes the exposed Pods accessible from outside the cluster.
The default Service type is ClusterIP, which makes the exposed Pods only accessible from within the cluster.
Pro tip: find out about all available Service types with
kubectl explain service.spec.type.
Beyond exposing your containers, a Service also ensures continuous availability for your app.
If one of the Pod crashes and is restarted, the Service makes sure not to route traffic to this container until it is ready again.
Also, when the Pod is restarted, and a new IP address is assigned, the Service automatically handles the update too.
{
"description": "A load balancer can remove the need of keeping track of IP addresses",
"animation": "assets/service-come-and-go.svg",
"fallback": "assets/service-come-and-go-fallback.svg"
}
Furthermore, if you decide to scale your Deployment to 2, 3, 4, or 100 replicas, the Service keeps track of all of these Pods.
This completes the description of your app — a Deployment and Service is all you need.
You need to do the same thing for the database component now.
In principle, a MongoDB Pod can be deployed similarly as your app — that is, by defining a Deployment and Service resource.
However, deploying MongoDB needs some additional configuration.
MongoDB requires a persistent storage.
This storage must not be affected by whatever happens to the MongoDB Pod.
If the MongoDB Pod is deleted, the storage must persist — if the MongoDB Pod is moved to another node, the storage must persist.
There exists a Kubernetes resource that allows obtaining persistent storage volume: the PersistentVolumeClaim.
Consequently, the description of your database component should consist of three resource definitions:
- PersistentVolumeClaim
- Service
- Deployment
Here's the complete configuration:
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: mongo-pvc
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 256Mi
---
apiVersion: v1
kind: Service
metadata:
name: mongo
spec:
selector:
app: mongo
ports:
- port: 27017
targetPort: 27017
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: mongo
spec:
selector:
matchLabels:
app: mongo
template:
metadata:
labels:
app: mongo
spec:
containers:
- name: mongo
image: mongo:3.6.17-xenial
ports:
- containerPort: 27017
volumeMounts:
- name: storage
mountPath: /data/db
volumes:
- name: storage
persistentVolumeClaim:
claimName: mongo-pvcPlease save this YAML definition in a file named mongo.yaml in the kube directory.
Let's look at each of the three parts of the definition.
PersistentVolumeClaim
The PersistentVolumeClaim requests a persistent storage volume of 256 MB.
This volume is made available to the MongoDB container to save its data.
Service
The Service is similar to the Service you defined for the app component.
However, note that it does not have a type field.
If a Service does not have a type field, Kubernetes assigns it the default type ClusterIP.
ClusterIP makes the Pod accessible from within the cluster, but not from outside — this is fine because the only entity that has to access the MongoDB Pod is your app.
Deployment
The Deployment has a similar structure to the other Deployment.
However, it contains an additional field that you haven't seen yet: volumes.
The volumes field defines a storage volume named storage, which references the PersistentVolumeClaim.
Furthermore, the volume is referenced from the volumeMounts field in the definition of the MongoDB container.
The volumeMount field mounts the referenced volume at the specified path in the container, which in this case is /data/db.
And /data/db is where MongoDB saves its data.
In other words, the MongoDB database data is stored in a persistent storage volume that has a lifecycle independent of the MongoDB container.
Deploying stateful applications to Kubernetes is a complex but essential topic. You can learn more about it in Managing State module of the Learnk8s Academy.
There's one more important thing to note.
Do you remember the value of the MONGO_URL environment variable in the Knote Deployment?
It is mongodb://mongo:27017/dev.
The hostname is mongo.
Why is it mongo?
Because the name of the MongoDB Service is mongo.
If you named your MongoDB service foo, then you would need to change the value of the MONGO_URL variable to monogdb://foo:27017.
Service discovery is a critical Kubernetes concept.
Pods within a cluster can talk to each other through the names of the Services exposing them.
Kubernetes has an internal DNS system that keeps track of domain names and IP addresses.
Similarly to how Docker provides DNS resolution for containers, Kubernetes provides DNS resolution for Services.
All components of your app are described by Kubernetes resources now — let's deploy them to the cluster.
So far, you created a few YAML files with resource definitions.
You didn't yet touch the cluster.
But now comes the big moment!
You are going to submit your resource definitions to Kubernetes.
And Kubernetes will bring your application to life.
First of all, make sure that you have a knote.yaml and mongo.yaml file inside the kube directory:
tree .
kube/
├── knote.yaml
└── mongo.yaml
You can find these files also in this repository.
Also, make sure that your Minikube cluster is running:
minikube status
Then submit your resource definitions to Kubernetes with the following command:
kubectl apply -f kube
This command submits all the YAML files in the kube directory to Kubernetes.
The
-fflag accepts either a single filename or a directory. In the latter case, all YAML files in the directory are submitted.
As soon as Kubernetes receives your resources, it creates the Pods.
You can watch your Pods coming alive with:
kubectl get pods --watch
You should see two Pods transitioning from Pending to ContainerCreating to Running.
These Pods correspond to the Knote and MongoDB containers.
As soon as both Pods are in the Running state, your application is ready.
You can now access your application through the knote Service.
In Minikube, a Service can be accessed with the following command:
minikube service knote --url
The command should print the URL of the knote Service.
You can open the URL in a web browser.
You should see your application.
Verify that your app works as expected by creating some notes with pictures.
The app should work as it did when you ran it locally with Docker.
But now it's running on Kubernetes.
When you're done testing the app, you can remove it from the cluster with the following command:
kubectl delete -f kube
The command deletes all the resources that were created by kubectl apply.
In this section, you learned how to deploy an application to Kubernetes.
Here's a racap of what you learned:
- You defined a Deployment for your app.
- You created a Service to expose your deployment to outside the cluster.
- You created a Deployment for the MongoDB database and to persist its data.
- You deployed all of those resources in your local cluster.
- You verified that Kubernetes successfully created the resources on your behalf.
In the next part, you will learn how to scale your application for high-availability and resiliency.