Chapter 5. Using build strategies

The following sections define the primary supported build strategies, and how to use them.

5.1. Docker build

Red Hat OpenShift Service on AWS uses Buildah to build a container image from a Dockerfile. For more information on building container images with Dockerfiles, see the Dockerfile reference documentation.

Tip

If you set Docker build arguments by using the buildArgs array, see Understand how ARG and FROM interact in the Dockerfile reference documentation.

5.1.1. Replacing the Dockerfile FROM image

You can replace the FROM instruction of the Dockerfile with the from parameters of the BuildConfig object. If the Dockerfile uses multi-stage builds, the image in the last FROM instruction will be replaced.

Procedure

To replace the FROM instruction of the Dockerfile with the from parameters of the BuildConfig object, add the following settings to the BuildConfig object:
```
strategy:
  dockerStrategy:
    from:
      kind: "ImageStreamTag"
      name: "debian:latest"
```

5.1.2. Using Dockerfile path

By default, docker builds use a Dockerfile located at the root of the context specified in the BuildConfig.spec.source.contextDir field.

The dockerfilePath field allows the build to use a different path to locate your Dockerfile, relative to the BuildConfig.spec.source.contextDir field. It can be a different file name than the default Dockerfile, such as MyDockerfile, or a path to a Dockerfile in a subdirectory, such as dockerfiles/app1/Dockerfile.

Procedure

Set the dockerfilePath field for the build to use a different path to locate your Dockerfile:
```
strategy:
  dockerStrategy:
    dockerfilePath: dockerfiles/app1/Dockerfile
```

5.1.3. Using docker environment variables

To make environment variables available to the docker build process and resulting image, you can add environment variables to the dockerStrategy definition of the build configuration.

The environment variables defined there are inserted as a single ENV Dockerfile instruction right after the FROM instruction, so that it can be referenced later on within the Dockerfile.

The variables are defined during build and stay in the output image, therefore they will be present in any container that runs that image as well.

For example, defining a custom HTTP proxy to be used during build and runtime:

dockerStrategy:
...
  env:
    - name: "HTTP_PROXY"
      value: "http://myproxy.net:5187/"

You can also manage environment variables defined in the build configuration with the oc set env command.

5.1.4. Adding Docker build arguments

You can set Docker build arguments using the buildArgs array. The build arguments are passed to Docker when a build is started.

Tip

See Understand how ARG and FROM interact in the Dockerfile reference documentation.

Procedure

To set Docker build arguments, add entries to the buildArgs array, which is located in the dockerStrategy definition of the BuildConfig object. For example:
```
dockerStrategy:
...
  buildArgs:
    - name: "version"
      value: "latest"
```
Note
Only the name and value fields are supported. Any settings on the valueFrom field are ignored.

5.1.5. Squashing layers with docker builds

Docker builds normally create a layer representing each instruction in a Dockerfile. Setting the imageOptimizationPolicy to SkipLayers merges all instructions into a single layer on top of the base image.

Procedure

Set the imageOptimizationPolicy to SkipLayers:

strategy:
  dockerStrategy:
    imageOptimizationPolicy: SkipLayers

5.1.6. Using build volumes

You can mount build volumes to give running builds access to information that you do not want to persist in the output container image.

Build volumes provide sensitive information, such as repository credentials, that the build environment or configuration only needs at build time. Build volumes are different from build inputs, whose data can persist in the output container image.

The mount points of build volumes, from which the running build reads data, are functionally similar to pod volume mounts.

Prerequisites

You have added an input secret, config map, or both to a BuildConfig object.

Procedure

In the dockerStrategy definition of the BuildConfig object, add any build volumes to the volumes array. For example:

spec:
  dockerStrategy:
    volumes:
      - name: secret-mvn 1
        mounts:
        - destinationPath: /opt/app-root/src/.ssh 2
        source:
          type: Secret 3
          secret:
            secretName: my-secret 4
      - name: settings-mvn 5
        mounts:
        - destinationPath: /opt/app-root/src/.m2  6
        source:
          type: ConfigMap 7
          configMap:
            name: my-config 8

