Chapter 2. Builds

A build is the process of transforming input parameters into a resulting object. Most often, the process is used to transform input parameters or source code into a runnable image. A

BuildConfig

OpenShift Container Platform uses Kubernetes by creating containers from build images and pushing them to a container image registry.

Build objects share common characteristics including inputs for a build, the requirement to complete a build process, logging the build process, publishing resources from successful builds, and publishing the final status of the build. Builds take advantage of resource restrictions, specifying limitations on resources such as CPU usage, memory usage, and build or pod execution time.

The OpenShift Container Platform build system provides extensible support for build strategies that are based on selectable types specified in the build API. There are three primary build strategies available:

By default, docker builds and S2I builds are supported.

The resulting object of a build depends on the builder used to create it. For docker and S2I builds, the resulting objects are runnable images. For custom builds, the resulting objects are whatever the builder image author has specified.

Additionally, the pipeline build strategy can be used to implement sophisticated workflows:

buildArgs

buildah run

jenkinsfile

jenkinsfile

A build configuration describes a single build definition and a set of triggers for when a new build is created. Build configurations are defined by a

BuildConfig

A build configuration, or

BuildConfig

Depending on how you choose to create your application using OpenShift Container Platform, a

BuildConfig

BuildConfig

The following example

BuildConfig

kind: BuildConfig
apiVersion: build.openshift.io/v1
metadata:
  name: "ruby-sample-build" 

spec:
  runPolicy: "Serial" 

  triggers: 

    -
      type: "GitHub"
      github:
        secret: "secret101"
    - type: "Generic"
      generic:
        secret: "secret101"
    -
      type: "ImageChange"
  source: 

    git:
      uri: "https://github.com/openshift/ruby-hello-world"
  strategy: 

    sourceStrategy:
      from:
        kind: "ImageStreamTag"
        name: "ruby-20-centos7:latest"
  output: 

    to:
      kind: "ImageStreamTag"
      name: "origin-ruby-sample:latest"
  postCommit: 

      script: "bundle exec rake test"

A build input provides source content for builds to operate on. You can use the following build inputs to provide sources in OpenShift Container Platform, listed in order of precedence:

You can combine multiple inputs in a single build. However, as the inline Dockerfile takes precedence, it can overwrite any other file named Dockerfile provided by another input. Binary (local) input and Git repositories are mutually exclusive inputs.

You can use input secrets when you do not want certain resources or credentials used during a build to be available in the final application image produced by the build, or want to consume a value that is defined in a secret resource. External artifacts can be used to pull in additional files that are not available as one of the other build input types.

When you run a build:

The following example of a source definition includes multiple input types and an explanation of how they are combined. For more details on how each input type is defined, see the specific sections for each input type.

source:
  git:
    uri: https://github.com/openshift/ruby-hello-world.git 

    ref: "master"
  images:
  - from:
      kind: ImageStreamTag
      name: myinputimage:latest
      namespace: mynamespace
    paths:
    - destinationDir: app/dir/injected/dir 

      sourcePath: /usr/lib/somefile.jar
  contextDir: "app/dir" 

  dockerfile: "FROM centos:7\nRUN yum install -y httpd" 

When you supply a

dockerfile

dockerfile

The source definition is part of the

spec

BuildConfig

source:
  dockerfile: "FROM centos:7\nRUN yum install -y httpd" 

You can add additional files to the build process with images. Input images are referenced in the same way the

From

To

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 is loaded and the indicated files and directories are copied into the context directory of the build process. This is the same directory into which the source repository content is cloned. If the source path ends in

/.

Image inputs are specified in the

source

BuildConfig

source:
  git:
    uri: https://github.com/openshift/ruby-hello-world.git
    ref: "master"
  images: 

  - from: 

      kind: ImageStreamTag
      name: myinputimage:latest
      namespace: mynamespace
    paths: 

    - destinationDir: injected/dir 

      sourcePath: /usr/lib/somefile.jar 

  - from:
      kind: ImageStreamTag
      name: myotherinputimage:latest
      namespace: myothernamespace
    pullSecret: mysecret 

    paths:
    - destinationDir: injected/dir
      sourcePath: /usr/lib/somefile.jar

builder

$ oc secrets link builder dockerhub

build error: failed to pull image

When specified, source code is fetched from the supplied location.

If you supply an inline Dockerfile, it overwrites the Dockerfile in the

contextDir

The source definition is part of the

spec

BuildConfig

source:
  git: 

    uri: "https://github.com/openshift/ruby-hello-world"
    ref: "master"
  contextDir: "app/dir" 

  dockerfile: "FROM openshift/ruby-22-centos7\nUSER example" 

If the

ref

git fetch

FETCH_HEAD

When no

ref

--depth=1

master

git clone

ref

main

source

NoProxy

