This document covers:

1. Gluu 4 VM-based installation
2. Gluu 4 Cloud Native installation on Kubernetes

The goal is to upgrade the Java runtime to Java 25 while keeping Gluu 4.5.14 itself unchanged.

Section-1: Gluu 4 VM-based installation

Overview

Gluu Server 4.5.14 ships with Java 21 by default.
However, administrators can upgrade the runtime to Java 25 without upgrading Gluu itself.

This is done by installing Amazon Corretto 25 and updating the /opt/jre symlink that Gluu services use.

This process changes only the Java runtime, not the Gluu binaries.

Prerequisites

Before proceeding, ensure:

• You are running Gluu Server 4.5.14 on a virtual machine
• You have root or sudo access
• Internet access is available to download Corretto
• Services can be restarted safely

Recommended:

• Take a VM snapshot
• Back up the /opt directory

Upgrade Procedure

Step-1: Navigate to /opt

cd /opt/

Step-2: Download Amazon Corretto 25

wget https://corretto.aws/downloads/latest/amazon-corretto-25-x64-linux-jdk.tar.gz

This downloads the latest Amazon Corretto Java 25 JDK.

Step-3: Extract the archive

tar -xzf amazon-corretto-25-x64-linux-jdk.tar.gz

This will create a directory similar to:

/opt/amazon-corretto-25.x.x.x-linux-x64

Step-4: Update the Java runtime symlink

Gluu services use:

/opt/jre

Update this symlink to point to the new Java installation.

ln -sfn /opt/amazon-corretto-25.0.2.10.1-linux-x64 /opt/jre

Explanation:

Step-5: Remove downloaded archive (optional)

rm -rf amazon-corretto-25-x64-linux-jdk.tar.gz

Step-6: Restart Gluu services

You can restart services individually or reboot the VM.

Verification

Confirm the Java version used by Gluu.

/opt/jre/bin/java -version

Expected output:

openjdk version "25.0.2" 2026-01-20 LTS
OpenJDK Runtime Environment Corretto-25.0.2.10.1 (build 25.0.2+10-LTS)
OpenJDK 64-Bit Server VM Corretto-25.0.2.10.1 (build 25.0.2+10-LTS, mixed mode, sharing)

You may also verify running Java processes:

ps -ef | grep java

Rollback Procedure

If problems occur, revert the symlink to the previous Java runtime.

Example:

ln -sfn /opt/jre-21 /opt/jre

Then restart services again.

Notes

• Test upgrades in non-production environments first
• Monitor logs after restart

Example:

/opt/gluu/jetty/oxauth/logs
/opt/gluu/jetty/identity/logs

Summary

Section-2: Gluu 4 Cloud Native installation on Kubernetes

Overview

This section describes how to upgrade the Java runtime used by the oxauth and oxtrust containers in a Kubernetes-based Gluu 4.5.14 deployment.

The approach is:

1. start from the existing Gluu component image
2. layer BellSoft Liberica OpenJRE 25.0.2 into that image
3. publish the custom image to a container registry
4. update the Kubernetes workload to use the new image
5. verify that the pod is running with the updated image and Java runtime

This follows the same image-overlay pattern used for upgrading oxauth to Java 25.

Scope

This procedure covers:

• oxauth
• oxtrust

It does not change other Gluu components such as:

• oxd-server
• oxpassport

If you want Java 25 for additional components, the same image-overlay method can be repeated for those components separately.

Kubernetes object type difference

Before starting, note the workload type used by each component:

• oxauth runs as a Deployment
• oxtrust runs as a StatefulSet

That means the image build and push process is the same, but the Kubernetes update commands differ:

• oxauth update target: deployment/gluu-oxauth
• oxtrust update target: statefulset/gluu-oxtrust

Prerequisites

• Gluu 4.5.14 is already deployed in Kubernetes
• the gluu-oxauth Deployment is running
• the gluu-oxtrust StatefulSet is running
• Docker is available on the build host
• a container registry is available to store the custom image
• the Kubernetes cluster can pull from that registry

Example used below:

• base image for oxauth: gluufederation/oxauth:4.5.14-1
• base image for oxtrust: gluufederation/oxtrust:4.5.14-1
• target image for oxauth: localhost:32000/oxauth-java25:4.5.14-1
• target image for oxtrust: localhost:32000/oxtrust-java25:4.5.14-1

Part-A: Upgrade oxauth to Java 25

Step-1: Confirm the current oxauth image

Check the container name and current image used by the gluu-oxauth Deployment:

