Build Strategy Options - Builds | Developer Guide | OpenShift Container Platform 3.5

Source-to-Image Strategy Options

The following options are specific to the S2I build strategy.

Force Pull

By default, if the builder image specified in the build configuration is available locally on the node, that image will be used. However, to override the local image and refresh it from the registry to which the image stream points, create a BuildConfig with the forcePull flag set to true:

strategy:
  sourceStrategy:
    from:
      kind: "ImageStreamTag"
      name: "builder-image:latest" (1)
    forcePull: true (2)

1	The builder image being used, where the local version on the node may not be up to date with the version in the registry to which the image stream points.
2	This flag causes the local builder image to be ignored and a fresh version to be pulled from the registry to which the image stream points. Setting `forcePull` to false results in the default behavior of honoring the image stored locally.

Incremental Builds

S2I can perform incremental builds, which means it reuses artifacts from previously-built images. To create an incremental build, create a BuildConfig 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.

See the S2I Requirements topic for information on how to create a builder image supporting incremental builds.

Extended Builds

This feature is in technology preview. This means the API may change without notice or the feature may be removed entirely. For a supported mechanism to produce application images with runtime-only content, consider using the Image Source feature and defining two builds, one which produces an image containing the runtime artifacts and a second build which consumes the runtime artifacts from that image and adds them to a runtime-only image.

For compiled languages (Go, C, C++, Java, etc.) the dependencies necessary for compilation might increase the size of the image or introduce vulnerabilities that can be exploited.

To avoid these problems, S2I (Source-to-Image) introduces a two-image build process that allows an application to be built via the normal flow in a builder image, but then injects the resulting application artifacts into a runtime-only image for execution.

To offer flexibility in this process, S2I executes an assemble-runtime script inside the runtime image that allows further customization of the resulting runtime image.

More information about this can be found in the official S2I extended builds documents.

This feature is available only for the source strategy.

strategy:
  type: "Source"
  sourceStrategy:
    from:
      kind: "ImageStreamTag"
      name: "builder-image:latest"
    runtimeImage: (1)
      kind: "ImageStreamTag"
      name: "runtime-image:latest"
    runtimeArtifacts: (2)
      - sourcePath: "/path/to/source"
        destinationDir: "path/to/destination"

1	The runtime image that the artifacts should be copied to. This is the final image that the application will run on. This image should contain the minimum application dependencies to run the injected content from the builder image.
2	The runtime artifacts are a mapping of artifacts produced in the builder image that should be injected into the runtime image. `sourcePath` can be the full path to a file or directory inside the builder image. `destinationDir` must be a directory inside the runtime image where the artifacts will be copied. This directory is relative to the specified WORKDIR inside that image.

In the current implementation, you cannot have incremental extended builds thus, the incremental option is not valid with runtimeImage.

If the runtime image needs authentication to be pulled across OpenShift projects or from another private registry, the details can be specified within the image pull secret configuration.

Testing your Application

Extended builds offer two ways of running tests against your application.

The first option is to install all test dependencies and run the tests inside your builder image since that image, in the context of extended builds, will not be pushed to a registry. This can be done as a part of the assemble script for the builder image.

The second option is to specify a script via the postcommit hook. This is executed in an ephemeral container based on the runtime image, thus it is not committed to the image.

Overriding Builder Image Scripts

You can override the assemble, run, and save-artifacts S2I scripts provided by the builder image in one of two ways. Either:

Provide an assemble, run, and/or save-artifacts script in the .s2i/bin directory of your application source repository, or
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 script(s) provided in the image.

Files located at the scripts URL take precedence over files located in .s2i/bin of the source repository. See the S2I Requirements topic and the S2I documentation for information on how S2I scripts are used.

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.

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. The complete list of supported environment variables is available in the documentation for each image.

If you provide a .s2i/environment file in your source repository, S2I reads this file during the build. This allows customization of the build behavior as the assemble script may use these variables.

For example, if you want to disable assets compilation for your Rails application, you can add DISABLE_ASSET_COMPILATION=true in the .s2i/environment file to cause assets compilation to be skipped during the build.

In addition to builds, the specified environment variables are also available in the running application itself. For example, you can add RAILS_ENV=development to the .s2i/environment file to cause the Rails application to start in development mode instead of production.

BuildConfig Environment

You can add environment variables to the sourceStrategy definition of the BuildConfig. 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.

For example disabling assets compilation for your Rails application:

sourceStrategy:
...
  env:
    - name: "DISABLE_ASSET_COMPILATION"
      value: "true"

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

Adding Secrets via Web Console

To add a secret to your build configuration so that it can access a private repository:

Create a new OpenShift Container Platform project.
Create a secret that contains credentials for accessing a private source code repository.
Create a Source-to-Image (S2I) 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 the Save button.

Enabling Pulling and Pushing

Enable pulling to a private registry by setting the Pull Secret in the build configuration and enable pushing by setting the Push Secret.

Ignoring Source Files

Source to image 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.

For more details on the format of the .s2iignore file, see the source-to-image documentation.

Docker Strategy Options

