Introduction
Containers have transformed the way applications are developed, deployed, and managed. They package applications along with their dependencies, making them portable, lightweight, and easy to run across different environments.
With the IBM z/OS Container Platform, this modern approach is now available on the mainframe, enabling organisations to bring cloud-native development practices to z/OS while maintaining enterprise-grade reliability.
This blog walks you through the basics of z/OS containers and demonstrates how to build and run a simple Java microservice.
What is IBM z/OS Container Platform?
The IBM z/OS Container Platform allows developers to build and run containerised applications directly on z/OS. It uses industry-standard container technology, enabling applications to run consistently across environments—from development to production.
Containers on z/OS run as native address spaces, ensuring seamless integration with existing z/OS resources while supporting modern development practices.
Why Choose z/OS Containers?
The platform helps accelerate hybrid cloud transformation by providing:
• Portability and agility across environments
• Kubernetes orchestration support
• Cloud-native Java development for new and existing workloads
• Seamless integration with z/OS data and transactions
By leveraging these capabilities, teams can modernise applications without leaving the z/OS ecosystem.
Which Applications are Suitable for Containers?
Applications that are self-contained and can run independently are ideal candidates for containerisation.
Examples include:
• Web applications
• Microservices
• REST APIs
Containerisation simplifies deployment, improves portability, and enables easier scaling of these workloads.
Supported Java Runtimes
IBM z/OS Container Platform supports Java container images for:
• IBM SDK, Java Technology Edition, Version 8
• IBM Semeru Runtime Certified Edition (Java 11, 17, 21, and 25)
These container images follow Open Container Initiative (OCI) standards and utilise tools such as:
• Podman – container management
• runc – container runtime
• skopeo – image management
• umoci – container image tooling
Java container images are hosted on the IBM Cloud Container Registry under namespace :
icr.io/zoscp/ibmjava:8
icr.io/zoscp/ibm-semeru-runtimes
Prerequisites
Before proceeding, ensure that:
• IBM z/OS Container Platform is installed and configured
• Podman is available on your z/OS system
• You have access to IBM Cloud Container Registry (ICR)
• You have a valid entitlement key
• Java source can be compiled using javac
Getting Started with Java on z/OS Containers
Before starting, decide which Java version you would like to use. In this example, we will use Java 25, but the same process can be followed for Java 8, Java 11, 17, or 21.
Step 1: Configure Podman (if required)
If Podman is not found in your PATH, configure it as follows:
export PATH=$PATH:/usr/lpp/IBM/zoscp/bin
Step 2: Log in to IBM Cloud Container Registry
Authenticate using your entitlement key:
podman login -u iamapikey -p <key> icr.io
You can obtain access from the IBM Container Registry.
Step 3: Trust the Java 25 Container Image
The following command trusts the Java 25 Certified Edition container image:
podman image trust set --type accept icr.io/zoscp/ibm-semeru-runtimes:certified-25-jdk-zos
Step 4: Pull the Container Image
Download the Java 25 container image:
podman pull icr.io/zoscp/ibm-semeru-runtimes:certified-25-jdk-zos
Building a Simple Java Microservice
Let’s create a small microservice that returns a greeting message when accessed through web browser or REST client
To keep this example simple, the Java application is compiled outside the container and only the generated .class file is copied into the image.
Step 1: Create the Java Source File
Create a file named SimpleService.java with the following content:
import com.sun.net.httpserver.HttpServer;
import com.sun.net.httpserver.HttpExchange;
import java.io.IOException;
import java.io.OutputStream;
import java.net.InetSocketAddress;
public class SimpleService {
public static void main(String[] args) throws IOException {
HttpServer server = HttpServer.create(new InetSocketAddress(8080), 0);
server.createContext("/hello", (HttpExchange exchange) -> {
String response = "Hello from the z/OS container microservice!";
exchange.sendResponseHeaders(200, response.length());
try (OutputStream os = exchange.getResponseBody()) {
os.write(response.getBytes());
}
});
System.out.println("Microservice running on port 8080");
server.start();
}
}
This application starts an HTTP server on port 8080 and responds to requests sent to the /hello endpoint.
Step 2: Compile the Application
Compile the Java source using:
javac SimpleService.java
This generates:
SimpleService.class
Step 3: Create the Project Structure
Organise the files as follows:
simpleservice/
├── src/
│ └── SimpleService.java
├── app/
│ └── SimpleService.class
└── Containerfile
Copy the generated SimpleService.class file into the app directory.
Step 4: Create a Container file
A Container file contains the instructions required to build a container image.
Create the file called Containerfile with the following contents:
FROM icr.io/zoscp/ibm-semeru-runtimes:certified-25-jdk-zos
COPY app /app
WORKDIR /app
EXPOSE 8080
CMD ["java", "SimpleService"]
Step 5: Build the Container Image
Build the image using:
podman build -t simpleservice:1.0 .
You should see output similar to:
STEP 1/5: FROM icr.io/zoscp/ibm-semeru-runtimes:certified-25-jdk-zos
STEP 2/5: COPY app /app
--> 85c192e8e74b
STEP 3/5: WORKDIR /app
--> 5771868fae4c
STEP 4/5: EXPOSE 8080
--> 2dc2cfed3f5c
STEP 5/5: CMD ["java", "SimpleService"]
COMMIT simpleservice:1.0
--> b303f8f9303a
Successfully tagged localhost/simpleservice:1.0
b303f8f9303ad2be468773fd1b9d040b8921963fa35fc7a1eaacf8cee0b69f1f
Step 6: Run the Container
The below command creates and starts a container mysvc2 from the image , running the Java application inside it. The port mapping makes the application accessible from the host system.
podman run --name mysvc2 simpleservice:1.0
/u/jenkins:>podman run --name mysvc2 simpleservice:1.0
Expected output :
Microservice running on port 8080
Step 7: Test the Microservice
Open another terminal and run:
curl http://localhost:8080/hello
Output:
Hello from the z/OS container microservice!
Congratulations! You have successfully deployed and executed your first Java microservice in a z/OS container.
Step 8: Stop and Remove the Container
When you are finished testing:
podman stop mysvc2
podman rm mysvc2
Useful Podman Options
• -d → Run container in detached mode
• -it → Interactive terminal
• --name → Assign a container name
• -v host:container → Mount a volume
• -e KEY=value → Set environment variables
• --rm → Remove the container after exit
Conclusion
IBM z/OS Containers provide a modern, standards-based approach to running Java applications on the mainframe. By combining the power of containers with the reliability of z/OS, teams can accelerate development, improve portability, and seamlessly integrate with hybrid cloud environments.
With just a few steps, you can start building and deploying Java 25-based microservices on z/OS, unlocking new possibilities for modern enterprise applications.
References