microk8s.kubectl -n gluu get deploy gluu-oxauth -o jsonpath='{range .spec.template.spec.containers[*]}{.name}{" => "}{.image}{"\n"}{end}'

Expected output should show the oxauth container and its current image, for example:

oxauth => gluufederation/oxauth:4.5.14-1

Step-2: Create a working directory

mkdir -p ~/oxauth-java25
cd ~/oxauth-java25

Step-3: Create the Dockerfile

Create a Dockerfile that copies Java 25 into the existing oxauth image:

cat > ~/oxauth-java25/Dockerfile <<'EOF_DOCKERFILE'
FROM bellsoft/liberica-openjre-alpine:25.0.2@sha256:87025d11840c8e873019b59f2d64a6b3da4bc5e126bb6d51aa3cd86f1b8b27be AS java-25
FROM gluufederation/oxauth:4.5.14-1
COPY --from=java-25 /usr/lib/jvm /usr/lib/jvm
ENV JAVA_HOME=/usr/lib/jvm/jre-25.0.2-bellsoft-x86_64
ENV PATH=${JAVA_HOME}/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
EOF_DOCKERFILE

Verify the Dockerfile:

cat ~/oxauth-java25/Dockerfile

Step-4: Build the custom image

docker build --rm --force-rm -t oxauth-java25:4.5.14-1 .

Step-5: Validate the image locally

docker run --rm oxauth-java25:4.5.14-1 sh -c 'java -version; echo; echo $JAVA_HOME'

Expected output should show:

• Java version 25.0.2
• JAVA_HOME=/usr/lib/jvm/jre-25.0.2-bellsoft-x86_64

Step-6: Tag and push the image to a registry

Option-A: MicroK8s local registry

If using the MicroK8s local registry on port 32000:

docker tag oxauth-java25:4.5.14-1 localhost:32000/oxauth-java25:4.5.14-1
docker push localhost:32000/oxauth-java25:4.5.14-1

If you see an error like the one below, then you need to enable registry:

failed to do request: Head "https://localhost:32000/v2/oxauth-java25/blobs/sha256:...": dial tcp 127.0.0.1:32000: connect: connection refused

To enable registry:

microk8s enable registry

Option-B: External/private registry

docker tag oxauth-java25:4.5.14-1 <your-registry>/oxauth-java25:4.5.14-1
docker push <your-registry>/oxauth-java25:4.5.14-1

Make sure the Kubernetes cluster can pull from the registry. If the registry is private, configure the appropriate imagePullSecrets.

Step-7: Update the oxauth Deployment

Patch the running gluu-oxauth Deployment to use the new image.

If using the MicroK8s local registry

microk8s.kubectl -n gluu set image deployment/gluu-oxauth oxauth=localhost:32000/oxauth-java25:4.5.14-1

If using another registry

microk8s.kubectl -n gluu set image deployment/gluu-oxauth oxauth=<your-registry>/oxauth-java25:4.5.14-1

Step-8: Watch the rollout

microk8s.kubectl -n gluu rollout status deployment/gluu-oxauth

Step-9: Verify the running image

microk8s.kubectl -n gluu get pod -l app=oxauth -o wide
microk8s.kubectl -n gluu get pod <oxauth-pod-name> -o jsonpath='{.spec.containers[0].image}{"\n"}{.status.containerStatuses[0].imageID}{"\n"}'

Optional — Verify Java inside the running oxauth container

microk8s.kubectl -n gluu exec -ti <oxauth-pod-name> -- sh -c 'java -version; echo; echo $JAVA_HOME'

Expected output:

• Java 25.0.2
• JAVA_HOME=/usr/lib/jvm/jre-25.0.2-bellsoft-x86_64

Rollback oxauth

microk8s.kubectl -n gluu set image deployment/gluu-oxauth oxauth=gluufederation/oxauth:4.5.14-1
microk8s.kubectl -n gluu rollout status deployment/gluu-oxauth

Part-B: Upgrade oxtrust to Java 25

Step-1: Confirm the current oxtrust image

Check the container name and current image used by the gluu-oxtrust StatefulSet:

microk8s.kubectl -n gluu get statefulset gluu-oxtrust -o jsonpath='{range .spec.template.spec.containers[*]}{.name}{" => "}{.image}{"\n"}{end}'

Expected output should show:

oxtrust => gluufederation/oxtrust:4.5.14-1

Step-2: Create a working directory

mkdir -p ~/oxtrust-java25
cd ~/oxtrust-java25

Step-3: Create the Dockerfile