source:
  git:
    uri: "https://github.com/openshift/ruby-hello-world"
    ref: "master"
    httpProxy: http://proxy.example.com
    httpsProxy: https://proxy.example.com
    noProxy: somedomain.com, otherdomain.com

BuildConfig

BuildConfig

BuildConfig

build.openshift.io/source-secret-match-uri-

BuildConfig

BuildConfig

*

ssh://git@bitbucket.atlassian.com:7999/ATLASSIAN jira.git

ssh://bitbucket.atlassian.com:7999/*

ssh://git@bitbucket.atlassian.com:7999/*

$ oc annotate secret mysecret \
    'build.openshift.io/source-secret-match-uri-1=ssh://bitbucket.atlassian.com:7999/*'

BuildConfig

mycorp.com

mydev1.mycorp.com

mydev2.mycorp.com

kind: Secret
apiVersion: v1
metadata:
  name: matches-all-corporate-servers-https-only
  annotations:
    build.openshift.io/source-secret-match-uri-1: https://*.mycorp.com/*
data:
  ...
---
kind: Secret
apiVersion: v1
metadata:
  name: override-for-my-dev-servers-https-only
  annotations:
    build.openshift.io/source-secret-match-uri-1: https://mydev1.mycorp.com/*
    build.openshift.io/source-secret-match-uri-2: https://mydev2.mycorp.com/*
data:
  ...

sourceSecret

source

BuildConfig

basicsecret

apiVersion: "build.openshift.io/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"
    sourceSecret:
      name: "basicsecret"
  strategy:
    sourceStrategy:
      from:
        kind: "ImageStreamTag"
        name: "python-33-centos7:latest"

oc set build-secret

.gitconfig

BuildConfig

$ oc create secret generic <secret_name> --from-file=<path/to/.gitconfig>

sslVerify=false

http

.gitconfig

[http]
        sslVerify=false

.gitconfig

.gitconfig

--username

--password

$HOME/.ssh/

id_dsa.pub

id_ecdsa.pub

id_ed25519.pub

id_rsa.pub

.gitconfig

.gitconfig

.gitconfig

.gitconfig

Streaming content from a local file system to the builder is called a

Binary

BuildConfig.spec.source.type

Binary

This source type is unique in that it is leveraged solely based on your use of the

oc start-build

To utilize binary builds, invoke

oc start-build

In each of the previously listed cases:

Instead of a file name, you can pass a URL with HTTP or HTTPS schema to

--from-file

--from-archive

--from-file

Content-Disposition

When using

oc new-build --binary=true

BuildConfig

Binary

BuildConfig

oc start-build

--from

The Dockerfile and

contextDir

Dockerfile can be used with any binary build source. If Dockerfile is used and the binary stream is an archive, its contents serve as a replacement Dockerfile to any Dockerfile in the archive. If Dockerfile is used with the

--from-file

In the case of the binary stream encapsulating extracted archive content, the value of the

contextDir

In some scenarios, build operations require credentials or other configuration data to access dependent resources, but it is undesirable for that information to be placed in source control. You can define input secrets and input config maps for this purpose.

For example, when building a Java application with Maven, you can set up a private mirror of Maven Central or JCenter that is accessed by private keys. To download libraries from that private mirror, you have to supply the following:

For security reasons, you do not want to expose your credentials in the application image.

This example describes a Java application, but you can use the same approach for adding SSL certificates into the

/etc/ssl/certs

Secret

dockercfg

apiVersion: v1
kind: Secret
metadata:
  name: test-secret
  namespace: my-namespace
type: Opaque 

data: 

  username: <username> 

  password: <password>
stringData: 

  hostname: myapp.mydomain.com 

type

opaque

type= Opaque

opaque

key:value

example.com/my-secret-type

PodSpec

kubectl rolling-update

resourceVersion

resourceVersion

BuildConfig

BuildConfig

$ oc new-build \
    openshift/wildfly-101-centos7~https://github.com/wildfly/quickstart.git \
    --context-dir helloworld --build-secret “secret-mvn” \
    --build-config-map "settings-mvn"

settings.xml

id_rsa

WORKDIR

Dockerfile

destinationDir

source:
  git:
    uri: https://github.com/wildfly/quickstart.git
  contextDir: helloworld
  configMaps:
    - configMap:
        name: settings-mvn
      destinationDir: ".m2"
  secrets:
    - secret:
        name: secret-mvn
      destinationDir: ".ssh"

BuildConfig

$ oc new-build \
    openshift/wildfly-101-centos7~https://github.com/wildfly/quickstart.git \
    --context-dir helloworld --build-secret “secret-mvn:.ssh” \
    --build-config-map "settings-mvn:.m2"

settings.xml

./.m2

id_rsa

./.ssh

Source

destinationDir

