Chapter 3. Creating build inputs

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.