Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 36 ยท Testing and Deployment

Containers, Kubernetes and Deployment

Package a Quarkus app as a container image with Jib or Docker, generate Kubernetes manifests from application.properties, tune JVM memory and deploy with probes.

A Quarkus service is finished when it runs reliably in the place your customers reach it. Today that place is usually a container on Kubernetes or a platform built on it (OpenShift, Cloud Run, Azure Container Apps, ECS). Quarkus treats this as a first-class concern: extensions build the image, generate the manifests and wire the probes from the same application.properties you already use.

This lesson walks through the packaging choices, the image build extensions, the generated Kubernetes resources, JVM settings inside containers, and a deployment checklist. It builds on native images, health checks and configuration in production. For Docker and Kubernetes fundamentals see the Docker tutorial and the Kubernetes tutorial. Containers and clusters are not available on this site, so commands and YAML are read-only and the TryIts compute the same results in plain Java.

What "package" produces

By default ./mvnw package creates the fast-jar layout in target/quarkus-app/:

TEXT
target/quarkus-app/
  quarkus-run.jar          the launcher: java -jar target/quarkus-app/quarkus-run.jar
  lib/boot/                libraries needed to boot
  lib/main/                your dependencies (change rarely)
  app/                     your own classes (change on every build)
  quarkus/                 generated bytecode and serialized build output

The split is deliberate: dependencies seldom change, your code changes constantly. In a container image each folder can become its own layer, so rebuilding after a code change re-uploads only a few kilobytes. Other packaging types exist: uber-jar (one big jar, simple but a big layer), native (executable, see the previous lesson) and mutable-jar (for remote dev).

Building an image

You have three common options, chosen by adding an extension.

Extension How it builds Needs a Docker daemon
quarkus-container-image-jib Jib assembles layers directly No
quarkus-container-image-docker Runs docker build with a Dockerfile Yes
quarkus-container-image-buildpack / openshift / podman Buildpacks, OpenShift S2I, Podman Depends

With Jib, one command builds and pushes an image:

PROPERTIES
quarkus.container-image.group=shop
quarkus.container-image.name=orders
quarkus.container-image.tag=${quarkus.application.version}
quarkus.container-image.registry=registry.example.com
%prod.quarkus.jib.base-jvm-image=eclipse-temurin:25-jre
quarkus.jib.jvm-additional-arguments=-XX:MaxRAMPercentage=75
Terminal
./mvnw package -Dquarkus.container-image.build=true -Dquarkus.container-image.push=true

If you prefer a Dockerfile, new projects contain src/main/docker/Dockerfile.jvm, Dockerfile.legacy-jar and Dockerfile.native. Build the app first, then the image:

Terminal
./mvnw package
docker build -f src/main/docker/Dockerfile.jvm -t shop/orders:1.0 .
docker run --rm -p 8080:8080 -e QUARKUS_DATASOURCE_PASSWORD=secret shop/orders:1.0

Practices that matter: use a slim, maintained JRE base image, run as a non-root user (the Quarkus Dockerfiles do), pin the base image tag, and never ENV a password.

Generating Kubernetes resources

Add quarkus-kubernetes and the build writes ready-to-apply YAML to target/kubernetes/kubernetes.yml: a Deployment, a Service, the probes pointing at /q/health/... if SmallRye Health is present, and a ServiceAccount. You control it with properties:

PROPERTIES
quarkus.kubernetes.name=orders
quarkus.kubernetes.replicas=3
quarkus.kubernetes.namespace=shop
quarkus.kubernetes.resources.requests.memory=256Mi
quarkus.kubernetes.resources.limits.memory=512Mi
quarkus.kubernetes.resources.requests.cpu=250m
quarkus.kubernetes.env.vars.GREETING_MESSAGE=Hello from the cluster
quarkus.kubernetes.env.secrets=orders-db
quarkus.kubernetes.env.configmaps=orders-settings
quarkus.kubernetes.ingress.expose=true
quarkus.kubernetes.ingress.host=orders.example.com
Terminal
./mvnw package -Dquarkus.kubernetes.deploy=true     # build, push, kubectl apply
kubectl get pods -n shop

You can also commit the generated YAML (GitOps with Argo CD or Flux), post-process it with Kustomize, or generate a Helm chart with quarkus-helm. For OpenShift use quarkus-openshift, which adds Routes and image streams; for Knative, quarkus-kubernetes with quarkus.kubernetes.deployment-target=knative.

From code to cluster

Package fast-jar or native runner.
Image Jib, Docker or buildpacks.
Manifests Generated from properties.
Deploy kubectl, Helm or GitOps.

One set of properties drives all four steps.

1 / 2
Java Stand-in: render a Deployment from properties

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

JVM memory inside containers

A container has a memory limit. If the process exceeds it, the kernel kills it (OOMKilled, exit code 137). The JVM reads the container limit and sizes itself accordingly, but the default heap is only a quarter of it, and the JVM uses extra memory outside the heap (metaspace, thread stacks, direct buffers, code cache). Set the heap as a share of the limit and leave room for the rest:

PROPERTIES
quarkus.jib.jvm-additional-arguments=-XX:MaxRAMPercentage=70,-XX:+ExitOnOutOfMemoryError

A practical sizing rule: heap = 60 to 75 percent of the limit; the remainder covers non-heap memory. ExitOnOutOfMemoryError makes the process exit so Kubernetes restarts it, instead of staying half-alive. Set the request equal to the memory the app needs in normal operation and the limit a bit higher. For CPU, avoid tight limits during startup: throttling slows the JIT and makes startup long, which is also where native images help.

Java Stand-in: a memory budget for a container

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Rollouts and configuration

  • Use rolling updates with readinessProbe: new pods receive traffic only when ready, so users do not see errors. Set maxUnavailable: 0 for zero downtime.
  • Handle graceful shutdown: Kubernetes sends SIGTERM; Quarkus stops accepting connections and finishes in-flight requests. Set quarkus.shutdown.timeout=30s below the pod's terminationGracePeriodSeconds.
  • Run database migrations (Flyway or Liquibase) as part of startup with care: if three pods start together, the migration tool takes a lock, but long migrations delay readiness. A separate migration job is safer for big changes.
  • Scale with a HorizontalPodAutoscaler on CPU or custom metrics. Remember that startup time and memory per pod decide how fast and how cheaply you scale; this is where Quarkus's design pays off.
  • Keep configuration in ConfigMaps and Secrets and the image identical across environments.

Other targets

The same JAR or native binary runs on AWS Lambda (quarkus-amazon-lambda), Azure Functions, Google Cloud Functions, Knative serverless, a plain VM with systemd, or Docker Compose for small setups. Pick the extension for the platform; application code stays the same.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does the fast-jar layout separate lib/ from app/?

    Separate folders become separate image layers, so rebuilds upload only the small, changing part.
  2. 2. Which extension builds a container image without a Docker daemon?

    Jib builds layers directly and can push to a registry without a local daemon.
  3. 3. A pod is OOMKilled with exit code 137. What is a likely cause?

    The JVM uses memory outside the heap; a heap near 100 percent of the limit leaves no room for it.
  4. 4. Where should the production database password come from in a Kubernetes deployment?

    Secrets stay outside the image and outside the repository.

Summary

  • package produces a layered fast-jar; add Jib, Docker or buildpack extensions to build images.
  • quarkus-kubernetes generates Deployment, Service and probes from quarkus.kubernetes.* properties.
  • Size heap as a share of the container limit and leave room for non-heap memory.
  • Use readiness for rollouts, graceful shutdown, platform-supplied secrets and one image for all environments.

Next: Project: A Bookshop API