Builds | Developer Guide | OpenShift Enterprise 3.0

Overview

A build is a process of creating runnable images to be used on OpenShift. There are three build strategies:

Source-To-Image (S2I) (description, options)
Docker (description, options)
Custom (description, options)

Defining a BuildConfig

A build configuration describes a single build definition and a set of triggers for when a new build should be created.

A build configuration is defined by a BuildConfig, which is a REST object that can be used in a POST to the API server to create a new instance. The following example BuildConfig results in a new build every time a Docker image tag or the source code changes:

Example 1. BuildConfig Object Definition

{
  "kind": "BuildConfig",
    "apiVersion": "v1",
    "metadata": {
      "name": "ruby-sample-build" (1)
    },
  "spec": {
    "triggers": [ (2)
      {
        "type": "GitHub",
        "github": {
          "secret": "secret101"
        }
      },
      {
        "type": "Generic",
        "generic": {
          "secret": "secret101"
        }
      },
      {
        "type": "ImageChange"
      }
    ],
    "source": { (3)
      "type": "Git",
      "git": {
        "uri": "https://github.com/openshift/ruby-hello-world"
      }
    },
    "strategy": { (4)
      "type": "Source",
      "sourceStrategy": {
        "from": {
          "kind": "ImageStreamTag",
          "name": "ruby-20-centos7:latest"
        }
      }
    },
    "output": { (5)
      "to": {
        "kind": "ImageStreamTag",
        "name": "origin-ruby-sample:latest"
      }
    }
  }
}

1	This specification will create a new `BuildConfig` named ruby-sample-build.
2	You can specify a list of triggers, which cause a new build to be created.
3	The `source` section defines the source code repository location. You can provide additional options, such as `sourcesecret` or `contextDir` here.
4	The `strategy` section describes the build strategy used to execute the build. You can specify `Source`, `Docker` and `Custom` strategies here. This above example uses the `ruby-20-centos7` Docker image that Source-To-Image will use for the application build.
5	After the Docker image is successfully built, it will be pushed into the repository described in the `output` section.

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": {
    "type": "Source",
    "sourceStrategy": {
      "from": {
        "kind": "ImageStreamTag",bas
        "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": {
    "type": "Source",
    "sourceStrategy": {
      "from": {
        "kind": "ImageStreamTag",
        "name": "incremental-image:latest" (1)
      },
      "incremental": true (2)
    }
  }
}

1	Specify an image that supports incremental builds. The S2I images provided by OpenShift do not implement artifact reuse, so setting `incremental` to true will have no effect on builds using those builder images.
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.

Override 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 .sti/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": {
    "type": "Source",
    "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 .sti/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.

Environment Files

Source build enables you to set environment values (one per line) inside your application, by specifying them in a .sti/environment file in the source repository. The environment variables specified in this file are present during the build process and in the final Docker image. The complete list of supported environment variables is available in the documentation for each image.

If you provide a .sti/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 .sti/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 .sti/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"
      }
    ]
  }
}

Docker Strategy Options

The following options are specific to the Docker build strategy.

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:
  type: "Docker"
  dockerStrategy:
    noCache: true

Force Pull

{
  "strategy": {
    "type": "Docker",
    "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/"
      }
    ]
  }
}

Custom Strategy Options

The following options are specific to the Custom build strategy.

Exposing the Docker Socket

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

{
  "strategy": {
    "type": "Custom",
    "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": {
    "type": "Custom",
    "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.

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": {
    "type": "Custom",
    "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/"
      }
    ]
  }
}

Using a Proxy for Git Cloning

If your Git repository can only be accessed using a proxy, you can define the proxy to use in the source section of the BuildConfig. You can configure both a HTTP and HTTPS proxy to use. Both fields are optional.

Your source URI must use the HTTP or HTTPS protocol for this to work.

...
source:
  type: Git
  git:
    uri: "https://github.com/openshift/ruby-hello-world"
    httpProxy: http://proxy.example.com
    httpsProxy: https://proxy.example.com
...

Using Private Repositories for Builds

Supply valid credentials to build an application from a private repository. Currently, only SSH key based authentication is supported. The repository keys are located in the $HOME/.ssh/ directory, and are named id_dsa.pub, id_ecdsa.pub, id_ed25519.pub, or id_rsa.pub by default. Generate SSH key credentials with the following command:

$ ssh-keygen -t rsa -C "your_email@example.com"

