This lab will walk you through steps to build container images with various technologies.
-
Slides: https://speakerdeck.com/maeddes/options-galore-from-source-code-to-container-image
-
Recording (English): https://www.youtube.com/watch?v=mFamovTQ6Po
-
Recording (German): https://www.youtube.com/watch?v=ga8iqQ25lUY
-
Carlos Repo: https://github.com/carlosbarragan/java-containers-demo
Mandatory:
-
A Docker environment and Docker CLI https://docs.docker.com/get-docker/
-
Pack CLI for Cloud-Native Buildpacks https://buildpacks.io/docs/tools/pack/
-
Clone/Download this repo: https://github.com/maeddes/options-galore-container-build
Recommended:
-
A Java (17 or later) Development Kit for Java examples, e.g https://adoptopenjdk.net/
Optional:
-
Dive tool https://github.com/wagoodman/dive
Links:
Validate docker installation.
docker versionShould display output like (version might differ):
Client: Docker Engine - Community Version: 25.0.3 API version: 1.44 ... Server: Docker Engine - Community Engine: Version: 25.0.3 API version: 1.44 (minimum version 1.24)
Validate Java.
java --versionShould display output like (version might differ):
openjdk 17.0.7 2023-04-18 OpenJDK Runtime Environment (build 17.0.7+7-Ubuntu-0ubuntu120.04) OpenJDK 64-Bit Server VM (build 17.0.7+7-Ubuntu-0ubuntu120.04, mixed mode, sharing)
Download/clone the repo and change to the root folder. If you are running in gitpod,codespaces or using devcontainer, you can skip this step.
git clone https://github.com/maeddes/options-galore-container-buildNote: Without git CLI you can download the repo as zip file here: https://github.com/maeddes/options-galore-container-build/archive/refs/heads/main.zip Extract it and change your command line shell to the root folder.
cd options-galore-container-buildBuild the code:
Change to the Java sample app
cd javaOption 1 (with local JDK installed)
./mvnw clean packageValidate build artefact (timestamps will of course be different)
ls -ltr ./target/simplecode-0.0.1-SNAPSHOT.jar-rw-r--r-- 1 root root 20951064 May 5 11:47 ./target/simplecode-0.0.1-SNAPSHOT.jar
Observe contents of Dockerfile-simple-ubuntu
cat Dockerfile-simple-ubuntuFROM ubuntu:22.04 RUN apt update && apt install openjdk-17-jre-headless -y COPY target/simplecode-0.0.1-SNAPSHOT.jar /opt/app.jar CMD ["java","-jar","/opt/app.jar"]
Build first image with this Dockerfile:
docker build -f Dockerfile-simple-ubuntu -t java-app:v-simple-ubuntu .Build images with other predefined base images:
docker build -f Dockerfile-simple-temurin -t java-app:v-simple-temurin .docker build -f Dockerfile-simple-ibm-semeru -t java-app:v-simple-ibm-semeru .Validate images in local repo
docker imagesREPOSITORY TAG IMAGE ID CREATED SIZE java-app v-simple-ibm-semeru 3a7c058097d9 8 seconds ago 300MB java-app v-simple-temurin 62c5ca75dad1 32 seconds ago 292MB java-app v-simple-ubuntu a491383f3f53 2 minutes ago 400MB----
Observe build history and differences of the 3 images
docker history java-app:v-simple-ubuntu
docker history java-app:v-simple-temurin
docker history java-app:v-simple-ibm-semeruYou will observe different base layers and structure, but always the same top layer:
IMAGE CREATED CREATED BY SIZE COMMENT 7209f28736c8 3 minutes ago /bin/sh -c #(nop) CMD ["java" "-jar" "/opt/… 0B e5385e2e3146 3 minutes ago /bin/sh -c #(nop) COPY file:90a1db2252f31169… 19MB
Optional: Use tool "dive" to show detailed history of image:
dive java-app:v-simple-ubuntudive java-app:v-simple-temurindive java-app:v-simple-ibm-semeruUsage: ctrl+l (ensure layer changes) <tab> ctrl+u (uncheck unmodified) <tab> <arrows> for layer switch
Build image with Multistage Dockerfile:
docker build -f Dockerfile-multistage-builder -t java-app:v-multistage-builder .This will take a while as all the maven dependencies need to be downloaded.
Validate history:
docker history java-app:v-multistage-builderExplore docker images:
docker imagesREPOSITORY TAG IMAGE ID CREATED SIZE java-app v-multistage-builder 816512fee0cd 17 seconds ago 291MB
Perform a slight modification in the source code which does not affect the behaviour of the application. You can use the editor 'nano' to execute this:
nano src/main/java/de/maeddes/simplecode/SimplecodeApplication.javaLocate the method hello()
@GetMapping("/")
String hello(){
logger.info("Call to hello method on instance: " + getInstanceId());
return getInstanceId()+" Hello, Container people ! ";
}
and just add some characters to the method name, e.g.
String helloABC(){
And save it using Ctrl+X and confirm with 'Y'.
Now you can repeat the docker build call.
docker build -f Dockerfile-multistage-builder -t java-app:v-multistage-builder .You can observe that all the dependencies will need to get downloaded again. This method does not cache anything.
Build with multistage cache option:
docker build -f Dockerfile-multistage-cache -t java-app:v-multistage-cache .Change the code and rebuild:
You can use an editor to change a method name in
src/main/java/de/maeddes/simplecode/SimplecodeApplication.java
or simply execute
sed -i 's/hello/helloABC/g' src/main/java/de/maeddes/simplecode/SimplecodeApplication.java(Linux)
or
sed -i '' 's/hello/helloABC/g' src/main/java/de/maeddes/simplecode/SimplecodeApplication.java(Mac)
Rebuild and observe faster build through caching:
docker build -f Dockerfile-multistage-cache -t java-app:v-multistage-cache .Observe the history to validate that top layer is still 'monolithic':
docker history java-app:v-multistage-cacheBuild the code with a layered jar approach:
docker build -f Dockerfile-multistage-layered -t java-app:layered .Display layered state
docker history java-app:layeredIMAGE CREATED CREATED BY SIZE COMMENT de2cb7c4be82 8 seconds ago ENTRYPOINT ["java" "org.springframework.boot… 0B buildkit.dockerfile.v0 <missing> 8 seconds ago COPY application/application/ ./ # buildkit 6.12kB buildkit.dockerfile.v0 <missing> 8 seconds ago COPY application/snapshot-dependencies/ ./ #… 0B buildkit.dockerfile.v0 <missing> 8 seconds ago COPY application/spring-boot-loader/ ./ # bu… 245kB buildkit.dockerfile.v0 <missing> 8 seconds ago COPY application/dependencies/ ./ # buildkit 18.9MB buildkit.dockerfile.v0
Finally have a look at the Dockerfile with specific JVM flags:
cat Dockerfile-multistage-layered-jvm-flagsin the final line you can see how to apply alternative settings here.
ENTRYPOINT ["java","-XX:+UseParallelGC","-XX:MaxRAMPercentage=75","org.springframework.boot.loader.JarLauncher"]
The following steps show how to build container images with the jib-maven plugin.
Again the use of the local maven wrapper (mvnw) will require a local JDK installation. If it’s not present use option 2.
Option 1:
./mvnw compile com.google.cloud.tools:jib-maven-plugin:3.3.2:dockerBuild -Dimage=java-app:jibIn this case the :dockerBuild part will instruct the plugin to build to the local docker daemon. The -Dimage parameter will specify the image name tag.
If you have a docker account you can login and push directly to the docker hub using: (Replace <docker_id> with your own username)
./mvnw compile com.google.cloud.tools:jib-maven-plugin:3.3.2:build -Dimage=<docker_id>/java-app:jibAnother option is to export the image directly to a tar. Use the following command.
./mvnw compile com.google.cloud.tools:jib-maven-plugin:3.3.2:buildTar -Dimage=java-app:jibYou will see an output saying
After that you can import the image into the local registry.
docker load -i target/jib-image.tar15bbc04e2cf6: Loading layer [==================================================>] 41.71MB/41.71MB 7f270d883779: Loading layer [==================================================>] 16.82MB/16.82MB 496ff124a7de: Loading layer [==================================================>] 213B/213B 965a8d44c836: Loading layer [==================================================>] 1.345kB/1.345kB 5e91304a655b: Loading layer [==================================================>] 219B/219B Loaded image: java-app:jib
Option 2:
Without local maven you can only perform the tar build and direct import via load.
docker run -it --rm --name my-maven-project -v "$(pwd)":/opt/app -w /opt/app maven:3.6.3-jdk-11 mvn compile com.google.cloud.tools:jib-maven-plugin:3.3.1:buildTar -Dimage=java-app:jibLoad the exported tar file as image into the local registry.
docker load -i target/jib-image.tar15bbc04e2cf6: Loading layer [==================================================>] 41.71MB/41.71MB 7f270d883779: Loading layer [==================================================>] 16.82MB/16.82MB 496ff124a7de: Loading layer [==================================================>] 213B/213B 965a8d44c836: Loading layer [==================================================>] 1.345kB/1.345kB 5e91304a655b: Loading layer [==================================================>] 219B/219B Loaded image: java-app:jib
Both options - final steps:
Now that you’ve built and loaded the image into the local registry using one of the options above, inspect the layered structure of the image.
docker history java-app:jibIMAGE CREATED CREATED BY SIZE COMMENT bafe5ced0d6f 51 years ago jib-maven-plugin:3.1.4 82B jvm arg files <missing> 51 years ago jib-maven-plugin:3.1.4 2.37kB classes <missing> 51 years ago jib-maven-plugin:3.1.4 1B resources <missing> 51 years ago jib-maven-plugin:3.1.4 18.9MB dependencies
Optional: Perform some small modifications in the code similar to the ones during the Dockerfile exercise. Re-run the build steps and observe the caching and improved performance.
Note: All of the previous examples referenced the jib plugin directly in the maven call. An alternative (and probably the clean way) to the steps above is to add the plugin to your pom.xml:
The <to> tag in the following xml sets the target image path in the image registry. In our case we are using the local registry and thus just providing the image tag.
You can add the following plugin to your pom.xml
<plugin>
<groupId>com.google.cloud.tools</groupId>
<artifactId>jib-maven-plugin</artifactId>
<version>3.3.2</version>
<configuration>
<to>
<image>java-app:jib-v2.0</image>
</to>
</configuration>
</plugin>In this case the invocation looks much simpler.
./mvnw compile jib:dockerBuildThe :build and :buildTar options work accordingly.
It is of course also possible to define custom JVM arguments with Jib. However this is not possible with a plain mvn call. You also can of course apply these settings not during build time, but when starting the container:
docker run --env JAVA_TOOL_OPTIONS='-XX:+UseParallelGC -XX:MaxRAMPercentage=75' java-app:jib
Access the pack CLI and list the suggest builders. A builder includes the buildpacks and environment that will be used for building and running your app.
pack builder suggestSet a default builder to avoid specifying a builder every time you build. For the examples in this tutorial use the base builder image from Paketo buildpacks.
pack config default-builder paketobuildpacks/builder-jammy-baseNow all is set to build the container image using the buildpack. Simply execute:
pack build java-app:packThe first invocation will take a long time. The builder image is big as it contains all the logic plus buildpacks.
After it is downloaded can now observe the output - the so-called bill of materials. This gives detailed information about the build.
Should display output like:
===> ANALYZING ... ===> DETECTING ... ===> RESTORING ===> BUILDING ... ===> EXPORTING ... Successfully built image java-app:pack^
Optimize the build with:
pack build java-app:pack-compressed --env BP_JVM_JLINK_ENABLED=true
If you want to configure specific JVM settings with Paketo Buildpacks you can extend the call to use alternative configuration:
pack build -e BPE_APPEND_JAVA_TOOL_OPTIONS='-XX:+UseParallelGC -XX:MaxRAMPercentage=75' -e BPE_DELIM_JAVA_TOOL_OPTIONS=' ' java-app:packPaketo buildpacks can be configured using different for external configuration (Environment Variables, buildpack.yml, Bindings, Procfiles).
Use an environment variable to configure the JVM version installed by the Java Buildpack and build a new version of the container image
pack build java-app:pack-v2.0 --env BP_JVM_VERSION=11Observe the usage of (JDK 11.0.19, JRE 11.0.19) in the BUILDING phase of the output.
Get an overview of the built Images
docker imagesUsing pack it is possible to swap out the underlying OS layers (run image) of an app image with another run image version, without re-building the application.
Rebase app image with a version pinned run image
pack rebase java-app:pack --run-image paketobuildpacks/run:1.3.48-full-cnbShould display output like:
1.3.48-full-cnb: Pulling from paketobuildpacks/run
83525de54a98: Already exists
c1dbbbd2a415: Pull complete
283105c565ee: Pull complete
7ead7caf102c: Pull complete
Digest: sha256:005e54c4254bd49fa5b0b55fd7b7f16a2654bc6643963dece1cd03f7a0abce24
Status: Downloaded newer image for paketobuildpacks/run:1.3.48-full-cnb
Rebasing java-app:pack on run image paketobuildpacks/run:1.3.48-full-cnb
Saving java-app:pack...
*** Images (a938edc476a8):
java-app:pack
Rebased Image: a938edc476a85ab53d6aa52a5cc6288c1dffdafd9b3654236cf8b62bbce70a83
Successfully rebased image java-app:pack
For a Spring Boot application you can also invoke Paketo Buildpacks directly via maven.
./mvnw spring-boot:build-image -Dspring-boot.build-image.imageName=java-app:paketoAfter compiling and testing the code within a standard Maven build, the build-image phase appears in the build log, in which you should observe display output like:
===> DETECTING ... ===> ANALYZING ... ===> RESTORING ===> BUILDING ... ===> EXPORTING ... Successfully built image 'docker.io/library/java-app:paketo'
Get an overview of the built Images
You have now completed the core exercise. Feel free to do some modifications yourself. Suggestions: * Edit the pom.xml and alternate the Java version (8,11,17 have been tested). * Do minor or major code modifications and observe changes * Use dive to analyze the created images.
© Matthias Haeussler. Free for private purposes. (Re)distribution for commercial purposes not allowed without owner permissions.