5.2. Source-to-image build
Source-to-image (S2I) is a tool for building reproducible container images. It produces ready-to-run images by injecting application source into a container image and assembling a new image. The new image incorporates the base image, the builder, and built source and is ready to use with the buildah run command. S2I supports incremental builds, which re-use previously downloaded dependencies, previously built artifacts, and so on.
5.2.1. Performing source-to-image incremental builds
Source-to-image (S2I) can perform incremental builds, which means it reuses artifacts from previously-built images.
Procedure
To create an incremental build, create a with the following modification to the strategy definition:
strategy: sourceStrategy: from: kind: "ImageStreamTag" name: "incremental-image:latest" 1 incremental: true 2- 1
- Specify an image that supports incremental builds. Consult the documentation of the builder image to determine if it supports this behavior.
- 2
- This flag controls whether an incremental build is attempted. If the builder image does not support incremental builds, the build will still succeed, but you will get a log message stating the incremental build was not successful because of a missing
save-artifactsscript.
Additional resources
- See S2I Requirements for information on how to create a builder image supporting incremental builds.
5.2.2. Overriding source-to-image builder image scripts
You can override the assemble, run, and save-artifacts source-to-image (S2I) scripts provided by the builder image.
Procedure
To override the assemble, run, and save-artifacts S2I scripts provided by the builder image, either:
-
Provide an
assemble,run, orsave-artifactsscript in the.s2i/bindirectory of your application source repository. Provide a URL of a directory containing the scripts as part of the strategy definition. For example:
strategy: sourceStrategy: from: kind: "ImageStreamTag" name: "builder-image:latest" scripts: "http://somehost.com/scripts_directory" 1- 1
- This path will have
run,assemble, andsave-artifactsappended to it. If any or all scripts are found they will be used in place of the same named scripts provided in the image.
Files located at the scripts URL take precedence over files located in .s2i/bin of the source repository.
5.2.3. Source-to-image environment variables
There are two ways to make environment variables available to the source build process and resulting image. Environment files and BuildConfig environment values. Variables provided will be present during the build process and in the output image.
5.2.3.1. Using source-to-image environment files
Source build enables you to set environment values, one per line, inside your application, by specifying them in a .s2i/environment file in the source repository. The environment variables specified in this file are present during the build process and in the output image.
If you provide a .s2i/environment file in your source repository, source-to-image (S2I) reads this file during the build. This allows customization of the build behavior as the assemble script may use these variables.
Procedure
For example, to disable assets compilation for your Rails application during the build:
-
Add
DISABLE_ASSET_COMPILATION=truein the.s2i/environmentfile.
In addition to builds, the specified environment variables are also available in the running application itself. For example, to cause the Rails application to start in development mode instead of production:
-
Add
RAILS_ENV=developmentto the.s2i/environmentfile.
The complete list of supported environment variables is available in the using images section for each image.
5.2.3.2. Using source-to-image build configuration environment
You can add environment variables to the sourceStrategy definition of the build configuration. The environment variables defined there are visible during the assemble script execution and will be defined in the output image, making them also available to the run script and application code.
Procedure
For example, to disable assets compilation for your Rails application:
sourceStrategy: ... env: - name: "DISABLE_ASSET_COMPILATION" value: "true"
Additional resources
- The build environment section provides more advanced instructions.
-
You can also manage environment variables defined in the build configuration with the
oc set envcommand.
5.2.4. Ignoring source-to-image source files
Source-to-image (S2I) supports a .s2iignore file, which contains a list of file patterns that should be ignored. Files in the build working directory, as provided by the various input sources, that match a pattern found in the .s2iignore file will not be made available to the assemble script.
5.2.5. 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.
5.2.5.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.
5.2.5.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:
- A script specified in the build configuration.
-
A script found in the application source
.s2i/bindirectory. -
A script found at the default image URL with the
io.openshift.s2i.scripts-urllabel.
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.
| Script | Description |
|---|---|
|
|
The
|
|
|
The |
|
|
The
These dependencies are gathered into a |
|
|
The |
|
|
The
注意
The suggested location to put the test application built by your |
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