The following options are specific to the Docker build strategy.

FROM Image

The FROM instruction of the Dockerfile will be replaced by the from of the BuildConfig:

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

Dockerfile Path

By default, Docker builds use a Dockerfile (named 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 simply a different file name other than the default Dockerfile (for example, MyDockerfile), or a path to a Dockerfile in a subdirectory (for example, dockerfiles/app1/Dockerfile):

strategy:
  dockerStrategy:
    dockerfilePath: dockerfiles/app1/Dockerfile

No Cache

Docker builds normally reuse cached layers found on the host performing the build. Setting the noCache option to true forces the build to ignore cached layers and rerun all steps of the Dockerfile:

strategy:
  dockerStrategy:
    noCache: true

Force Pull

strategy:
  dockerStrategy:
    forcePull: true (1)

1	This flag causes the local builder image to be ignored, and a fresh version to be pulled from the registry to which the image stream points. Setting `forcePull` to false results in the default behavior of honoring the image stored locally.

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

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

Cluster administrators can also configure global build settings using Ansible.

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

Adding Secrets via Web Console

To add a secret to your build configuration so that it can access a private repository"

Create a new OpenShift Container Platform project.
Create a secret that contains credentials for accessing a private source code repository.
Create a docker build configuration.
On the build configuration editor page or in the fromimage page of the web console, set the Source Secret.
Click the Save button.

Enabling Pulling and Pushing

Enable pulling to a private registry by setting the Pull Secret in the build configuration and enable pushing by setting the Push Secret.

Custom Strategy Options

The following options are specific to the Custom build strategy.

FROM Image

Use the customStrategy.from section to indicate the image to use for the custom build:

strategy:
  customStrategy:
    from:
      kind: "DockerImage"
      name: "openshift/sti-image-builder"

Exposing the Docker Socket

In order to allow the running of Docker commands and the building of container images from inside the container, the build container must be bound to an accessible socket. To do so, set the exposeDockerSocket option to true:

strategy:
  customStrategy:
    exposeDockerSocket: true

Secrets

In addition to secrets for source and images that can be added to all build types, custom strategies allow adding an arbitrary list of secrets to the builder pod.

Each secret can be mounted at a specific location:

strategy:
  customStrategy:
    secrets:
      - secretSource: (1)
          name: "secret1"
        mountPath: "/tmp/secret1" (2)
      - secretSource:
          name: "secret2"
        mountPath: "/tmp/secret2"

1	`secretSource` is a reference to a secret in the same namespace as the build.
2	`mountPath` is the path inside the custom builder where the secret should be mounted.

Adding Secrets via Web Console

To add a secret to your build configuration so that it can access a private repository:

Create a new OpenShift Container Platform project.
Create a secret that contains credentials for accessing a private source code repository.
Create a custom build configuration.
On the build configuration editor page or in the fromimage page of the web console, set the Source Secret.
Click the Save button.

Enabling Pulling and Pushing

Enable pulling to a private registry by setting the Pull Secret in the build configuration and enable pushing by setting the Push Secret.

Force Pull

By default, when setting up the build pod, the build controller checks if the image specified in the build configuration is available locally on the node. If so, that image will be used. However, to override the local image and refresh it from the registry to which the image stream points, create a BuildConfig with the forcePull flag set to true:

strategy:
  customStrategy:
    forcePull: true (1)

1	This flag causes the local builder image to be ignored, and a fresh version to be pulled from the registry to which the image stream points. Setting `forcePull` to false results in the default behavior of honoring the image stored locally.

Environment Variables

To make environment variables available to the Custom build process, you can add environment variables to the customStrategy definition of the BuildConfig.

The environment variables defined there are passed to the pod that runs the custom build.

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

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

Cluster administrators can also configure global build settings using Ansible.

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

Pipeline Strategy Options

The following options are specific to the Pipeline build strategy.

Providing the Jenkinsfile

You can provide the Jenkinsfile in one of two ways:

Embed the Jenkinsfile in the build configuration.
Include in the build configuration a reference to the Git repository that contains the Jenkinsfile.

Embedded Definition

kind: "BuildConfig"
apiVersion: "v1"
metadata:
  name: "sample-pipeline"
spec:
  strategy:
    jenkinsPipelineStrategy:
      jenkinsfile: "node('agent') {\nstage 'build'\nopenshiftBuild(buildConfig: 'ruby-sample-build', showBuildLogs: 'true')\nstage 'deploy'\nopenshiftDeploy(deploymentConfig: 'frontend')\n}"

Reference to Git Repository

kind: "BuildConfig"
apiVersion: "v1"
metadata:
  name: "sample-pipeline"
spec:
  source:
    git:
      uri: "https://github.com/openshift/ruby-hello-world"
  strategy:
    jenkinsPipelineStrategy:
      jenkinsfilePath: some/repo/dir/filename (1)

1	The optional `jenkinsfilePath` field specifies the name of the file to use, relative to the source `contextDir`. If `contextDir` is omitted, it defaults to the root of the repository. If `jenkinsfilePath` is omitted, it defaults to *Jenkinsfile*.