이 콘텐츠는 선택한 언어로 제공되지 않습니다.
Chapter 9. Builds
9.1. Overview
A build is the process of transforming input parameters into a resulting object. Most often, the process is used to transform source code into a runnable image.
Build configurations are characterized by a strategy and one or more sources. The strategy determines the aforementioned process, while the sources provide its input.
There are three build strategies:
- Source-To-Image (S2I) (description, options)
- Docker (description, options)
- Custom (description, options)
And there are three types of build source:
It is up to each build strategy to consider or ignore a certain type of source, as well as to determine how it is to be used.
Binary and Git are mutually exclusive source types, while Dockerfile can be used by itself or together with Git and Binary.
9.2. 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 9.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" dockerfile: "FROM openshift/ruby-22-centos7\nUSER example" 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 of the build. The source type determines the primary source of input, and can be eitherGit
, to point to a code repository location,Dockerfile
, to build from an inline Dockerfile, orBinary
, to accept binary payloads. It is possible to have multiple sources at once, refer to the documentation for each source type for details. - 4
- The
strategy
section describes the build strategy used to execute the build. You can specifySource
,Docker
andCustom
strategies here. This above example uses theruby-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.
9.3. Source-to-Image Strategy Options
The following options are specific to the S2I build strategy.
9.3.1. 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" 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.
9.3.2. 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. 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.
9.3.3. Overriding Builder Image Scripts
You can override the assemble, run, and save-artifactsS2I 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.
9.3.4. 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.
9.3.4.1. 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
.
9.3.4.2. 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"
9.4. Docker Strategy Options
The following options are specific to the Docker build strategy.
9.4.1. FROM Image
The FROM
instruction of the Dockerfile will be replaced by the from
of the BuildConfig
:
strategy: type: Docker dockerStrategy: from: kind: "ImageStreamTag" name: "debian:latest"
9.4.2. 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/):
strategy: type: Docker dockerStrategy: dockerfilePath: dockerfiles/app1/
9.4.3. 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
9.4.4. 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: "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.
9.4.5. 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/"
9.5. Custom Strategy Options
The following options are specific to the Custom build strategy.
9.5.1. 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
9.5.2. 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"
9.5.3. 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.
9.5.4. 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/"
9.6. Git Repository Source Options
When the BuildConfig.spec.source.type
is Git
, a Git repository is required, and an inline Dockerfile is optional.
The source code is fetched from the location specified and, if the BuildConfig.spec.source.dockerfile
field is specified, the inline Dockerfile replaces the one in the contextDir
of the Git repository.
The source definition is part of the spec
section in the BuildConfig
:
source: type: "Git" git: 1 uri: "https://github.com/openshift/ruby-hello-world" ref: "master" contextDir: "app/dir" 2 dockerfile: "FROM openshift/ruby-22-centos7\nUSER example" 3
- 1
- The
git
field contains the URI to the remote Git repository of the source code. Optionally, specify theref
field to check out a specific Git reference. A validref
can be a SHA1 tag or a branch name. - 2
- 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. - 3
- If the optional
dockerfile
field is provided, it should be a string containing a Dockerfile that overwrites any Dockerfile that may exist in the source repository.
9.6.1. 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
9.6.2. Using Private Repositories for Builds
Supply valid credentials to build an application from a private repository.
Currently two types of authentication are supported: basic username-password and SSH key based authentication.
9.6.2.1. Basic Authentication
Basic authentication requires either a combination of username
and password
, or a token
to authenticate against the SCM server. A CA certificate
file, or a .gitconfig
file can be attached.
A secret
is used to store your keys.
Create the
secret
first before using the username and password to access the private repository:$ oc secrets new-basicauth basicsecret --username=USERNAME --password=PASSWORD
To create a Basic Authentication Secret with a token:
$ oc secrets new-basicauth basicsecret --password=TOKEN
To create a Basic Authentication Secret with a CA certificate file:
$ oc secrets new-basicauth basicsecret --username=USERNAME --password=PASSWORD --ca-cert=FILENAME
To create a Basic Authentication Secret with a
.gitconfig
file:$ oc secrets new-basicauth basicsecret --username=USERNAME --password=PASSWORD --gitconfig=FILENAME
Add the
secret
to the builder service account. Each build is run withserviceaccount/builder
role, so you need to give it access your secret with following command:$ oc secrets add serviceaccount/builder secrets/basicsecret
Add a
sourceSecret
field to thesource
section inside theBuildConfig
and set it to the name of thesecret
that you created. In this casebasicsecret
:apiVersion: "v1" kind: "BuildConfig" metadata: name: "sample-build" spec: output: to: kind: "ImageStreamTag" name: "sample-image:latest" source: git: uri: "https://github.com/user/app.git" 1 sourceSecret: name: "basicsecret" type: "Git" strategy: sourceStrategy: from: kind: "ImageStreamTag" name: "python-33-centos7:latest" type: "Source"
- 1
- The URL of private repository, accessed by basic authentication, is usually in the
http
orhttps
form.
9.6.2.2. SSH Key Based Authentication
SSH Key Based Authentication requires a private SSH key. A .gitconfig
file can also be attached.
The repository keys are usually 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"
Creating a passphrase for the SSH key prevents OpenShift Enterprisefrom building. 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-sshauth sshsecret --ssh-privatekey=$HOME/.ssh/id_rsa
To create a SSH Based Authentication Secret with a
.gitconfig
file:$ oc secrets new-sshauth sshsecret --ssh-privatekey=$HOME/.ssh/id_rsa --gitconfig=FILENAME
Add the
secret
to the builder service account. Each build is run withserviceaccount/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 thesource
section inside theBuildConfig
and set it to the name of thesecret
that you created. In this casesshsecret
: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: "sshsecret" type: "Git" strategy: sourceStrategy: from: kind: "ImageStreamTag" name: "python-33-centos7:latest" type: "Source"
- 1
- The URL of private repository, accessed by a private SSH key, is usually in the form
git@example.com:<username>/<repository>.git
.
9.6.2.3. Other
If the cloning of your application is dependent on a CA certificate, .gitconfig
file, or both, then you can create a secret that contains them, add it to the builder service account, and then your BuildConfig
.
Create desired type of
secret
:To create a secret from a
.gitconfig
:$ oc secrets new mysecret .gitconfig=path/to/.gitconfig
To create a secret from a
CA certificate
:$ oc secrets new mysecret ca.crt=path/to/certificate
To create a secret from a
CA certificate
and.gitconfig
:$ oc secrets new mysecret ca.crt=path/to/certificate .gitconfig=path/to/.gitconfig
NoteSSL verification can be turned off, if
sslVerify=false
is set for thehttp
section in your.gitconfig
file:[http] sslVerify=false
Add the
secret
to the builder service account. Each build is run with theserviceaccount/builder
role, so you need to give it access your secret with following command:$ oc secrets add serviceaccount/builder secrets/mysecret
Add the
secret
to theBuildConfig
:source: git: uri: "https://github.com/sclorg/nodejs-ex.git" sourceSecret: name: "mysecret"
9.7. 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.
9.8. 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 context will consist of a single file named by the value of binary.asFile
. 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 (if asFile
is not set), 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: git: uri: https://github.com/sclorg/nodejs-ex.git secrets: - secret: name: secret-npmrc type: Git
To include the secrets in a new build configuration, run the following command:
$ oc new-build openshift/nodejs-010-centos7~https://github.com/sclorg/nodejs-ex.git
During the build, the .npmrc file is copied into the directory where the source code is located. In case of the OpenShift Enterprise S2I builder images, this is the image working directory, which is set using the WORKDIR
instruction in the Dockerfile. If you want to specify another directory, add a destinationDir
to the secret definition:
source: git: uri: https://github.com/sclorg/nodejs-ex.git secrets: - secret: name: secret-npmrc destinationDir: /etc type: Git
You can also specify the destination directory when creating a new build configuration:
$ oc new-build openshift/nodejs-010-centos7~https://github.com/sclorg/nodejs-ex.git
- The
binary
field specifies the details of the binary source. - The
asFile
field specifies the name of the file that will be created with the binary contents. - The
contextDir
field specifies a subdirectory within the extracted contents of a binary archive. - 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.
9.9. Starting a Build
Manually start a new build from an existing build configuration in your current project using the following command:
$ oc start-build <buildconfig_name>
Re-run a build using the --from-build
flag:
$ oc start-build --from-build=<build_name>
Specify the --follow
flag to stream the build’s logs in stdout:
$ oc start-build <buildconfig_name> --follow
Specify the --env
flag to set any desired environment variable for the build:
$ oc start-build <buildconfig_name> --env=<key>=<value>
Rather than relying on a Git source pull or a Dockerfile for a build, you can can also start a build by directly pushing your source, which could be the contents of a Git or SVN working directory, a set of prebuilt binary artifacts you want to deploy, or a single file. This can be done by specifying one of the following options for the start-build
command:
Option | Description |
---|---|
| Specifies a directory that will be archived and used as a binary input for the build. |
| Specifies a single file that will be the only file in the build source. The file is placed in the root of an empty directory with the same file name as the original file provided. |
|
Specifies a path to a local repository to use as the binary input for a build. Add the |
When passing any of these options directly to the build, the contents are streamed to the build and override the current build source settings.
Builds triggered from binary input will not preserve the source on the server, so rebuilds triggered by base image changes will use the source specified in the build configuration.
For example, the following command sends the contents of a local Git repository as an archive from the tag v2
and starts a build:
$ oc start-build hello-world --from-repo=../hello-world --commit=v2
9.10. Canceling a Build
Manually cancel a build using the web console, or with the following CLI command:
$ oc cancel-build <build_name>
9.11. Viewing Build Details
You can view build details using the web console or the following CLI command:
$ oc describe build <build_name>
The output of the describe
command includes details such as the build source, strategy, and output destination. If the build uses the Docker or Source strategy, it will also include information about the source revision used for the build: commit ID, author, committer, and message.
9.12. Accessing Build Logs
You can access build logs using the web console or the CLI.
To stream the logs using the build directly:
$ oc logs -f build/<build_name>
To stream the logs of the latest build for a build configuration:
$ oc logs -f bc/<buildconfig_name>
To return the logs of a given version build for a build configuration:
$ oc logs --version=<number> bc/<buildconfig_name>
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 Enterprise 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. |
9.13. Setting Maximum Duration
When defining a BuildConfig
, you can define its maximum duration by setting the completionDeadlineSeconds
field. It is specified in seconds and is not set by default. When not set, there is no maximum duration enforced.
The maximum duration is counted from the time when a build pod gets scheduled in the system, and defines how long it can be active, including the time needed to pull the builder image. After reaching the specified timeout, the build is terminated by OpenShift Enterprise.
The following example shows the part of a BuildConfig
specifying completionDeadlineSeconds
field for 30 minutes:
spec: completionDeadlineSeconds: 1800
9.14. 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:
9.14.1. Webhook Triggers
Webhook triggers allow you to trigger a new build by sending a request to the OpenShift Enterprise 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
, which will be part of the URL you supply to GitHub when configuring the webhook. The secret ensures the uniqueness of the URL, preventing others from triggering the build. The following example is a trigger definition YAML within the BuildConfig
:
type: "GitHub" github: secret: "secret101"
The secret field in webhook trigger configuration is not the same as secret
field you encounter when configuring webhook in GitHub UI. The former is to make the webhook URL unique and hard to predict, the latter is an optional string field used to create HMAC hex digest of the body, which is sent as an X-Hub-Signature
header.
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>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github
To configure a GitHub Webhook:
Describe the build configuration to get the webhook URL:
$ oc describe bc <name>
- Copy the webhook URL.
- Follow the GitHub setup instructions to paste the webhook URL into your GitHub repository settings.
Gogs supports the same webhook payload format as GitHub. Therefore, if you are using a Gogs server, you can define a GitHub webhook trigger on your BuildConfig
and trigger it via your Gogs server also.
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
which will be part of the URL, the caller must use to trigger the build. The secret ensures the uniqueness of the URL, preventing others from triggering the build. The following is an example trigger definition YAML 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>/oapi/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.
9.14.2. 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 namedocker-registry
running in OpenShift Enterprise.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 thelatest
tag of the image stream namedruby-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
andTag
as defined by the build strategy’sfrom
field. TheimageChange
object here must be empty. - 2
- An image change trigger that monitors an arbitrary image stream. The
imageChange
part in this case must include afrom
field that references theImageStreamTag
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.
9.14.3. 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 YAML 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.
9.15. 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 Enterprise Docker Registry, you don’t have to do this because secrets
are generated automatically for you by OpenShift Enterprise.
The .dockercfg JSON file is found in your home directory by default and has the following format:
auths: https://index.docker.io/v1/: 1 auth: "YWRfbGzhcGU6R2labnRib21ifTE=" 2 email: "user@example.com" 3
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
objects, 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. Each build is run withserviceaccount/builder
role, so you need to give it access your secret with following command:$ oc secrets add serviceaccount/builder secrets/dockerhub
Add a
pushSecret
field into theoutput
section of theBuildConfig
and set it to the name of thesecret
that you created, which in the above example is dockerhub:spec: output: to: kind: "DockerImage" name: "private.registry.com/org/private-image:latest" 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"
This example uses pullSecret
in a Source build, but it is also applicable in Docker and Custom builds.
9.16. Build Output
Docker and Source builds result in the creation of a new Docker image. The image is then pushed to the registry specified in the output
section of the Build
specification.
If the output kind is ImageStreamTag
, then the image will be pushed to the integrated OpenShift Enterprise registry and tagged in the specified image stream. If the output is of type DockerImage
, then the name of the output reference will be used as a Docker push specification. The specification may contain a registry or will default to DockerHub if no registry is specified. If the output section of the build specification is empty, then the image will not be pushed at the end of the build.
Example 9.2. Output to an ImageStreamTag
output: to: kind: "ImageStreamTag" name: "sample-image:latest"
Example 9.3. Output to a Docker Push Specification
output: to: kind: "DockerImage" name: "my-registry.mycompany.com:5000/myimages/myimage:tag"
9.16.1. Output Image Environment Variables
Docker and Source builds set the following environment variables on output images:
Variable | Description |
---|---|
| Name of the build |
| Namespace of the build |
| The source URL of the build |
| The Git reference used in the build |
| Source commit used in the build |
9.16.2. Output Image Labels
Docker and Source builds set the following labels on output images:
Label | Description |
---|---|
io.openshift.build.commit.author | Author of the source commit used in the build |
io.openshift.build.commit.date | Date of the source commit used in the build |
io.openshift.build.commit.id | Hash of the source commit used in the build |
io.openshift.build.commit.message | Message of the source commit used in the build |
io.openshift.build.commit.ref | Branch or reference specified in the source |
io.openshift.build.source-location | Source URL for the build |
9.17. Using External Artifacts During a Build
It is not recommended to store binary files in a source repository. Therefore, you may find it necessary to define a build which pulls additional files (such as Java .jar dependencies) during the build process. How this is done depends on the build strategy you are using.
For a Source
build strategy, you must put appropriate shell commands into the assemble script:
Example 9.4. .sti/bin/assemble File
#!/bin/sh APP_VERSION=1.0 wget http://repository.example.com/app/app-$APP_VERSION.jar -O app.jar
Example 9.5. .sti/bin/run File
#!/bin/sh exec java -jar app.jar
For more information on how to control which assemble and run script is used by a Source build, see Overriding Builder Image Scripts.
For a Docker
build strategy, you must modify the Dockerfile and invoke shell commands with the RUN
instruction:
Example 9.6. Excerpt of Dockerfile
FROM jboss/base-jdk:8 ENV APP_VERSION 1.0 RUN wget http://repository.example.com/app/app-$APP_VERSION.jar -O app.jar EXPOSE 8080 CMD [ "java", "-jar", "app.jar" ]
In practice, you may want to use an environment variable for the file location so that the specific file to be downloaded can be customized using an environment variable defined on the BuildConfig
, rather than updating the assemble script or Dockerfile.
You can choose between different methods of defining environment variables:
-
Using the .sti/environment file (only for a
Source
build strategy) -
Setting in
BuildConfig
-
Providing explicitly using
oc start-build --env
(only for builds that are triggered manually)
9.18. Build Resources
By default, builds are completed by pods using unbound resources, such as memory and CPU. These resources can be limited by specifying resource limits in a project’s default container limits.
You can also limit resource use by specifying resource limits as part of the build configuration. In the following example, each of the resources
, cpu
, and memory
parameters are optional:
apiVersion: "v1" kind: "BuildConfig" metadata: name: "sample-build" spec: resources: limits: cpu: "100m" 1 memory: "256Mi" 2
However, if a quota has been defined for your project, one of the following two items is required:
A
resources
section set with an explicitrequests
:resources: requests: 1 cpu: "100m" memory: "256Mi"
- 1
- The
requests
object contains the list of resources that correspond to the list of resources in the quota.
-
A limit range defined in your project, where the defaults from the
LimitRange
object apply to pods created during the build process.
Otherwise, build pod creation will fail, citing a failure to satisfy quota.
9.19. Troubleshooting
Issue | Resolution |
---|---|
A build fails with: requested access to the resource is denied | You have exceeded one of the image quotas set on your project. Check your current quota and verify the limits applied and storage in use: $ oc describe quota |