destinationDir

destinationDir

destinationDir

destinationDir

0666

assemble

assemble

destinationDir

destinationDir

FROM centos/ruby-22-centos7

USER root
COPY ./secret-dir /secrets
COPY ./config /

# Create a shell script that will output secrets and ConfigMaps when the image is run
RUN echo '#!/bin/sh' > /input_report.sh
RUN echo '(test -f /secrets/secret1 && echo -n "secret1=" && cat /secrets/secret1)' >> /input_report.sh
RUN echo '(test -f /config && echo -n "relative-configMap=" && cat /config)' >> /input_report.sh
RUN chmod 755 /input_report.sh

CMD ["/bin/sh", "-c", "/input_report.sh"]

/var/run/secrets/openshift.io/build

/var/run/secrets/openshift.io/build

$BUILD

It is not recommended to store binary files in a source repository. Therefore, you must define a build which pulls additional files, such as Java

.jar

For a Source build strategy, you must put appropriate shell commands into the

assemble

#!/bin/sh
APP_VERSION=1.0
wget http://repository.example.com/app/app-$APP_VERSION.jar -O app.jar

#!/bin/sh
exec java -jar app.jar

For a Docker build strategy, you must modify the Dockerfile and invoke shell commands with the RUN instruction:

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

assemble

You can choose between different methods of defining environment variables:

You can supply builds with a .

docker/config.json

You can supply credentials for multiple repositories within the same registry, each with credentials specific to that registry path.

The

.docker/config.json

auths:
  index.docker.io/v1/: 

    auth: "YWRfbGzhcGU6R2labnRib21ifTE=" 

    email: "user@example.com" 

  docker.io/my-namespace/my-user/my-image: 

    auth: "GzhYWRGU6R2fbclabnRgbkSp=""
    email: "user@example.com"
  docker.io/my-namespace: 

    auth: "GzhYWRGU6R2deesfrRgbkSp=""
    email: "user@example.com"

You can define multiple container image registries or define multiple repositories in the same registry. Alternatively, you can also add authentication entries to this file by running the

docker login

Kubernetes provides

Secret

As with pod environment variables, build environment variables can be defined in terms of references to other resources or variables using the Downward API. There are some exceptions, which are noted.

You can also manage environment variables defined in the

BuildConfig

oc set env

valueFrom

fieldPath

JsonPath

valueFrom

valueFrom

Service serving certificate secrets are intended to support complex middleware applications that need out-of-the-box certificates. It has the same settings as the server certificates generated by the administrator tooling for nodes and masters.

<service.name>.<service.namespace>.svc

<service.name>.<service.namespace>.svc

Other pods can trust cluster-created certificates, which are only signed for internal DNS names, by using the certificate authority (CA) bundle in the

/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt

The signature algorithm for this feature is

x509.SHA256WithRSA

To use a secret, a pod needs to reference the secret. A secret can be used with a pod in three ways:

Volume type secrets write data into the container as a file using the volume mechanism.

imagePullSecrets

When a template contains a secret definition, the only way for the template to use the provided secret is to ensure that the secret volume sources are validated and that the specified object reference actually points to an object of type

Secret

Secret API objects reside in a namespace. They can only be referenced by pods in that same namespace.

Individual secrets are limited to 1MB in size. This is to discourage the creation of large secrets that would exhaust apiserver and kubelet memory. However, creation of a number of smaller secrets could also exhaust memory.

Builds that use the docker or source-to-image (S2I) strategy result in the creation of a new container image. The image is then pushed to the container image registry specified in the

output

Build

If the output kind is

ImageStreamTag

DockerImage

spec:
  output:
    to:
      kind: "ImageStreamTag"
      name: "sample-image:latest"

spec:
  output:
    to:
      kind: "DockerImage"
      name: "my-registry.mycompany.com:5000/myimages/myimage:tag"

docker and source-to-image (S2I) strategy builds set the following environment variables on output images:

OPENSHIFT_BUILD_NAME

OPENSHIFT_BUILD_NAMESPACE

OPENSHIFT_BUILD_SOURCE

OPENSHIFT_BUILD_REFERENCE

OPENSHIFT_BUILD_COMMIT

Additionally, any user-defined environment variable, for example those configured with S2I] or docker strategy options, will also be part of the output image environment variable list.

