Lab - Source to Image
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 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:
Clone this repository locally and navigate to the newly cloned directory.
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.
Log in with your OpenShift Cluster.
Open your OpenShift web console and from the profile dropdown Copy Login Command.
Paste the login command to login, e.g.
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.
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
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,
Retrieve the authors using curl,
Or open up your browser and navigate to http://localhost:9080/openapi/ui to view your deployed microservice.
In the following labs we will be using two deployment strategies:
manually deploy as a traditional Kubernetes Deployment, and
automatic build and deployment using OpenShift BuildConfig and DeploymentConfig.
Both ways are very similar, the main difference being that with OpenShift BuildConfig and DeploymentConfig we can set triggers to automatically build the application when a new image tag has been pushed to the internal registry.
Now that we have the application running locally and have verified that it works, let's deploy it to an OpenShift environment.
In order to deploy to OpenShift, we need to push our images to your cluster's internal registry. First, run the following commands to authenticate with your OpenShift image registry.
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,
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.
You should now see the OpenAPI documentation for the getAuthor endpoint of your microservice.
For this section, you will explore how to automate our application build and deploy using OpenShift concepts known as build config and deployment config. With build configs, the s2i builds are actually happening on the cluster rather than locally.
Tag our builder and runtime images for OpenShift registry.
Push the images to the registry.
We are almost ready to deploy our application but first we need to create an application template that contains all the components of our application. See Using Templates.
Review the template.yaml file, which contains the BuildConfig object and the DeploymentConfig object as well as the other application objects,
The template file that we will apply, creates the following Kubernetes objects:
Template,
4 ImageStream objects: authors-builder, authors-runtime, s2i-open-liberty-builder, s2i-open-liberty
2 BuildConfig objects: the open-liberty-builder produces a authors-builder:0.1.0 from s2i-open-liberty-builder:0.1.0; and the open-liberty-app produces an authors-runtime:0.1.0 from s2i-open-liberty:0.1.0. The former build config is for the builder image and the latter is for the runtime image.
DeploymentConfig for authors-runtime:0.1.0 to manage the application Pods and ReplicationController,
Service, and
Route.
Lastly, we can use the oc cli to deploy the application while using the template that was just created.
After running the command you may see a message that says Failed however this is because the build has not yet completed.
If you log into your OpenShift console and navigate to Builds > Builds you should see your builds running.
Or list all builds,
Describe the build to review the status,
Once those builds complete a replication controller will be created that manages the application pods. Navigate to Workloads > Pods and look for your new pod. It should start with authors-.
Once you have verified that the new pod is running, enter the following command to view the application routes.
Use the route named authors2 and append /openapi/ui after the HOST/PORT value to open the UI, or append /api/v1/getauthor to set the API_URL. View the sample below, however, you will have a different route.
Then test your application with the command below:
In this optional section we will explore the option of configuring a webhook that will automatically notify OpenShift of a git push and will kick off the build and deploy process.
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/odrodrig/s2i-open-liberty 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.
Then, in your terminal, navigate to a directory where you'd like to clone your repo locally and run the following command while substituting repo_url with the url you copied in the previous step:
First let's delete the application that we deployed earlier. Run the following script:
Then run the following command to redeploy the application, this time we will specify to point to your newly created repo. Replace \ with the url to the GitHub repo that you copied earlier.
Now you should see some output of the components that have been created as well as a section labled With parameters:
Copy the GitHub Webhook Secret into a text document and save it for later.
In your terminal run the following command to get the webhook endpoint:
Look for the section labeled Webhook GitHub. It should look like the example below.
Replace the \ portion from the url copied in the previous step with the secret you copied earlier.
Then, in your browser, navigate to your git repo and find the Settings tab.
From the project settings select Webhooks on the left side of the page and click on new webhook.
In the payload url field, enter the webhook url that you copied earlier with the included secret.
For the content type, select application/json
Then, click Add webhook
You should now see a webhook listed in the project settings. Ensure that the webhook has a green checkmark next to it. If there is a red X, try creating the webhook again.
Now that the webhook is configured, let's push a change and test it out. From your code editor of choice, navigate to the repo that you cloned and open web-app/src/main/java/com/ibm/authors/GetAuthor.java
On lines 56-59 edit the name, twitter, and blog to your own information or fake information if you'd like.
Save the file.
From your terminal and within your cloned repo run the following commands after replacing the email address and name with your own information. This is the email address used to sign into github.
With the changes pushed, we can now go to the OpenShift dashboard and view the builds that have been kicked by the GitHub webhook.
In your browser, go back into your OpenShift console and navigate to Builds > Builds and you should see your builds running.
After the builds are completed, navigate to Workloads > Pods and look for your new pod. It should start with authors-3.
Once you have verified that the new pod is running, enter the following command to view the application routes.
Use the route named authors-3 and append /openapi/ui after the HOST/PORT value to open the UI, or append /api/v1/getauthor to set the API_URL. 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 automate the building and deploying of the application using OpenShift build and deployment configs.
