Skip to content

Open Liberty Devfile Stack Customization

Jump to bottom
Edward Mezarina edited this page Nov 15, 2021 · 4 revisions

This sample shows how to customize the default Open Liberty Stack to meet your Java and/or Open Liberty version requirements. You can follow this same process to customize the default WebSphere Liberty stack by simply using the build-wl.env file rather than the build-ol.env file.

Procedure

Building a Custom Open Liberty Devfile Stack Base Image

  1. Clone the Open Liberty Devfile Stack repository.
git clone https://github.com/OpenLiberty/devfile-stack.git
  1. Go into the devfile-stack directory.
cd devfile-stack
  1. Persist your customization.

There are different ways to persist your customization. Here, we explore the option of persisting the customized Open Liberty devfile stack in a branch off of your cloned Open Liberty devfile stack main branch, and the generated artifacts are stored in a git release.

  • Create a branch.
git checkout -b custom-stack-ol210010-java8
  1. Customize the Open Liberty devfile stack base image.
  • Review build-ol.env. (For the WebSphere Liberty stack, use build-wl.env)

Review the default customization variable values defined in build.sh as they may already match your target values.

The following customization variables are provided:

STACK_NAME: The name of this stack.

STACK_SHORT_NAME: The short name for this stack (one word / lowercase).

LIBERTY_RUNTIME_VERSION: The custom Open Liberty version you intend to use.

LIBERTY_RUNTIME_ARTIFACTID: The custom Open Liberty runtime artifact id you intend to use. See here.

LIBERTY_RUNTIME_GROUPID: The custom Open Liberty runtime group id you intend to use. See here.

WLP_INSTALL_PATH: The path where Liberty is installed in the stack image. This value is also used in the outer loop Dockerfile as the Liberty installation path in the official Liberty images. It is not recommended to change this.

BASE_OS_IMAGE: The custom Semeru UBI image you intend to use as base to build your custom Open Liberty devfile stack image. Semeru UBI images can be found here.

STACK_IMAGE_MAVEN: The custom Open Liberty base maven image name you will be creating next. This image is used to create your inner loop development containers through the devfile.yaml provided by the Open Liberty Stack. You can use image with name:tag that contains the {{liberty-version}} entry or not. If you do, the {{liberty-version}} variable is automatically set to the value of LIBERTY_RUNTIME_VERSION.

STACK_IMAGE_GRADLE: The custom Open Liberty base gradle image name you will be creating next. This image is used to create your inner loop development containers through the devfile.yaml provided by the Open Liberty Stack. You can use image with name:tag that contains the {{liberty-version}} entry or not. If you do, the {{liberty-version}} variable is automatically set to the value of LIBERTY_RUNTIME_VERSION.

OUTERLOOP_STACK_IMAGE_MAVEN: The custom Open Liberty base maven image name. This image will used as the base image for the first stage of your outer loop image build. You can use image with name:tag that contains the ${LIBERTY_VERSION} entry or not. If you do, the ${LIBERTY_VERSION} variable is automatically set to the value of LIBERTY_RUNTIME_VERSION. Note that this image should be the same as the image set in STACK_IMAGE_GRADLE after the resolution of any set variables.

OUTERLOOP_STACK_IMAGE_GRADLE: The custom Open Liberty base maven image name. This image will used as the base image for the first stage of your outer loop image build. You can use image with name:tag that contains the ${LIBERTY_VERSION} entry or not. If you do, the ${LIBERTY_VERSION} variable is automatically set to the value of LIBERTY_RUNTIME_VERSION. Note that this image should be the same as the image set in STACK_IMAGE_GRADLE after the resolution of any set variables.

OUTERLOOP_LIBERTY_IMAGE: The custom UBI Open Liberty image matching your choice of Open Liberty driver and Java versions. This image is used for outer loop application deployment. If you use the ${LIBERTY_VERSION} variable in the tag, that variable is automatically set to the value of LIBERTY_RUNTIME_VERSION. Open Liberty images can be found here.