For a SSH key to work in OpenShift builds, it must not have a passphrase set. When prompted for a passphrase, leave it blank.

Two files are created: the public key and a corresponding private key (one of id_dsa, id_ecdsa, id_ed25519, or id_rsa). With both of these in place, consult your source control management (SCM) system’s manual on how to upload the public key. The private key will be used to access your private repository.

A secret is used to store your keys.

Create the secret first before using the SSH key to access the private repository:
$ oc secrets new scmsecret ssh-privatekey=$HOME/.ssh/id_rsa
Add the secret to the builder service account. Each build is run with serviceaccount/builder role, so you need to give it access your secret with following command:
$ oc secrets add serviceaccount/builder secrets/sshsecret

Add a sourcesecret field into the source section inside the BuildConfig and set it to the name of the secret that you created. In this case scmsecret:

apiVersion: "v1"
kind: "BuildConfig"
metadata:
  name: "sample-build"
spec:
  output:
    to:
      kind: "ImageStreamTag"
      name: "sample-image:latest"
  source:
    git:
      uri: "git@repository.com:user/app.git" (1)
    sourcesecret:
      name: "scmsecret"
    type: "Git"
  strategy:
    sourceStrategy:
      from:
        kind: "ImageStreamTag"
        name: "python-33-centos7:latest"
    type: "Source"

1	The URL of private repository is usually in the form `git@example.com:<username>/<repository>`.

Dockerfile Source

When the BuildConfig.spec.source.type is Dockerfile, an inline Dockerfile is used as the build input, and no additional sources can be provided.

This source type is valid when the build strategy type is Docker or Custom.

The source definition is part of the spec section in the BuildConfig:

source:
  type: "Dockerfile"
  dockerfile: "FROM centos:7\nRUN yum install -y httpd" (1)

1	The `dockerfile` field contains an inline Dockerfile that will be built.

Binary Source

When the BuildConfig.spec.source.type is Binary, the build will expect a binary as input, and an inline Dockerfile is optional.

The binary is generally assumed to be a tar, gzipped tar, or zip file depending on the strategy. For Docker builds, this is the build context and an optional Dockerfile may be specified to override any Dockerfile in the build context. For Source builds, this is assumed to be an archive as described above. For Source and Docker builds, if binary.asFile is set the build will receive a directory with a single file. The contextDir field may be used when an archive is provided. Custom builds will receive this binary as input on standard input (stdin).

A binary source potentially extracts content, in which case contextDir allows changing to a subdirectory within the content before the build executes.

The source definition is part of the spec section in the BuildConfig:

source:
  type: "Binary"
  binary: (1)
    asFile: "webapp.war" (2)
  contextDir: "app/dir" (3)
  dockerfile: "FROM centos:7\nRUN yum install -y httpd" (4)

1	The `binary` field specifies the details of the binary source.
2	The `asFile` field specifies the name of a file that will be created with the binary contents.
3	The `contextDir` field specifies a subdirectory with the contents of a binary archive.
4	If the optional `dockerfile` field is provided, it should be a string containing an inline Dockerfile that potentially replaces one within the contents of the binary archive.

Image Source

Additional files can be provided to the build process via images. Input images are referenced in the same way the From and To image targets are defined. This means both docker images and image stream tags can be referenced. In conjunction with the image, you must provide one or more path pairs to indicate the path of the files/directories to copy out of the image and the destination to place them in the build context.

The source path can be any absolute path within the image specified. The destination must be a relative directory path. At build time, the image will be loaded and the indicated files/directories will be copied into the context directory of the build process. This is the same directory into which the source repository content (if any) is cloned.

Image inputs are specified in the source definition of the BuildConfig:

source:
  git:
    uri: https://github.com/openshift/ruby-hello-world.git
  images: (1)
  - from: (2)
      kind: ImageStreamTag
      name: myinputimage:latest
      namespace: mynamespace
    paths: (3)
    - destinationDir: injected/dir (4)
      sourcePath: /usr/lib/somefile.jar (5)
  - from:
      kind: ImageStreamTag
      name: myotherinputimage:latest
      namespace: myothernamespace
    pullsecret: mysecret (6)
    paths:
    - destinationDir: injected/dir
      sourcePath: /usr/lib/somefile.jar

1	An array of one or more input images and files.
2	A reference to the image containing the files to be copied.
3	An array of source/destination paths.
4	The directory relative to the build root where the build process can access the file.
5	The location of the file to be copied out of the referenced image.
6	An optional secret provided if credentials are needed to access the input image.