docker and source-to-image (S2I)` builds set the following labels on output images:

io.openshift.build.commit.author

io.openshift.build.commit.date

io.openshift.build.commit.id

io.openshift.build.commit.message

io.openshift.build.commit.ref

io.openshift.build.source-location

You can also use the

BuildConfig.spec.output.imageLabels

spec:
  output:
    to:
      kind: "ImageStreamTag"
      name: "my-image:latest"
    imageLabels:
    - name: "vendor"
      value: "MyCompany"
    - name: "authoritative-source-url"
      value: "registry.mycompany.com"

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

buildArgs

FROM

from

BuildConfig

FROM

FROM

from

BuildConfig

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

BuildConfig.spec.source.contextDir

dockerfilePath

BuildConfig.spec.source.contextDir

MyDockerfile

dockerfiles/app1/Dockerfile

dockerfilePath

strategy:
  dockerStrategy:
    dockerfilePath: dockerfiles/app1/Dockerfile

dockerStrategy

ENV

FROM

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

oc set env

buildArgs

buildArgs

dockerStrategy

BuildConfig

dockerStrategy:
...
  buildArgs:
    - name: "foo"
      value: "bar"

name

value

valueFrom

imageOptimizationPolicy

SkipLayers

Source-to-image (S2I) is a tool for building reproducible container images. It produces ready-to-run images by injecting application source into a container image and assembling a new image. The new image incorporates the base image, the builder, and built source and is ready to use with the

buildah run

assemble

run

save-artifacts

assemble

run

save-artifacts

scripts

.s2i/bin

.s2i/environment

.s2i/environment

assemble

development

production

sourceStrategy

assemble

run

.s2iignore

.s2iignore

assemble

FROM

assemble

run

save-artifacts

io.openshift.s2i.scripts-url

assemble

assemble

run

run

save-artifacts

save-artifacts

tar

usage

usage

test/run

test/run

test/run

test/test-app

tar

/tmp/s2i

#!/bin/bash

# restore build artifacts
if [ "$(ls /tmp/s2i/artifacts/ 2>/dev/null)" ]; then
    mv /tmp/s2i/artifacts/* $HOME/.
fi

# move the application source
mv /tmp/s2i/src $HOME/src

# build application artifacts
pushd ${HOME}
make all

# install the artifacts
make install
popd

#!/bin/bash

# run the application
/opt/application/run.sh

#!/bin/bash

pushd ${HOME}
if [ -d deps ]; then
    # all deps contents to tar stream
    tar cf - deps
fi
popd

#!/bin/bash

# inform the user how to use the image
cat <<EOF
This is a S2I sample builder image, to use it, install
https://github.com/openshift/source-to-image
EOF

The custom build strategy allows developers to define a specific builder image responsible for the entire build process. Using your own builder image allows you to customize your build process.

A custom builder image is a plain container image embedded with build process logic, for example for building RPMs or base images.

Custom builds run with a high level of privilege and are not available to users by default. Only users who can be trusted with cluster administration permissions should be granted access to run custom builds.

customStrategy.from

customStrategy

BUILD

Build

buildAPIVersion

SOURCE_REPOSITORY

SOURCE_URI

SOURCE_REPOSITORY

SOURCE_CONTEXT_DIR

SOURCE_REF

ORIGIN_VERSION

OUTPUT_REGISTRY

OUTPUT_IMAGE

PUSH_DOCKERCFG_PATH

podman push

jenkinsfile

The Pipeline build strategy allows developers to define a Jenkins pipeline for use by the Jenkins pipeline plugin. The build can be started, monitored, and managed by OpenShift Container Platform in the same way as any other build type.

Pipeline workflows are defined in a

jenkinsfile

jenkinsfile

jenkinsfiles

oc

jenkinsfile

jenkinsfile

jenkinsfilePath

contextDir

contextDir

jenkinsfilePath

jenkinsfile

jenkinsfile

jenkinsfile

jenkinsfile

jenkinsfile

jenkinsfile

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')
        }

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 

jenkinsfile

jenkinsPipelineStrategy

oc set env

jenkinsfile

Node.js/MongoDB

nodejs-mongodb.json

You can add a secret to your build configuration so that it can access a private repository.

You can enable pulling to a private registry by setting the pull secret and pushing by setting the push secret in the build configuration.

To enable pushing:

You must create the image you want to use as your custom build image.

You can use OpenShift Container Platform to build and push custom builder images to use in a custom strategy.

You can define a

BuildConfig

You can manually start a new build from an existing build configuration in your current project.

$ oc start-build <buildconfig_name>

--from-build

--follow

stdout

--env

start-build

--from-dir=<directory>

--from-file=<file>

--from-repo=<local_source_repo>

--commit

You can cancel a build using the web console, or with the following CLI command.

new

pending

To edit your build configurations, you use the Edit BuildConfig option in the Builds view of the Developer perspective.

You can use either of the following views to edit a

BuildConfig

You can switch between the Form view and YAML view without losing any data. The data in the Form view is transferred to the YAML view and vice versa.

You can delete a

BuildConfig

You can view build details with the web console or by using the

oc describe

This displays information including:

If the build uses the

Docker

Source

oc describe

You can access build logs using the web console or the CLI.

BuildConfig

BuildConfig