Skip to content
Tutorials Center
My learning

Topics

Lesson 57 of 66 ยท Packaging and Deployment

Deployment: Cloud, Kubernetes and Config

Deploy a Spring Boot service the 12-factor way: env and secret config, Kubernetes probes, graceful shutdown, zero-downtime rolling releases and a CI/CD pipeline.

You have a jar, and you have a container image. Deployment is the part that turns that image into a service people can rely on: it starts with the right configuration, receives traffic only when it is ready, survives a restart without dropping requests, and can be replaced by a new version while users keep working.

This lesson covers the habits that make a Spring Boot service easy to run: the twelve-factor approach to configuration, secrets, Kubernetes manifests with health probes, graceful shutdown, zero-downtime releases and a basic CI/CD pipeline. It builds on Containers: Dockerfile and Buildpacks, and for the wider Kubernetes picture see Kubernetes for Java and Kubernetes overview.

A cluster cannot run on this site, so the YAML and pipeline files are read-only. The three runnable examples are stand-ins: a rolling-update simulator, a graceful-shutdown demo built on plain Java threads, and a fail-fast configuration check.

The twelve-factor habits that matter most

The twelve-factor app is a checklist for services that run well in the cloud. Four of its factors shape almost every Spring Boot deployment:

Four habits for cloud-ready services

Config in the environment One image, different settings per environment.
Backing services are URLs Swap a database by changing a property.
Logs to stdout The platform collects them. No log files.
Disposable processes Fast start, graceful stop, no local state.

Anything that breaks one of these makes scaling and releases harder.

1 / 2

Spring Boot already supports this style. Every property can be set by an environment variable (SPRING_DATASOURCE_URL sets spring.datasource.url), and spring.profiles.active can come from SPRING_PROFILES_ACTIVE. See Properties, YAML and Externalized Config and Profiles and Environment-Specific Config for the rules and precedence.

Config and secrets in the environment

Plain settings and secrets travel differently. In Kubernetes the usual split is a ConfigMap for ordinary values and a Secret for credentials:

YAML
apiVersion: v1
kind: ConfigMap
metadata:
  name: shop-config
data:
  SPRING_PROFILES_ACTIVE: prod
  SPRING_DATASOURCE_URL: jdbc:postgresql://db.internal:5432/shop
  APP_FEATURE_NEWCHECKOUT: "true"
---
apiVersion: v1
kind: Secret
metadata:
  name: shop-secrets
type: Opaque
stringData:
  SPRING_DATASOURCE_PASSWORD: change-me
  APP_JWT_SECRET: change-me-too