1 5: Required. A unique name.
2 6: Required. The absolute path of the mount point. It must not contain .. or : and does not collide with the destination path generated by the builder. The /opt/app-root/src is the default home directory for many Red Hat S2I-enabled images.
3 7: Required. The type of source, ConfigMap, Secret, or CSI.
4 8: Required. The name of the source.

Additional resources

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-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, complete one of the following actions:
- Provide an assemble, run, or save-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 in the BuildConfig object. For example:
```
strategy:
  sourceStrategy:
    from:
      kind: "ImageStreamTag"
      name: "builder-image:latest"
    scripts: "http://somehost.com/scripts_directory" 1
```
  1
  The build process appends run, assemble, and save-artifacts to the path. If any or all scripts with these names exist, the build process uses these scripts in place of scripts with the same name that are provided in the image.
  Note
  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. The variables that you provide using either method 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.

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

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/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.

Table 5.1. S2I scripts
Script	Description
`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: Optional: Restore build artifacts. If you want to support incremental builds, make sure to define `save-artifacts` as well. Place the application source in the desired location. Build the application artifacts. 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: Build the image. Run the image to verify the `usage` script. Run `s2i build` to verify the `assemble` script. Optional: Run `s2i build` again to verify the `save-artifacts` and `assemble` scripts save and restore artifacts functionality. Run the image to verify the test application is working. 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.

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

S2I Image Creation Tutorial

5.2.6. Using build volumes

You can mount build volumes to give running builds access to information that you do not want to persist in the output container image.

The mount points of build volumes, from which the running build reads data, are functionally similar to pod volume mounts.

Prerequisites

You have added an input secret, config map, or both to a BuildConfig object.

Procedure

In the sourceStrategy definition of the BuildConfig object, add any build volumes to the volumes array. For example:

spec:
  sourceStrategy:
    volumes:
      - name: secret-mvn 1
        mounts:
        - destinationPath: /opt/app-root/src/.ssh 2
        source:
          type: Secret 3
          secret:
            secretName: my-secret 4
      - name: settings-mvn 5
        mounts:
        - destinationPath: /opt/app-root/src/.m2 6
        source:
          type: ConfigMap 7
          configMap:
            name: my-config 8

1 5: Required. A unique name.
2 6: Required. The absolute path of the mount point. It must not contain .. or : and does not collide with the destination path generated by the builder. The /opt/app-root/src is the default home directory for many Red Hat S2I-enabled images.
3 7: Required. The type of source, ConfigMap, Secret, or CSI.
4 8: Required. The name of the source.

Additional resources

5.3. Adding secrets with web console

You can add a secret to your build configuration so that it can access a private repository.

Procedure

To add a secret to your build configuration so that it can access a private repository from the Red Hat OpenShift Service on AWS web console:

Create a new Red Hat OpenShift Service on AWS project.
Create a secret that contains credentials for accessing a private source code repository.
Create a build configuration.
On the build configuration editor page or in the create app from builder image page of the web console, set the Source Secret.
Click Save.

5.4. Enabling pulling and pushing

You can enable pulling to a private registry by setting the pull secret and pushing by setting the push secret in the build configuration.

Procedure

To enable pulling to a private registry:

Set the pull secret in the build configuration.

To enable pushing:

Set the push secret in the build configuration.

Chapter 5. Using build strategies

5.1. Docker build

5.1.1. Replacing the Dockerfile FROM image

5.1.2. Using Dockerfile path

5.1.3. Using docker environment variables

5.1.4. Adding Docker build arguments

5.1.5. Squashing layers with docker builds

5.1.6. Using build volumes

5.2. Source-to-image build

5.2.1. Performing source-to-image incremental builds

5.2.2. Overriding source-to-image builder image scripts

5.2.3. Source-to-image environment variables

5.2.3.1. Using source-to-image environment files

5.2.3.2. Using source-to-image build configuration environment

5.2.4. Ignoring source-to-image source files

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

5.2.5.1. Understanding the source-to-image build process

5.2.5.2. How to write source-to-image scripts

5.2.6. Using build volumes

5.3. Adding secrets with web console

5.4. Enabling pulling and pushing

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links