OUTERLOOP_DOCKERFILE_MAVEN_LOC: The remote URL path where the maven based outer-loop Dockerfile will be persisted. This location is used for outer loop application deployment within devfile.yaml.

OUTERLOOP_DOCKERFILE_GRADLE_LOC: The remote URL path where the gradle based outer-loop Dockerfile will be persisted. This location is used for outer loop application deployment within devfile.yaml.

LIBERTY_PLUGIN_VERSION: The version of the Liberty Maven plugin to use in the stack.

Note:

For the purpose of this example, the outer loop Dockerfiles will be persisted into repository releases. Therefore, the value of OUTERLOOP_DOCKERFILE_MAVEN_LOC will look like this: https://<your-git-repo-path>/devfile-stack/releases/download/<your-expected-maven-release-name>/Dockerfile. Where <your-expected-release-name>. Similarly, the value of OUTERLOOP_DOCKERFILE_MAVEN_LOC will look like this: https://<your-git-repo-path>/devfile-stack/releases/download/<your-expected-gradle-release-name>/Dockerfile. Where <your-expected-maven-release-name> and <your-expected-gradle-release-name> are the names of the releases you will create later on to persist your customization artifacts. Save the names.

Save STACK_IMAGE name you chose. It will also be used later on.

  • Load variables and run build.sh.

You can run build.sh with the target customization values as inputs or you can update the build-ol.env file itself if you intend to persist the customization values and run the script with no inputs. For the purpose of this example, we will update the script.

Examples:

  • Using customization arguments:
source build-ol.env \
LIBERTY_RUNTIME_VERSION=21.0.0.10 \
. ./build.sh
  • Updating default values in build-ol.env:
vi build-ol.env

...
BASE_OS_IMAGE="ibmsemeruruntime/open-8-jdk:ubi-jdk-latest"
LIBERTY_RUNTIME_VERSION="21.0.0.10"
STACK_IMAGE_MAVEN="<my-repo>/<image-maven>:\{\{liberty-version\}\}"
STACK_IMAGE_GRADLE="<my-repo>/<image-gradle>:\{\{liberty-version\}\}-gradle"
OUTERLOOP_STACK_IMAGE_MAVEN="<my-repo>/<image-maven>:\$\{LIBERTY_VERSION\}"
OUTERLOOP_STACK_IMAGE_GRADLE="<my-repo>/<image-gradle>:\$\{LIBERTY_VERSION\}-gradle"
OUTERLOOP_LIBERTY_IMAGE="openliberty/open-liberty:\$\{LIBERTY_VERSION\}-full-java8-openj9-ubi"
OUTERLOOP_DOCKERFILE_MAVEN_LOC="https://<your-git-repo-path>/devfile-stack/releases/download/custom-maven-ol210010-java8/Dockerfile"
OUTERLOOP_DOCKERFILE_GRADLE_LOC="https://<your-git-repo-path>/devfile-stack/releases/download/custom-gradle-ol210010-java8/Dockerfile"
...

source build-ol.env
. ./build.sh

The build.sh script will produce a set of artifacts with your target customization values. The artifacts are located in a directory called: generated. This directory is an output directory and not part of the devfile-stack repository content.

  1. Consider updating the source and target compatibility entries in the build configuration files for both Maven and Gradle.

Maven:

vi stackimage/priming-app/pom.xml

Update:

<maven.compiler.target>8</maven.compiler.target>
<maven.compiler.source>8</maven.compiler.source>

Gradle:

vi stackimage/priming-app/build.gradle

Update:

sourceCompatibility = 8
targetCompatibility = 8
  1. Build your customized Open Liberty devfile stack base images.

Maven:

docker build -t <value of STACK_IMAGE_MAVEN in build.sh> -f generated/stackimage/maven/Dockerfile stackimage

Gradle:

