4.3. Creating images from source code with source-to-image

Source-to-image (S2I) is a framework that makes it easy to write images that take application source code as an input and produce a new image that runs the assembled application as output.

The main advantage of using S2I for building reproducible container images is the ease of use for developers. As a builder image author, you must understand two basic concepts in order for your images to provide the best S2I performance, the build process and S2I scripts.

4.3.1. Understanding the source-to-image build process

The build process consists of the following three fundamental elements, which are combined into a final container image:

  • Sources
  • Source-to-image (S2I) scripts
  • Builder image

S2I generates a Dockerfile with the builder image as the first FROM instruction. The Dockerfile generated by S2I is then passed to Buildah.

4.3.2. How to write source-to-image scripts

You can write source-to-image (S2I) scripts in any programming language, as long as the scripts are executable inside the builder image. S2I supports multiple options providing assemble/run/save-artifacts scripts. All of these locations are checked on each build in the following order:

  1. A script specified in the build configuration.
  2. A script found in the application source .s2i/bin directory.
  3. A script found at the default image URL with the io.openshift.s2i.scripts-url label.

Both the io.openshift.s2i.scripts-url label specified in the image and the script specified in a build configuration can take one of the following forms:

  • image:///path_to_scripts_dir: absolute path inside the image to a directory where the S2I scripts are located.
  • file:///path_to_scripts_dir: relative or absolute path to a directory on the host where the S2I scripts are located.
  • http(s)://path_to_scripts_dir: URL to a directory where the S2I scripts are located.

表 4.2. S2I scripts

ScriptDescription

assemble

The assemble script builds the application artifacts from a source and places them into appropriate directories inside the image. This script is required. The workflow for this script is:

  1. Optional: Restore build artifacts. If you want to support incremental builds, make sure to define save-artifacts as well.
  2. Place the application source in the desired location.
  3. Build the application artifacts.
  4. Install the artifacts into locations appropriate for them to run.

run

The run script executes your application. This script is required.

save-artifacts

The save-artifacts script gathers all dependencies that can speed up the build processes that follow. This script is optional. For example:

  • For Ruby, gems installed by Bundler.
  • For Java, .m2 contents.

These dependencies are gathered into a tar file and streamed to the standard output.

usage

The usage script allows you to inform the user how to properly use your image. This script is optional.

test/run

The test/run script allows you to create a process to check if the image is working correctly. This script is optional. The proposed flow of that process is:

  1. Build the image.
  2. Run the image to verify the usage script.
  3. Run s2i build to verify the assemble script.
  4. Optional: Run s2i build again to verify the save-artifacts and assemble scripts save and restore artifacts functionality.
  5. Run the image to verify the test application is working.
注意

The suggested location to put the test application built by your test/run script is the test/test-app directory in your image repository.

Example S2I scripts

The following example S2I scripts are written in Bash. Each example assumes its tar contents are unpacked into the /tmp/s2i directory.

assemble script:

#!/bin/bash

# restore build artifacts
if [ "$(ls /tmp/s2i/artifacts/ 2>/dev/null)" ]; then
    mv /tmp/s2i/artifacts/* $HOME/.
fi

# move the application source
mv /tmp/s2i/src $HOME/src

# build application artifacts
pushd ${HOME}
make all

# install the artifacts
make install
popd

run script:

#!/bin/bash

# run the application
/opt/application/run.sh

save-artifacts script:

#!/bin/bash

pushd ${HOME}
if [ -d deps ]; then
    # all deps contents to tar stream
    tar cf - deps
fi
popd

usage script:

#!/bin/bash

# inform the user how to use the image
cat <<EOF
This is a S2I sample builder image, to use it, install
https://github.com/openshift/source-to-image
EOF

Additional resources