Create a Dockerfile that copies Java 25 into the existing oxtrust image:

cat > ~/oxtrust-java25/Dockerfile <<'EOF_DOCKERFILE'
FROM bellsoft/liberica-openjre-alpine:25.0.2@sha256:87025d11840c8e873019b59f2d64a6b3da4bc5e126bb6d51aa3cd86f1b8b27be AS java-25
FROM gluufederation/oxtrust:4.5.14-1
COPY --from=java-25 /usr/lib/jvm /usr/lib/jvm
ENV JAVA_HOME=/usr/lib/jvm/jre-25.0.2-bellsoft-x86_64
ENV PATH=${JAVA_HOME}/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
EOF_DOCKERFILE

Verify the Dockerfile:

cat ~/oxtrust-java25/Dockerfile

Step-4: Build the custom image

docker build --rm --force-rm -t oxtrust-java25:4.5.14-1 .

Step-5: Validate the image locally

docker run --rm oxtrust-java25:4.5.14-1 sh -c 'java -version; echo; echo $JAVA_HOME'

Expected output should show:

• Java version 25.0.2
• JAVA_HOME=/usr/lib/jvm/jre-25.0.2-bellsoft-x86_64

Step-6: Tag and push the image to a registry

Option-A: MicroK8s local registry

If using the MicroK8s local registry on port 32000:

docker tag oxtrust-java25:4.5.14-1 localhost:32000/oxtrust-java25:4.5.14-1
docker push localhost:32000/oxtrust-java25:4.5.14-1

Option-B: External/private registry

docker tag oxtrust-java25:4.5.14-1 <your-registry>/oxtrust-java25:4.5.14-1
docker push <your-registry>/oxtrust-java25:4.5.14-1

Make sure the Kubernetes cluster can pull from the registry. If the registry is private, configure the appropriate imagePullSecrets.

Step-7: Update the oxtrust StatefulSet

Patch the running gluu-oxtrust StatefulSet to use the new image.

If using the MicroK8s local registry

microk8s.kubectl -n gluu set image statefulset/gluu-oxtrust oxtrust=localhost:32000/oxtrust-java25:4.5.14-1

If using another registry

microk8s.kubectl -n gluu set image statefulset/gluu-oxtrust oxtrust=<your-registry>/oxtrust-java25:4.5.14-1

Step-8: Watch the rollout

microk8s.kubectl -n gluu rollout status statefulset/gluu-oxtrust

Expected output may look like:

partitioned roll out complete: 1 new pods have been updated...

Step-9: Verify the running image

microk8s.kubectl -n gluu get pod gluu-oxtrust-0 -o jsonpath='{.spec.containers[0].image}{"\n"}{.status.containerStatuses[0].imageID}{"\n"}'

Expected output should show the custom image and its digest, for example:

localhost:32000/oxtrust-java25:4.5.14-1
localhost:32000/oxtrust-java25@sha256:...

Optional — Verify Java inside the running oxtrust container

microk8s.kubectl -n gluu exec -ti gluu-oxtrust-0 -- sh -c 'java -version; echo; echo $JAVA_HOME'

Expected output:

• Java 25.0.2
• JAVA_HOME=/usr/lib/jvm/jre-25.0.2-bellsoft-x86_64

Rollback oxtrust

microk8s.kubectl -n gluu set image statefulset/gluu-oxtrust oxtrust=gluufederation/oxtrust:4.5.14-1
microk8s.kubectl -n gluu rollout status statefulset/gluu-oxtrust

Post-upgrade sanity checks

After upgrading either component, do not stop at java -version. Also verify:

• pod is 1/1 Running
• logs do not show immediate Java or startup exceptions
• ingress/UI access still works
• the component responds normally under real traffic

Example commands:

microk8s.kubectl -n gluu get pods -o wide
microk8s.kubectl -n gluu logs deploy/gluu-oxauth --since=10m
microk8s.kubectl -n gluu logs gluu-oxtrust-0 --since=10m

Section-2: Summary

Using this method, the oxauth and oxtrust containers can be upgraded from their default Java runtime to Java 25 while keeping the Gluu 4.5.14 application images themselves unchanged.

The key idea is:

• keep the original application image
• replace only the Java runtime layer
• publish the custom image
• update the Kubernetes workload to use the new image
• verify the running pod and Java version

The only operational difference is the Kubernetes workload type:

• oxauth uses a Deployment
• oxtrust uses a StatefulSet

That is the Kubernetes equivalent of the Docker-based Java 25 image procedure for both components.