This feature is not supported for builds using the Custom strategy.

Using secrets During a Build

In some scenarios operations performed by the build require credentials to access dependent resources, but it is undesirable for those credentials to be available in the final application image produced by the build.

For example, you are building a NodeJS application and you set up your private mirror for NodeJS modules. In order to download modules from that private mirror, you have to supply a custom .npmrc file for the build that contains a URL, username and password. For security reasons, you do not want to expose your credentials in the application image.

While this example describes NodeJS, you can use the same approach for adding SSL certificates into the /etc/ssl/certs directory, API keys or tokens, license files, etc.

Defining secrets in the BuildConfig

First, you have to create the secret you want to use. You can do that by executing the following command:

$ oc secrets new secret-npmrc .npmrc=~/.npmrc

This command will create a new secret named secret-npmrc and store the base64 encoded content of the ~/.npmrc file in it.

Now, that you have the secret created, you can add references to secrets into the source section in the existing BuildConfig:

source:
  git:
    uri: https://github.com/openshift/nodejs-ex.git
  secrets:
    secret:
      name: secret-npmrc
  type: Git

If you want to create a new BuildConfig and you want to include the secrets in it, you can run the following command:

$ oc new-build openshift/nodejs-010-centos7~https://github.com/openshift/nodejs-ex.git --build-secret secret-npmrc

During the build in both of these examples the .npmrc will be copied into a directory where the source code is located. In case of the OpenShift Source-To-Image builder images, this will be the image working directory which is set using the WORKDIR instruction in the Dockerfile. If you want to specify another directory, you can add a destinationDir into the secret definition:

source:
  git:
    uri: https://github.com/openshift/nodejs-ex.git
  secrets:
    secret:
      name: secret-npmrc
    destinationDir: /etc
  type: Git

You can also specify the destination directory when creating a new BuildConfig:

$ oc new-build openshift/nodejs-010-centos7~https://github.com/openshift/nodejs-ex.git --build-secret “secret-npmrc:/etc”

In both cases, the .npmrc file will be added into the /etc directory of the build environment. Note that for a Docker strategy the destination directory must be a relative path.

Source-to-Image Strategy

When you are using a Source strategy all defined source secrets will be copied to the respective destinationDir. If you left destinationDir empty then the secrets will be placed to the working directory of the builder image. The same rule is used when a destination directory is a relative path - the secrets will be placed into the paths that are relative to the image’s working directory. The destinationDir must exist or an error will occur. No directory paths are created during the copy process.

Keep in mind that in the current implementation, files with the secrets are world-writable (have 0666 permissions) and will be truncated to size zero after execution of the assemble script. This means that the secret files will exist in the resulting image but they will be empty for security reasons.

Docker Strategy

When you are using a Docker strategy, you can add all defined source secrets into your Docker image using the ADD and COPY instructions in your Dockerfile. If you don’t specify the destinationDir for a secret, then the files will be copied into the same directory in which the Dockerfile is located. If you specify a relative path as destinationDir, then the secrets will be copied into that directory, relative to your Dockerfile location. This makes the secret files available to the Docker build operation as part of the context directory used during the build.

Note that for security reasons, users should always remove their secrets from the final application image. This removal should be part of the Dockerfile itself. In that case, the secrets will not be present in the container running from that image. However, the secrets will still exist in the image itself in the layer where they were added.

Custom Strategy

When you are using a Custom strategy, then all the defined source secrets will be available inside the builder container under /var/run/secrets/openshift.io/build directory. It is the custom build image’s responsibility to use these secrets appropriately. The Custom strategy also allows secrets to be defined as described in secrets. There is no technical difference between existing strategy secrets and the source secrets. However, your builder image might distinguish between them and use them differently, based on your build use case. The source secrets are always mounted into /var/run/secrets/openshift.io/build directory or your builder can parse the $BUILD environment variable which includes the full Build object serialized into JSON format.

Starting a Build

Manually invoke a build using the following command:

$ oc start-build <BuildConfigName>

Re-run a build using the --from-build flag:

$ oc start-build --from-build=<buildName>

Specify the --follow flag to stream the build’s logs in stdout:

$ oc start-build <BuildConfigName> --follow

Canceling a Build

Manually cancel a build using the following command:

$ oc cancel-build <buildName>

Accessing Build Logs

To allow access to build logs, use the following command:

$ oc build-logs <buildName>

Log Verbosity

