Lab - Source-to-Image (S2I)
Last updated
Last updated
This project contains a Source-to-Image (S2I) builder image and a S2I runtime image which creates an image running Java web applications on Open Liberty.
Source-to-Image (S2I) is an open source toolkit for building reproducible container images from source code. S2I produces ready-to-run images by injecting source code into a container image.
The Open Liberty builder in this lab can be used in two different environments:
Local Docker runtime via 's2i',
Deployment to OpenShift'.
With interpreted languages like python and javascript, the runtime container is also the build container. For example, with a node.js application the 'npm install' is run to build the application and then 'npm start' is run in the same container in order to start the application.
However, with compiled languages like Java, the build and runtime processes can be separated. This will allow for slimmer runtime containers for faster application starts and less bloat in the application image.
This lab will focus on the second scenario of using a builder image along with a runtime image.
(source: https://github.com/openshift/source-to-image/blob/master/docs/runtime_image.md)
The following prerequisites are needed:
Have followed these steps to get a cluster
You can stop after step 11
For this lab you need to use a docker-in-docker environment so that you can build Docker images. You can use a web-terminal assigned to you for the workshop or you can use the labs client of IBM Skills Network.
Follow the instructions here to create your client environment.
Clone this repository locally and navigate to the newly cloned directory.
To install Source to Image. Run the following commands
To make things easier, we are going to set some environment variables that we can reuse in later commands.
Note: Replace Your Username with your actual docker hub username. If you do not have one, go here to create one.
Your root folder should be set to the root of the cloned repository, e.g. /root/s2i-open-liberty-workshop,
In this section we will create the first of our two S2I images. This image will be responsible for taking in our source code and building the application binary with Maven.
Navigate to the builder image directory
Review the ./Dockerfile
The image uses a Redhat certified Universal Base Image (UBI) from the public container registry at Redhat,
You can customize the builder image further, e.g. change the LABEL for maintainer to your name,
Now build the builder image.
Note: Don't miss the . for the current directory at the end of the docker build command,
Log in to your Dockerhub account. After running the below command, you will be asked to enter your docker password.
Push the builder image out to Docker hub.
With that done, you can now build your runtime image.
In this section you will create the second of our two S2I images. The runtime image will be responsible for taking the compiled binary from the builder image and serving it with the Open Liberty application server.
Navigate to the runtime image directory
Review the ./Dockerfile
Build the runtime image
Note: Don't miss the . for the current directory at the end of the docker build command,
Push the runtime image to Docker hub.
Now we are ready to build our application with S2I.
In this section, we will use S2I to build our application container image and then we will run the image locally using Docker.
Use the builder image and runtime image to build the application image
Run a multistage S2I build, to build the application.
Let's break down the above command:
s2i build . - Use s2i build in the current directory to build the Docker image by combining the builder image and sources
$DOCKER_USERNAME/s2i-open-liberty-builder:0.1.0 - This is the builder image used to build the application
authors - name of our application image
--runtime-image $DOCKER_USERNAME/s2i-open-liberty:0.1.0 - Take the output of the builder image and run it in this container.
-a /tmp/src/target -a /tmp/src/server.xml - The runtime-artifact flag specifies a file or directory to be copies from builder to runtime image. The runtime-artifact is where the builder output is located. These files will be passed into the runtime image.
Run the newly built image to start the application on your local machine in the background,
Check the container is running successfully,
Retrieve the authors using curl,
In the following steps we will be using two deployment strategies:
deploy as a traditional Kubernetes Deployment, and
build and deployment using templates, OpenShift BuildConfig, and DeploymentConfig.
Now that we have the application running locally and have verified that it works, let's deploy it to an OpenShift environment.
Log in with your OpenShift Cluster.
In preparation of this lab, you claimed a cluster that was created for you, and which is now available via your IBM Cloud dashboard,
Browse to your assigned OpenShift cluster Overview page,
From the top right, open your OpenShift web console
In the OpenShift Web Console, from the profile dropdown click Copy Login Command.
Paste the login command to login, e.g.
For this method, we will deploy our application by creating a kubernetes deployment along with a service and a route.
Tag the image that was created in the previous section.
Push the image that we built locally using s2i to the OpenShift image registry.
Go back to the root folder,
Review the application.yaml file,
This command will add your newly pushed authors image to the deployment yaml file.
Apply the application.yaml file using the oc cli to create our Deployment, Service, and Route.
Now let's visit the deployed application. Run the following to get the route to access the application.
Copy and paste the output of the previous command to set a variable $APP_URL,
Test the application using curl
Or use the route to your app and paste it into your web browser and add the following to the end of the route:
So your route should appear like the following but without the (...):
It sometimes takes a minute to fully deploy so if you get a message about the application not being available, try again.
For this section, you will explore how to build and deploy our application using OpenShift concepts known as templates, build configs and deployment configs. With build configs, the s2i builds are actually happening on the cluster rather than locally.
Create a push secret to push the application image to your DockerHub account.
You must modify the following command by replacing \ with your DockerHub password and \ with your email address for DockerHub.
With the secret created we can now give the builder service account access to the secret so that it can push the newly created application image to your account.
Then, we need to create a builder template that contains our builder image build config. See Using Templates.
Review the buildTemplate.yaml file, which contains the BuildConfig object for the builder image,
Next, let's create the build config and start the first build:
This command will not only create our build config but also kick off the first build to create our builder image and push it to DockerHub.
To view the status of the build you can run:
Or view the Build section of the OpenShift console.
Now let's take a look at our runtime image build config:
Then, create the build config for our runtime image and start the first build:
To take a look at the build status, run:
Or view the Build section of the OpenShift console.
Now with our builds run, we can deploy our application. Previously we used a kubernetes deployment object to do this however this time we will use an OpenShift deployment configuration.
Both objects are similar and will accomplish the same goals however with deployment configs you have greater control of your application's deployment behavior. You also have the option to set automated triggers to kick off builds and deploys based on image, configuration, or git repository changes. Due to a limitation in our workshop environment, we will not be exploring triggers and utilizing image streams with the integrated OpenShift registry, however, if you would like to take a look at a template that automates the entire build and deploy process with triggers, check out the this example template found in the workshop repo.
Let's check out the deployment config template:
Then, create the deploymentConfig
To verify that your app is deployed, run:
You should see a pod named authors2-1- followed by 5 random characters, in the example below they are x58fk. This is the application pod.
You can also view these on the OpenShift dashboard if you navigate to Workloads > Pods and look for your new pod. Make sure you are in your personal project and not in default. The pod name should start with authors2-.
Once you have verified that the new pod is running, enter the following command to view the application routes.
Copy the route named authors2 and add it to the end of the command below.
View the sample below, however, you will have a different route.
Then test your application with the command below:
You should then get a response back from the application that we just deployed:
In this optional section we will create our own copy of the code push the changes to OpenShift.
First we need to create your own version of the code repo by creating a fork. This will copy the repo into your GitHub account. Navigate to the lab repo at https://github.com/IBM/s2i-open-liberty-workshop and click on the Fork button in the upper right of the page.
When the repo is done forking, click on the green Clone or download button and copy your git repo url.
To make it easier, create an environment variable to hold your repo url. Copy the following command and replace <repo url> with your actual repo url:
Then, in your terminal, navigate to the $HOME directory to clone your repo locally and run the following commands:
Now that we have our own copy, let's push a change and test it out. From your browser, navigate to the GitHub repo that you forked. Click on the Branch dropdown and select conference.
Then navigate to the file at web-app/src/main/java/com/ibm/authors/GetAuthor.java
Click on the pencil icon in the upper right of the code to enter editing mode.
On lines 56-59 edit the name, twitter, and blog to your own information or fake information if you'd like.
Scroll down and click on Commit changes.
With the changes pushed, we can now rebuild and redeploy the application. Follow the following steps:
Build the builder image:
Ensure that the previous build is finished, then start the runtime build:
Ensure that the runtime image build is finished, then deploy the app with the following command:
Once you have verified that the application is deployed and the new pod is running, enter the following command to view the application routes.
Copy the route named authors-3 and add it to the end of the command below.
View the sample below, however, you will have a different route.
Then test your application with the command below:
You should then see the info that you edited in the file earlier.
In this lab we have explored building our own custom s2i images for building containerized application from source code. We utilized a multi stage s2i process that separated the build environment from the runtime environment which allowed for us to have a slimmer application image. Then, we deployed the application as a traditional Kubernetes deployment. Lastly, we explored how to build and deploy the application using templates, OpenShift build configs, and deployment configs.
Go back to the Summary.
