How to Deploy Quarkus Microservices to Kubernetes Using Docker

Quarkus is a modern Java framework designed for cloud-native development, offering fast startup times, low memory usage, and seamless integration with containers. In this tutorial, we’ll walk through how to build a simple Quarkus microservice, containerize it with Docker, and deploy it to Kubernetes.

Prerequisites

Before we begin, make sure the following tools are installed on your system:

• Java 17+
• Quarkus CLI or Maven
• Docker
• Kubernetes (e.g., Minikube, Kind, or any cloud K8s cluster)
• kubectl CLI

1. Create a Quarkus Microservice

You can create a new Quarkus project using the CLI:

quarkus create app org.acme:quarkus-demo --no-code
cd quarkus-demo

Or use Maven:

mvn io.quarkus:quarkus-maven-plugin:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=quarkus-demo \
    -DclassName="org.acme.GreetingResource" \
    -Dpath="/hello"
cd quarkus-demo

The GreetingResource.java will look like this:

package org.acme;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@Path("/hello")
public class GreetingResource {

    @GET
    public String hello() {
        return "Hello from Quarkus!";
    }
}

Run the app locally to test:

./mvnw quarkus:dev

Or

mvn quarkus:dev

Visit http://localhost:8080/hello to see the response.

2. Add a Dockerfile

Quarkus supports Docker when creating a new Quarkus application. There should be a src/main/docker/Dockerfile.jvm

FROM registry.access.redhat.com/ubi9/openjdk-17:1.21

ENV LANGUAGE='en_US:en'

# We make four distinct layers so if there are application changes the library layers can be re-used
COPY --chown=185 target/quarkus-app/lib/ /deployments/lib/
COPY --chown=185 target/quarkus-app/*.jar /deployments/
COPY --chown=185 target/quarkus-app/app/ /deployments/app/
COPY --chown=185 target/quarkus-app/quarkus/ /deployments/quarkus/

EXPOSE 8080
USER 185
ENV JAVA_OPTS_APPEND="-Dquarkus.http.host=0.0.0.0 -Djava.util.logging.manager=org.jboss.logmanager.LogManager"
ENV JAVA_APP_JAR="/deployments/quarkus-run.jar"

ENTRYPOINT [ "/opt/jboss/container/java/run/run-java.sh" ]

3. Build the Docker Image

Build a Quarkus application.

mvn clean package

Use the following command to build the Docker image:

docker build -f src/main/docker/Dockerfile.jvm -t quarkus-demo .

Run it locally to test:

docker run -i --rm -p 8080:8080 quarkus-demo

4. Push Docker Image to a Registry

If you're using Docker Hub:

docker login
docker tag quarkus-demo yourusername/quarkus-demo
docker push yourusername/quarkus-demo

Make sure to replace yourusername with your actual Docker Hub username.

5. Create Kubernetes Manifests

deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: quarkus-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: quarkus-demo
  template:
    metadata:
      labels:
        app: quarkus-demo
    spec:
      containers:
        - name: quarkus-demo
          image: yourusername/quarkus-demo
          ports:
            - containerPort: 8080

service.yaml

apiVersion: v1
kind: Service
metadata:
  name: quarkus-demo
spec:
  selector:
    app: quarkus-demo
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080
  type: LoadBalancer

6. Deploy to Kubernetes

We will use Minikube. To do that, install Minikube using the following command.

curl -LO https://github.com/kubernetes/minikube/releases/latest/download/minikube-darwin-arm64
sudo install minikube-darwin-arm64 /usr/local/bin/minikube

Start your cluster.

minikube start

Apply the manifests using kubectl:

kubectl apply -f deployment.yaml
kubectl apply -f service.yaml

Check that the pods and services are running:

kubectl get pods
kubectl get services

If using Minikube:

minikube service quarkus-demo

Or use port-forwarding:

kubectl port-forward svc/quarkus-demo 8080:80

Test in the browser:

http://localhost:8080/hello

7. Optional: Use Minikube Dashboard or Lens

For better visibility, use the Minikube dashboard:

minikube dashboard

Or install Lens for a GUI-based Kubernetes management.

Conclusion

In this tutorial, you learned how to:

• Create a Quarkus microservice
• Containerize it using Docker
• Push the image to a registry
• Deploy and expose it in Kubernetes

This setup is a solid foundation for building scalable, cloud-native Java applications. You can take it further by implementing CI/CD pipelines, adding health checks, or exploring Helm and Kustomize for configuration management.

You can get the full source code on our GitHub.

That's just the basics. If you need more deep learning about Java and Spring Framework, you can take the following cheap course:

• Java basics, Java in Use //Complete course for beginners
• Java Programming: Master Basic Java Concepts
• Master Java Web Services and REST API with Spring Boot
• JDBC Servlets and JSP - Java Web Development Fundamentals
• The Complete Java Web Development Course
• Spring MVC For Beginners: Build Java Web App in 25 Steps
• Practical RESTful Web Services with Java EE 8 (JAX-RS 2.1)

Thanks!