검색

이 콘텐츠는 선택한 언어로 제공되지 않습니다.

Chapter 4. S2I Requirements

download PDF

4.1. Overview

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 possible S2I performance: the build process and S2I scripts.

4.2. Build Process

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

  • sources
  • S2I scripts
  • builder image

During the build process, S2I must place sources and scripts inside the builder image. To do so, S2I creates a tar file that contains the sources and scripts, then streams that file into the builder image. Before executing the assemble script, S2I untars that file and places its contents into the location specified by the io.openshift.s2i.destination label from the builder image, with the default location being the /tmp directory.

For this process to happen, your image must supply the tar archiving utility (the tar command available in $PATH) and the command line interpreter (the /bin/sh command); this allows your image to use the fastest possible build path. If the tar or /bin/sh command is not available, the s2i build process is forced to automatically perform an additional container build to put both the sources and the scripts inside the image, and only then run the usual build.

See the following diagram for the basic S2I build workflow:

Figure 4.1. Build Workflow

S2I workflow
  • Run build’s responsibility is to untar the sources, scripts and artifacts (if such exist) and invoke the assemble script. If this is the second run (after catching tar or /bin/sh not found error) it is responsible only for invoking assemble script, since both scripts and sources are already there.

4.3. S2I Scripts

You can write 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 BuildConfig
  2. A script found in the application source .s2i/bin directory
  3. A script found at the default image URL (io.openshift.s2i.scripts-url label)

Both the io.openshift.s2i.scripts-url label specified in the image and the script specified in a BuildConfig 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
Table 4.1. S2I Scripts
ScriptDescription

assemble (required)

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

  1. Restore build artifacts. If you want to support incremental builds, make sure to define save-artifacts as well (optional).
  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 (required)

The run script executes your application.

save-artifacts (optional)

The save-artifacts script gathers all dependencies that can speed up the build processes that follow. 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 (optional)

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

test/run (optional)

The test/run script allows you to create a simple process to check if the image is working correctly. 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. Run s2i build again to verify the save-artifacts and assemble scripts save and restore artifacts functionality. (optional)
  5. Run the image to verify the test application is working.

See the Testing S2I Images topic for more information.

Note

The suggested location to put the test application built by your test/run script is the test/test-app directory in your image repository. See the S2I documentation for more information.

Example S2I Scripts

Note

The following examples are written in Bash and it is assumed all tar contents are unpacked into the /tmp/s2i directory.

Example 4.1. 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

Example 4.2. run script:

#!/bin/bash

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

Example 4.3. save-artifacts script:

#!/bin/bash

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

Example 4.4. 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

4.4. Using Images with ONBUILD Instructions

The ONBUILD instructions can be found in many official container images. For example:

  • Ruby
  • Node.js
  • Python

See the Docker documentation for more information on ONBUILD.

Upon startup, S2I detects whether the builder image contains sh and tar binaries which are necessary for the S2I process to inject build inputs. If the builder image does not contain these prerequisites, it will attempt to instead perform a container build to layer the inputs. If the builder image includes ONBUILD instructions, S2I will instead fail the build because the ONBUILD instructions would be executed during the layering process, and that equates to performing a generic container build which is less secure than an S2I build and requires explicit permissions.

Therefore you should ensure that your S2I builder image either does not contain ONBUILD instructions, or ensure that it has the necessary sh and tar binary prerequisites.

4.5. External References

Red Hat logoGithubRedditYoutubeTwitter

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

Red Hat을 사용하는 고객은 신뢰할 수 있는 콘텐츠가 포함된 제품과 서비스를 통해 혁신하고 목표를 달성할 수 있습니다.

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat은 코드, 문서, 웹 속성에서 문제가 있는 언어를 교체하기 위해 최선을 다하고 있습니다. 자세한 내용은 다음을 참조하세요.Red Hat 블로그.

Red Hat 소개

Red Hat은 기업이 핵심 데이터 센터에서 네트워크 에지에 이르기까지 플랫폼과 환경 전반에서 더 쉽게 작업할 수 있도록 강화된 솔루션을 제공합니다.

© 2024 Red Hat, Inc.