This documentation is for a release that is no longer maintained
See documentation for the latest supported version 3 or the latest supported version 4.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:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 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-artifacts
script.
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-artifacts
script in the.s2i/bin
directory of your application source repository. Provide a URL of a directory containing the scripts as part of the strategy definition. For example:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 1
- This path will have
run
,assemble
, andsave-artifacts
appended 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=true
in the.s2i/environment
file.
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=development
to the.s2i/environment
file.
The complete list of supported environment variables is available in the using images section for each image.
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"
sourceStrategy: ... env: - name: "DISABLE_ASSET_COMPILATION" value: "true"
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
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 env
command.
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.
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/bin
directory. -
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.
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:
run
script:
run the application
#!/bin/bash
# run the application
/opt/application/run.sh
save-artifacts
script:
usage
script:
Additional resources