To enable more verbose output, pass the BUILD_LOGLEVEL environment variable as part of the sourceStrategy or dockerStrategy in a BuildConfig:

{
  "sourceStrategy": {
    ...
    "env": [
      {
        "name": "BUILD_LOGLEVEL",
        "value": "2" (1)
      }
    ]
  }
}

1	Adjust this value to the desired log level.

A platform administrator can set verbosity for the entire OpenShift instance by passing the --loglevel option to the openshift start command. If both --loglevel and BUILD_LOGLEVEL are specified, BUILD_LOGLEVEL takes precedence.

Available log levels for Source builds are as follows:

Level 0	Produces output from containers running the *assemble* script and all encountered errors. This is the default.
Level 1	Produces basic information about the executed process.
Level 2	Produces very detailed information about the executed process.
Level 3	Produces very detailed information about the executed process, and a listing of the archive contents.
Level 4	Currently produces the same information as level 3.
Level 5	Produces everything mentioned on previous levels and additionally provides docker push messages.

Source Code

The source code location is one of the required parameters for the BuildConfig. The build uses this location and fetches the source code that is later built. The source code location definition is part of the spec section in the BuildConfig:

{
  "source" : {
    "type" : "Git", (1)
    "git" : { (2)
      "uri": "https://github.com/openshift/ruby-hello-world"
    },
    "contextDir": "app/dir", (3)
  },
}

1	The `type` field describes which SCM is used to fetch your source code.
2	The `git` field contains the URI to the remote Git repository of the source code. Optionally, specify the `ref` field to check out a specific Git reference. A valid `ref` can be a SHA1 tag or a branch name.
3	The `contextDir` field allows you to override the default location inside the source code repository where the build looks for the application source code. If your application exists inside a sub-directory, you can override the default location (the root folder) using this field.

Build Triggers

When defining a BuildConfig, you can define triggers to control the circumstances in which the BuildConfig should be run. The following build triggers are available:

Webhook
Image change
Configuration change

Webhook Triggers

Webhook triggers allow you to trigger a new build by sending a request to the OpenShift API endpoint. You can define these triggers using GitHub webhooks or Generic webhooks.

GitHub Webhooks

GitHub webhooks handle the call made by GitHub when a repository is updated. When defining the trigger, you must specify a secret as part of the URL you supply to GitHub when configuring the webhook. The secret ensures that only you and your repository can trigger the build. The following example is a trigger definition JSON within the BuildConfig:

{
  "type": "GitHub",
  "github": {
    "secret": "secret101"
  }
}

The payload URL is returned as the GitHub Webhook URL by the describe command (see below), and is structured as follows:

http://<openshift_api_host:port>/osapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github

Generic Webhooks

Generic webhooks can be invoked from any system capable of making a web request. As with a GitHub webhook, you must specify a secret when defining the trigger, and the caller must provide this secret to trigger the build. The following is an example trigger definition JSON within the BuildConfig:

{
  "type": "Generic",
  "generic": {
    "secret": "secret101"
  }
}

To set up the caller, supply the calling system with the URL of the generic webhook endpoint for your build:

http://<openshift_api_host:port>/osapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic

The endpoint can accept an optional payload with the following format:

{
  type: 'git',
  git: {
    uri: '<url to git repository>',
    ref: '<optional git reference>',
    commit: '<commit hash identifying a specific git commit>',
    author: {
      name: '<author name>',
      email: '<author e-mail>',
    },
    committer: {
      name: '<committer name>',
      email: '<committer e-mail>',
    },
    message: '<commit message>'
  }
}

Displaying a BuildConfig’s Webhook URLs

Use the following command to display the webhook URLs associated with a build configuration:

$ oc describe bc <name>

If the above command does not display any webhook URLs, then no webhook trigger is defined for that build configuration.

Image Change Triggers

Image change triggers allow your build to be automatically invoked when a new version of an upstream image is available. For example, if a build is based on top of a RHEL image, then you can trigger that build to run any time the RHEL image changes. As a result, the application image is always running on the latest RHEL base image.

Configuring an image change trigger requires the following actions:

Define an ImageStream that points to the upstream image you want to trigger on:
{ "kind": "ImageStream", "apiVersion": "v1", "metadata": { "name": "ruby-20-centos7" } }
This defines the image stream that is tied to a Docker image repository located at <system-registry>/<namespace>/ruby-20-centos7. The <system-registry> is defined as a service with the name docker-registry running in OpenShift.
If an image stream is the base image for the build, set the from field in the build strategy to point to the image stream:
{ "strategy": { "type": "Source", "sourceStrategy": { "from": { "kind": "ImageStreamTag", "name": "ruby-20-centos7:latest" }, } } }
In this case, the sourceStrategy definition is consuming the latest tag of the image stream named ruby-20-centos7 located within this namespace.

