mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-06 06:46:26 +01:00
158 lines
4.8 KiB
Plaintext
158 lines
4.8 KiB
Plaintext
// Module included in the following assemblies:
|
|
//
|
|
//* builds/build-strategies.adoc
|
|
|
|
[id="images-create-s2i-scripts_{context}"]
|
|
= Writing 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:
|
|
|
|
. A script specified in the BuildConfig
|
|
. A script found in the application source `.s2i/bin` directory
|
|
. 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
|
|
|
|
.S2I Scripts
|
|
[cols="3a,8a",options="header"]
|
|
|===
|
|
|
|
|Script |Description
|
|
|
|
|`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:
|
|
|
|
. Restore build artifacts. If you want to support incremental builds, make sure to define *_save-artifacts_* as well (optional).
|
|
. Place the application source in the desired location.
|
|
. Build the application artifacts.
|
|
. 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:
|
|
|
|
. Build the image.
|
|
. Run the image to verify the `usage` script.
|
|
. Run `s2i build` to verify the `assemble` script.
|
|
. Run `s2i build` again to verify the `save-artifacts` and `assemble` scripts save and restore artifacts functionality. (optional)
|
|
. 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:
|
|
[source,terminal]
|
|
----
|
|
#!/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:
|
|
[source,terminal]
|
|
----
|
|
#!/bin/bash
|
|
|
|
# run the application
|
|
/opt/application/run.sh
|
|
----
|
|
|
|
.`save-artifacts` script:
|
|
[source,terminal]
|
|
----
|
|
#!/bin/bash
|
|
|
|
pushd ${HOME}
|
|
if [ -d deps ]; then
|
|
# all deps contents to tar stream
|
|
tar cf - deps
|
|
fi
|
|
popd
|
|
|
|
----
|
|
|
|
|
|
.`usage` script:
|
|
[source,terminal]
|
|
----
|
|
#!/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
|
|
----
|
|
|
|
|
|
////
|
|
== Using Images with ONBUILD Instructions
|
|
The `ONBUILD` instructions can be found in many official container images. For
|
|
example:
|
|
|
|
* Ruby
|
|
* Node.js
|
|
* Python
|
|
|
|
See the link:https://docs.docker.com/engine/reference/builder/#onbuild[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.
|
|
|
|
.Additional resources
|
|
|
|
* link:https://blog.openshift.com/create-s2i-builder-image/[S2I Image Creation Tutorial]
|
|
////
|