A Kubernetes Secret is only base64-encoded, not encrypted by itself. Treat it as a delivery mechanism and keep the real values in a proper secret manager (your cloud's secret service, Vault, or an operator that syncs them into the cluster), never in Git. Never bake secrets into an image or log them. See Secrets management.

Instead of environment variables, secrets can be mounted as files, one file per key. Spring reads that directory with the config tree import:

YAML
spring:
  config:
    import: "optional:configtree:/etc/secrets/"

A file named db.password in that folder becomes the property db.password. Files are slightly safer than environment variables because they do not show up in process listings or crash dumps.

The third rule is to fail fast. If a required value is missing, the application should refuse to start with a clear message, so the platform never routes traffic to a half-configured service. The next stand-in combines both ideas: it maps environment variable names to property names, checks the required keys and masks secrets in its output.

Java Fail fast on missing config, mask the secrets

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.

A container that crashes on start with a precise message is far easier to fix than one that starts and fails on the first customer request. In real Spring, @ConfigurationProperties with @Validated gives you this behavior, as shown in Type-Safe @ConfigurationProperties.

A Kubernetes Deployment with probes

A Deployment keeps a number of identical pods running and replaces them when you ship a new image. These are the settings that matter for a Spring Boot service:

YAML
apiVersion: apps/v1
kind: Deployment
metadata:
  name: shop
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: shop
  template:
    metadata:
      labels:
        app: shop
    spec:
      terminationGracePeriodSeconds: 45
      containers:
        - name: shop
          image: registry.example.com/shop/api:3f2a9c1
          ports:
            - containerPort: 8080
          envFrom:
            - configMapRef:
                name: shop-config
            - secretRef:
                name: shop-secrets
          resources:
            requests:
              cpu: 250m
              memory: 768Mi
            limits:
              memory: 768Mi
          startupProbe:
            httpGet:
              path: /actuator/health/liveness
              port: 8080
            periodSeconds: 5
            failureThreshold: 30
          livenessProbe:
            httpGet:
              path: /actuator/health/liveness
              port: 8080
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /actuator/health/readiness
              port: 8080
            periodSeconds: 5
          lifecycle:
            preStop:
              exec:
                command: ["sleep", "5"]

The three probes answer different questions. The startup probe gives a slow application time to boot before the other two begin. Liveness decides whether to restart the container, so it should not depend on external systems; a database outage should not make Kubernetes restart every pod. Readiness decides whether the pod receives traffic, and it can reasonably go down during overload or while a dependency is unavailable. The endpoints come from Actuator. The memory request equals the limit so the pod has a predictable footprint, a point covered in the previous lesson.

Graceful shutdown

When Kubernetes stops a pod, it removes it from the load balancer and sends SIGTERM; if the process is still alive after terminationGracePeriodSeconds, it sends SIGKILL. Without precautions, requests that are still running die with the process. Spring Boot can drain them:

YAML
server:
  shutdown: graceful
spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s

On SIGTERM the web server stops accepting new requests, waits up to 30 seconds for in-flight ones, then lets the application close. Keep terminationGracePeriodSeconds larger than that timeout plus the preStop pause. The short preStop sleep covers a practical gap: the load balancer and the pod learn about each other slowly, so a few new requests may still arrive after the signal.

sequenceDiagram
    participant K as Kubernetes
    participant L as Load balancer
    participant P as Pod
    K->>L: Remove the pod from the endpoints
    K->>P: preStop hook (sleep 5 seconds)
    K->>P: SIGTERM
    P->>P: Stop accepting and finish in-flight requests
    P-->>K: Process exits
    K->>P: SIGKILL only after the grace period

Shutdown is a sequence: stop the traffic, signal the process, let it drain, and only then kill.

The stand-in below uses a small thread pool to show the difference. In the graceful run the server refuses new requests but lets running ones finish. In the abrupt run the running requests are interrupted.

Java Graceful versus abrupt shutdown

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.

Request 3 gets a clean rejection in both cases, and the load balancer retries it on another pod. The difference is in requests 1 and 2: graceful completes them, abrupt cuts them off, and the customer sees an error.

Zero-downtime releases

A rolling update replaces pods a few at a time. Two numbers control the pace: maxSurge (how many extra pods may exist) and maxUnavailable (how many may be missing). With maxUnavailable: 0, Kubernetes starts a new pod first and only stops an old one after the new one is ready. That is why readiness probes matter: they are the signal for "safe to continue".

The simulator below runs the rules for three settings with three replicas and a pod that needs two ticks to become ready.

Java Rolling update simulator

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.

The first setting never serves fewer than three pods. The second dips to two, which is fine if two pods carry the load. Recreate drops to zero for the whole start-up time: that is downtime.

A few more rules keep releases smooth:

  • Database changes must be backward compatible with the old version, because old and new pods run side by side. Add a column first, deploy, and drop the old one in a later release. See Database Migrations with Flyway.
  • Use immutable image tags such as the commit hash, never latest, so a rollback means re-deploying an exact earlier image.
  • Watch the rollout. kubectl rollout status deployment/shop waits for it, and kubectl rollout undo deployment/shop goes back.
  • For riskier changes, use canary (send a small share of traffic to the new version) or blue/green (switch everything at once between two full environments) on top of this.

A simple CI/CD pipeline

Continuous integration builds and tests every commit. Continuous delivery then ships passing builds. A small GitHub Actions workflow for the service looks like this:

YAML
name: ci
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 25
          cache: maven
      - name: Build and test
        run: ./mvnw -B verify
      - name: Log in to the registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Build and push the image
        run: |
          docker build -t ghcr.io/acme/shop:${{ github.sha }} .
          docker push ghcr.io/acme/shop:${{ github.sha }}
      - name: Deploy
        run: kubectl set image deployment/shop shop=ghcr.io/acme/shop:${{ github.sha }}

Order matters: tests run before the image is built, the image is tagged with the commit, and the deploy step changes only the image reference. Many teams use GitOps instead of the last step: the pipeline commits the new tag to a configuration repository, and a controller such as Argo CD or Flux applies it to the cluster, which gives you a reviewable history of what runs where. For more on pipelines see CI pipelines.

Where to run it

Option Good for You manage
Managed container platform (Cloud Run, App Runner, Azure Container Apps and similar) Small teams, simple services Image and config
Kubernetes (managed by a cloud provider or self-hosted) Many services, custom networking Manifests, cluster upgrades
Virtual machine with systemd or Docker Compose One or two services, simple budgets Server patches, restarts

Start with the simplest platform that meets your needs. The habits in this lesson (environment config, probes, graceful shutdown, immutable images) carry over to all three.

Deploying to AWS: Elastic Beanstalk and App Runner

Amazon Web Services offers several ways to run a Boot application. Two of the simplest are Elastic Beanstalk, which runs your jar on managed virtual machines, and App Runner, which runs your container image or source code without servers to manage. (Services and their availability change over time, so check the current AWS documentation before you commit to one. The steps below are the general shape, and nothing on this site can run them.)

Elastic Beanstalk with a jar

  1. Build the executable jar: ./mvnw clean package (see Building and Packaging).
  2. Create an application and environment in the console, or with the EB CLI: eb init (choose a region and the Corretto Java platform, the "Java SE" flavor that runs a plain java -jar) and eb create shop-prod.
  3. Make the app listen on the port Beanstalk expects. The platform's nginx proxy forwards traffic to port 5000, so set SERVER_PORT=5000 as an environment property (or server.port=5000 in a profile).
  4. Set configuration as environment properties in the environment settings (database URL, credentials, profile). Boot reads them through relaxed binding, as the demo below shows. Keep secrets in AWS Secrets Manager or Parameter Store rather than in the repository.
  5. Configure the health check path to /actuator/health (or the readiness endpoint, see Actuator). A load balancer that probes / will mark an application unhealthy when / returns 404 or 401.
  6. Deploy with eb deploy, which uploads the new jar and performs a rolling or immutable update depending on the deployment policy.

An optional Procfile next to the jar controls the start command, for example web: java -Xmx512m -jar app.jar, which is how you set JVM options.

The environment needs a database too. The usual choice is Amazon RDS in the same VPC; give the instance profile network access to it, and pass its endpoint as SPRING_DATASOURCE_URL. Creating the database inside the Beanstalk environment is convenient for tests but ties its lifetime to the environment, so production databases are normally created separately.

App Runner with a container image

App Runner starts from an image in Amazon ECR (built as in Docker Images and Buildpacks) or from a source repository. You choose:

  • the port your container listens on (8080 is Boot's default, so no change is needed);
  • CPU and memory for each instance, and minimum and maximum instance counts for automatic scaling;
  • a health check: an HTTP check on /actuator/health is better than the default TCP check, because it proves the application is actually ready;
  • environment variables, and secrets referenced from Secrets Manager or Parameter Store, exposed to the container as ordinary environment variables;
  • an instance role (so the application can call other AWS services without keys in its configuration) and, if needed, a VPC connector to reach a private database.

Whichever service you use, the habits from this lesson apply unchanged: configuration in the environment, a health endpoint, graceful shutdown, one immutable artifact per release and no secrets in the artifact. The platform differs; the application does not.

Environment variables become Spring properties

Both services hand configuration to your app as environment variables, so it helps to know the exact naming rule. Boot's relaxed binding maps spring.datasource.url to SPRING_DATASOURCE_URL: uppercase, dots become underscores, and dashes are removed. Environment variables override values in application.properties. The stand-in applies the rule in both directions for a few keys. What is real: the naming rule and the override order. What is the stand-in: the loop that implements it.

Java Which property does this environment variable set?

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.

Notice app.max-connections: the dash disappears in the variable name (APP_MAXCONNECTIONS). Forgetting this is a common reason why an environment variable "does nothing".

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where should a database password live in a twelve-factor deployment?

    Images and repositories are widely copied. Secrets must be supplied at runtime so the same image can run in any environment without containing credentials.
  2. 2. What is the difference between a liveness and a readiness probe?

    A failing liveness probe makes Kubernetes restart the container. A failing readiness probe only takes the pod out of the service endpoints until it recovers.
  3. 3. Which rollout settings never reduce the number of ready pods during an update?

    With maxUnavailable 0 and room to surge, Kubernetes starts a new pod first and removes an old one only after the new one is ready.
  4. 4. Why should terminationGracePeriodSeconds be larger than spring.lifecycle.timeout-per-shutdown-phase?

    If the grace period ends first, Kubernetes kills the process while requests are still draining, which defeats graceful shutdown.
  5. 5. Why must a database migration be backward compatible during a rolling update?

    During the rollout both versions are live. A change that breaks the old version, such as dropping a column it reads, causes errors until the rollout finishes.

Summary

  • Keep one image and vary configuration through the environment; keep secrets out of images and Git, and fail fast when required config is missing.
  • Use separate startup, liveness and readiness probes backed by Actuator; keep liveness free of external dependencies.
  • Enable server.shutdown=graceful, set a shutdown timeout and make the Kubernetes grace period longer than it.
  • Roll out with maxUnavailable: 0 and readiness checks, tag images immutably, and make database changes backward compatible.
  • Build, test, package and deploy in one pipeline, tagged with the commit; consider GitOps for the final step.
  • Choose the simplest platform that fits: managed containers, Kubernetes or a single VM.

Next: Project: Todo REST API.