Define a build with one or more triggers that point to image streams:

{
  "type": "imageChange", (1)
  "imageChange": {}
}
{
  "type": "imagechange", (2)
  "imageChange": {
     "from": {
       "kind": "ImageStreamTag",
       "name": "custom-image:latest"
     }
  }
}

1	An image change trigger that monitors the `ImageStream` and `Tag` as defined by the build strategy’s `from` field. The `imageChange` part must be empty.
2	An image change trigger that monitors an arbitrary image stream. The `imageChange` part in this case must include a `from` field that references the `ImageStreamTag` to monitor.

When using an image change trigger for the strategy image stream, the generated build is supplied with an immutable Docker tag that points to the latest image corresponding to that tag. This new image reference will be used by the strategy when it executes for the build. For other image change triggers that do not reference the strategy image stream, a new build will be started, but the build strategy will not be updated with a unique image reference.

In the example above that has an image change trigger for the strategy, the resulting build will be:

{
  "strategy": {
    "type": "Source",
    "sourceStrategy": {
      "from": {
        "kind": "DockerImage",
        "name": "172.30.17.3:5001/mynamespace/ruby-20-centos7:immutableid"
      }
    }
  }
}

This ensures that the triggered build uses the new image that was just pushed to the repository, and the build can be re-run any time with the same inputs.

In addition to setting the image field for all Strategy types, for custom builds, the OPENSHIFT_CUSTOM_BUILD_BASE_IMAGE environment variable is checked. If it does not exist, then it is created with the immutable image reference. If it does exist then it is updated with the immutable image reference.

If a build is triggered due to a webhook trigger or manual request, the build that is created uses the immutableid resolved from the ImageStream referenced by the Strategy. This ensures that builds are performed using consistent image tags for ease of reproduction.

Image streams that point to Docker images in v1 Docker registries only trigger a build once when the image stream tag becomes available and not on subsequent image updates. This is due to the lack of uniquely identifiable images in v1 Docker registries.

Configuration Change Triggers

A configuration change trigger allows a build to be automatically invoked as soon as a new BuildConfig is created. The following is an example trigger definition JSON within the BuildConfig:

{
  "type": "ConfigChange"
}

Configuration change triggers currently only work when creating a new BuildConfig. In a future release, configuration change triggers will also be able to launch a build whenever a BuildConfig is updated.

Using Docker Credentials for Pushing and Pulling Images

Supply the .dockercfg file with valid Docker Registry credentials in order to push the output image into a private Docker Registry or pull the builder image from the private Docker Registry that requires authentication. For the OpenShift Docker Registry, you don’t have to do this because secrets are generated automatically for you by OpenShift.

The .dockercfg JSON file is found in your home directory by default and has the following format:

{
	"https://index.docker.io/v1/": { (1)
		"auth": "YWRfbGzhcGU6R2labnRib21ifTE=", (2)
		"email": "user@example.com" (3)
	}
}

1	URL of the registry.
2	Encrypted password.
3	Email address for the login.

You can define multiple Docker registry entries in this file. Alternatively, you can also add authentication entries to this file by running the docker login command. The file will be created if it does not exist. Kubernetes provides secret, which are used to store your configuration and passwords.

Create the secret from your local .dockercfg file:
$ oc secrets new dockerhub ~/.dockercfg
This generates a JSON specification of the secret named dockerhub and creates the object.
Once the secret is created, add it to the builder service account:
$ oc secrets add serviceaccount/builder secrets/dockerhub

Add a pushsecret field into the output section of the BuildConfig and set it to the name of the secret that you created, which in the above example is dockerhub:

{
  "spec": {
    "output": {
      "to": {
        "name": "private-image"
      },
      "pushsecret":{
        "name": "dockerhub"
      }
    }
  }
}

Pull the builder Docker image from a private Docker registry by specifying the pullsecret field, which is part of the build strategy definition:

{
  "strategy": {
    "sourceStrategy": {
      "from": {
        "kind": "DockerImage",
        "name": "docker.io/user/private_repository"
       },
       "pullsecret": {
        "name": "dockerhub"
       },
    },
    "type": "Source"
  }
}