Build Strategy Options - Builds | Developer Guide

Source-to-Image Strategy Options
Pipeline Strategy Options
- Providing the Jenkinsfile
- Environment Variables

The Docker build strategy is not supported in OpenShift Online.

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.

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"

The Build Environment section provides more advanced instructions.

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

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') {
          stage 'build'
          openshiftBuild(buildConfig: 'ruby-sample-build', showBuildLogs: 'true')
          stage 'deploy'
          openshiftDeploy(deploymentConfig: 'frontend')
        }

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

Environment Variables

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

Once defined, the environment variables will be set as parameters for any Jenkins job associated with the BuildConfig.

For example:

jenkinsPipelineStrategy:
...
  env:
    - name: "FOO"
      value: "BAR"

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

Mapping Between BuildConfig Environment Variables and Jenkins Job Parameters

When a Jenkins job is created or updated based on changes to a Pipeline strategy BuildConfig, any environment variables in the BuildConfig are mapped to Jenkins job parameters definitions, where the default values for the Jenkins job parameters definitions are the current values of the associated environment variables.

After the Jenkins job’s initial creation, you can still add additional parameters to the job from the Jenkins console. The parameter names differ from the names of the environment variables in the BuildConfig. The parameters are honored when builds are started for those Jenkins jobs.

How you start builds for the Jenkins job dictates how the parameters are set. If you start with oc start-build, the values of the environment variables in the BuildConfig are the parameters set for the corresponding job instance. Any changes you make to the parameters' default values from the Jenkins console are ignored. The BuildConfig values take precedence.

If you start with oc start-build -e, the values for the environment variables specified in the -e option take precedence. And if you specify an environment variable not listed in the BuildConfig, they will be added as a Jenkins job parameter definitions. Also any changes you make from the Jenkins console to the parameters corresponding to the environment variables are ignored. The BuildConfig and what you specify with oc start-build -e takes precedence.

If you start the Jenkins job via the Jenkins console, then you can control the setting of the parameters via the Jenkins console as part of starting a build for the job.

Specifying all possible environment variables and job parameters in the BuildConfig reduces disk I/O and improves performance during Jenkins processing.