docker build -t <value of STACK_IMAGE_GRADLE in build.sh> -f generated/stackimage/gradle/Dockerfile stackimage
  1. Push your custom OpenLiberty devfile stack images to an accessible repository.

Maven:

docker push <value of STACK_IMAGE_MAVEN in build.sh>

Gradle:

docker push <value of STACK_IMAGE_GRADLE in build.sh>
  1. Persist your customized Open Liberty devfile stack.
  • Add, commit, and push the updates to the branch created for this customization.

Example:

git add <files>
git commit -m 'Customized OL Stack using Java 8 with OpenJ9 and OpenLiberty 21.0.0.10'
git push
  • Create git releases.

For the purpose of this example, we will store the maven and gradle artifacts separately in two different releases.

Maven release custom-maven-ol210010-java8 (<your-expected-maven-release-name>):

Upload the following assets:

- generated/devfiles/maven/devfile.yaml
- generated/outer-loop/maven/Dockerfile

Gradle release custom-gradle-ol210010-java8 (<your-expected-gradle-release-name>):

Upload the following assets:

- generated/devfiles/gradle/devfile.yaml
- generated/outer-loop/gradle/Dockerfile

At this point you are done customizing the stack.

Running an Application Using the Customized Stack

The following steps show how to deploy your application using the Open Liberty devfile stack that you just customized.

  1. Login to your Kubernetes cluster.
oc login https://<your_cluster_hostname> -u <username> -p <password>
  1. Deploy your application for inner loop development.
If your application supports both Maven and Gradle, you can validate both by executing the steps below twice. Follow either the Maven or Gradle instructions below for each iteration.
  • Clone your application repository.

For this example, we will use the Open Liberty devfile stack intro located here. It supports both Maven and Gradle.

git clone https://github.com/OpenLiberty/devfile-stack-intro.git
  • cd into the devfile-stack-intro directory
cd devfile-stack-intro
  • Consider updating the source and target compatibility entries in the build configuration file.

Maven:

vi pom.xml

Update:

<maven.compiler.target>8</maven.compiler.target>
<maven.compiler.source>8</maven.compiler.source>

Gradle (build.gradle)

vi build.gradle

Update:

sourceCompatibility = 8
targetCompatibility = 8
  • Create the application component. This is done by using the custom devfile-stack devfile.yaml file that was uploaded to the release that was previously created.

Maven:

odo create mavenCustomizationSample --devfile https://<your-git-repo-path>/devfile-stack/releases/download/custom-maven-ol210010-java8/devfile.yaml

odo push

Gradle:

odo create gradleCustomizationSample --devfile https://<your-git-repo-path>/devfile-stack/releases/download/custom-gradle-ol210010-java8/devfile.yaml

odo push
  1. Validate that the maven and gradle built applications were deployed successfully.
odo url list

Maven:

Output:

Found the following URLs for component mavencustomizationsample
NAME     STATE      URL                                                                      PORT     SECURE     KIND
ep1      Pushed     http://ep1-mavencustomizationsample-test.apps.xxxxxxx.yy.zzz.aaa.com     9080     false      route

Open a browser using the shown HOST/PORT: http://ep1-mavenCustomizationSample-custom.apps.xxxxxxx.yy.zzz.aaa.com/. You should see a welcome page with the heading:

Welcome to your Open Liberty Microservice built with Odo

Gradle:

Output:

Found the following URLs for component gradleCustomizationSample
NAME     STATE      URL                                                                      PORT     SECURE     KIND
ep1      Pushed     http://ep1-gradleCustomizationSample-test.apps.xxxxxxx.yy.zzz.aaa.com     9080     false      route

Open a browser using the shown HOST/PORT: http://ep1-gradleCustomizationSample-custom.apps.xxxxxxx.yy.zzz.aaa.com/. You should see a welcome page with the heading:

Welcome to your Open Liberty Microservice built with Odo

Clone this wiki locally