1. Documentation
    2. history bug_report picture_as_pdf
×

Using build strategies

Docker build

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

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

Replacing Dockerfile FROM image

You can replace the FROM instruction of the Dockerfile with the from 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 of the BuildConfig.

strategy:
  dockerStrategy:
    from:
      kind: "ImageStreamTag"
      name: "debian:latest"

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

To use the dockerfilePath field for the build to use a different path to locate your Dockerfile, set:

strategy:
  dockerStrategy:
    dockerfilePath: dockerfiles/app1/Dockerfile

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.

Procedure

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.

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.

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: "foo"
      value: "bar"

Only the name and value fields are supported. Any settings on the valueFrom field are ignored.

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

Using build volumes

You can mount build volumes to give running builds access to information that you don’t 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
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 (1)
        mounts:
        - destinationPath: /opt/app-root/src/.m2  (2)
        source:
          type: ConfigMap (3)
          configMap:
            name: my-config (4)
      - name: my-csi-volume (1)
        mounts:
        - destinationPath: /opt/app-root/src/some_path  (2)
        source:
          type: CSI (3)
          csi:
            driver: csi.sharedresource.openshift.io (5)
            readOnly: true (6)
            volumeAttributes: (7)
              attribute: value
    1 Required. A unique name.
    2 Required. The absolute path of the mount point. It must not contain .. or : and doesn’t 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 Required. The type of source, ConfigMap, Secret, or CSI.
    4 Required. The name of the source.
    5 Required. The driver that provides the ephemeral CSI volume.
    6 Required. This value must be set to true. Provides a read-only volume.
    7 Optional. The volume attributes of the ephemeral CSI volume. Consult the CSI driver’s documentation for supported attribute keys and values.

The Shared Resource CSI Driver is supported as a Technology Preview feature.

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.

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.

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, 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. 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, and save-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.

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.

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.

Using source-to-image build configuration environment