Chapter 3. Builds and Images

3.1. BuildConfigs

3.1.1. Description of Resource

Build configurations define a build process for new Docker images. There are three types of builds possible - a Docker build using a Dockerfile, a Source-to-Image build that uses a specially prepared base image that accepts source code that it can make runnable, and a custom build that can run arbitrary Docker images as a base and accept the build parameters. Builds run on the cluster and on completion are pushed to the Docker registry specified in the "output" section. A build can be triggered via a webhook, when the base image changes, or when a user manually requests a new build be created.

Each build created by a build configuration is numbered and refers back to its parent configuration. Multiple builds can be triggered at once. Builds that do not have "output" set can be used to test code or run a verification build.

3.1.2. Creating a New BuildConfig

3.1.2.1. Request Breakdown

Creating a new buildconfig requires one request:

A POST request to the buildconfigs subresource of the namespace.

The POST request uses a BuildConfig configuration in the request body. The following example uses a BuildConfig for the Jboss Developer kitchensink quickstart found at https://github.com/jboss-developer/jboss-eap-quickstarts.

3.1.2.2. POST Request to Create a New BuildConfig

Request Header

curl -k -v \
-X POST \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/buildconfigs

Request Body

apiVersion: v1
kind: BuildConfig
metadata:
  labels:
    app: {$PROJECT}
  name: {$BUILD}
spec:
  runPolicy: Serial
  source:
    contextDir: kitchensink
    git:
      ref: 7.1.0.Beta
      uri: https://github.com/jboss-developer/jboss-eap-quickstarts.git
    type: Git
  strategy:
    sourceStrategy:
      from:
        kind: ImageStreamTag
        name: jboss-eap70-openshift:1.4
        namespace: openshift
    type: Source
  triggers:
  - github:
      secret: 8d1d7bbf3313324f
    type: GitHub
  - generic:
      secret: 2a20ab9ac1316fcf
    type: Generic
  - imageChange: {}
    type: ImageChange
  - type: ConfigChange

3.1.3. Listing All BuildConfigs in an Environment

3.1.3.1. Request Breakdown

Listing all the buildconfigs in an environment requires one request:

A GET request to the buildconfigs resource.

The GET request returns the BuildConfigList, listing the details of all buildconfigs in the environment.

3.1.3.2. GET Request to Return All BuildConfigs in an Environment

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/buildconfigs

3.1.4. Listing all BuildConfigs in a Namespace

3.1.4.1. Request Breakdown

Listing all the buildconfigs in a namespace requires one request:

A GET request to the buildconfigs subresource of the namespace.

The GET request returns the BuildConfigList, listing the details of all buildconfigs in the namespace.

3.1.4.2. GET Request to Return BuildConfigs in Namespace

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/buildconfigs

3.1.5. Listing a Specific BuildConfig Configuration

3.1.5.1. Request Breakdown

Listing a specific buildconfig configuration requires one request:

A GET request to the buildconfig name in the buildconfigs subresource of the namespace.

The GET request returns the BuildConfig configuration for the specified build.

3.1.5.2. GET Request to Return Specific BuildConfig Configuration

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/buildconfigs/{$BUILDCONFIG}

3.1.6. Deleting a BuildConfig

3.1.6.1. Request Breakdown

Deleting a buildconfig requires one request:

A DELETE request to the buildconfig name in the buildconfigs subresource of the namespace.

The DELETE request returns a code: 200 and the buildconfig is deleted.

3.1.6.2. DELETE Request to Delete BuildConfig

Request Header

curl -k -v \
-X DELETE  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/buildconfigs/{BUILDCONFIG}

3.2. Builds

3.2.1. Description of Resource

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 object is the definition of the entire build process.

3.2.2. Listing All Builds in an Environment

3.2.2.1. Request Breakdown

Listing all the builds in an environment requires one request:

A GET request to the builds resource.

The GET request returns the BuildList, listing the details of all builds in the environment.

3.2.2.2. GET Request to Return All Builds in an Environment

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/builds

3.2.3. Listing all Builds in a Namespace

3.2.3.1. Request Breakdown

Listing all the builds in a namespace requires one request:

A GET request to the builds subresource of the namespace.

The GET request returns the BuildList, listing the details of all builds in the namespace.

3.2.3.2. GET Request to Return Builds in Namespace

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/builds

3.2.4. Listing a Specific Build Configuration

3.2.4.1. Request Breakdown

Listing a specific build configuration requires one request:

A GET request to the build name in the builds subresource of the namespace.

The GET request returns the Build configuration for the specified build.

3.2.4.2. GET Request to Return Specific Build Configuration

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/builds/{$BUILD}

3.2.5. Starting a Build

3.2.5.1. Request Breakdown

Starting a build requires one request:

A POST request to the instantiate subresource of the BuildConfig name.

The POST request returns a BuildConfig configuration.

3.2.5.2. POST Request to Start a Build

Request Header

curl -k -v \
-X POST \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/buildconfigs/{$BUILDCONFIG}

Request Body

kind: BuildRequest
apiVersion: v1
metadata:
  name: {$BUILDCONFIG}
triggeredBy:
- message: Manually triggered

3.2.6. Cancelling a Build

3.2.6.1. Request Breakdown

Cancelling a build consists of two requests:

A GET request to the build name in the builds subresource of the namespace.
A PUT request with an added cancelled field to the build name in the builds subresource of the namespace.

The GET request returns a Build configuration.
The GET request is optional if an updated Build configuration can otherwise be provided for the PUT request.

Include a spec: status: cancelled parameter with value true in the Build configuration. Send the updated configuration as the request body in a PUT request to the build name.

3.2.6.2. GET Request to Return Build Configuration

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/builds/{$BUILD}

3.2.6.3. PUT Request to Cancel a Build

Request Header

curl -k -v \
-X PUT \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/builds/{$BUILD}

Request Body Snippet

...
spec:
  status:
    cancelled: "true"
...

3.2.7. Deleting a Build

3.2.7.1. Request Breakdown

Deleting a build requires one request:

A DELETE request to the build name in the builds subresource of the namespace.

The DELETE request returns a code: 200 and the build is deleted.

3.2.7.2. DELETE Request to Delete Build

Request Header

curl -k -v \
-X DELETE  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/builds/{$BUILD}

3.3. Images

3.3.1. Description of Resource

An image is a binary that includes all of the requirements for running a single container, as well as metadata describing its needs and capabilities.

3.3.2. Creating an Image

3.3.2.1. Request Breakdown

Creating a new image requires one request:

A POST request to the images subresource of the namespace.

The POST request uses an Image configuration in the request body.

3.3.2.2. POST Request to Create a New Image

Request Header

curl -k -v \
-X POST \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/images

Request Body

apiVersion: v1
kind: Image
metadata:
  name: {$IMAGE}
dockerImageReference: registry.access.redhat.com/openshift3/jenkins-1-rhel7@sha256:9a370e38aca93da91bda03107f74fc245b169a8c642daf431a93289f44e187a0

3.3.3. Listing All Images in a Cluster

3.3.3.1. Request Breakdown

Listing all the images in a cluster requires one request:

A GET request to the images resource.

The GET request returns the ImageList, listing the details of all images in the cluster.

3.3.3.2. GET Request to Return All Images in a Cluster

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/images

3.3.4. Listing a Specific Image Configuration

3.3.4.1. Request Breakdown

Listing a specific image configuration in a cluster requires one request:

A GET request to the sha256:-prefixed image hash in the images resource.

The GET request returns the Image configuration for the specified image.

3.3.4.2. GET Request to Return Specific Image Configuration

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/images/sha256:{$IMAGEHASH}

3.3.5. Deleting an Image

3.3.5.1. Request Breakdown

Deleting an Image requires one request:

A DELETE request to the sha256:-prefixed image hash in the images resource.

The DELETE request returns a code: 200 and the Image is deleted.

3.3.5.2. DELETE Request to Delete Image

Request Header

curl -k -v \
-X DELETE  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/images/sha256:{$IMAGEHASH}

3.4. Image Streams

3.4.1. Description of Resource

An ImageStream stores a mapping of tags to images, metadata overrides that are applied when images are tagged in a stream, and an optional reference to a Docker image repository on a registry.

3.4.2. Creating a New Image Stream

3.4.2.1. Request Breakdown

Creating a new image stream requires one request:

A POST request to the imagestreams subresource of the namespace.

The POST request uses an ImageStream configuration in the request body.

3.4.2.2. POST Request to Create a New Image Stream

Request Header

curl -k -v \
-X POST \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/imagestreams

Request Body

kind: ImageStream
apiVersion: v1
metadata:
  name: test
  annotations:
    openshift.io/display-name: Test
spec:
  tags:
  - name: 1.0
    annotations:
      openshift.io/display-name: test (1.0)
      description: Vague description of this early test image.
      iconClass: icon-ruby
      tags: test
      sampleRepo: https://github.com/openshift/ruby-ex.git
    from:
      kind: ImageStreamTag
      name: '1.0'

3.4.3. Importing an Image Stream

3.4.3.1. Request Breakdown

Importing an image stream requires one request:

A POST request to the imagestreamimports subresource of the namespace.

The POST request uses an ImageStreamImport configuration in the request body.

The following example imports the ruby-23-rhel7:latest image into a namespace as a custom imagestream.

3.4.3.2. POST Request to Create a New Image Stream

Request Header

curl -k -v \
-X POST \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/imagestreamimports

Request Body

kind: ImageStreamImport
apiVersion: v1
metadata:
  name: {$IMAGESTREAM}
spec:
  import: true
  images:
  - from:
      kind: DockerImage
      name: registry.access.redhat.com/rhscl/ruby-23-rhel7:latest
    to:
      name: '{$IMAGESTREAMTAG}'

3.4.4. Listing All Image Streams in a Cluster

3.4.4.1. Request Breakdown

Listing all the image streams in a cluster requires one request:

A GET request to the imagestreams resource.

The GET request returns the ImageStreamList, listing the details of all image streams in the cluster.

3.4.4.2. GET Request to Return All Image Streams in a Cluster

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/imagestreams

3.4.5. Listing all Image Streams in a Namespace

3.4.5.1. Request Breakdown

Listing all the image streams in a namespace requires one request:

A GET request to the imagestreams subresource of the namespace.

The GET request returns the ImageStreamList, listing the details of all image streams in the namespace.

3.4.5.2. GET Request to Return Image Streams in Namespace

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/imagestreams

3.4.6. Listing a Specific Image Stream Configuration

3.4.6.1. Request Breakdown

Listing a specific image stream configuration requires one request:

A GET request to the image stream name in the imagestreams subresource of the namespace.

The GET request returns the ImageStream configuration for the specified image stream.

3.4.6.2. GET Request to Return Specific Image Stream Configuration

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/imagestreams/{$IMAGESTREAM}

3.4.7. Deleting an Image Stream

3.4.7.1. Request Breakdown

Deleting a image stream requires one request:

A DELETE request to the image stream name in the imagestreams subresource of the namespace.

The DELETE request returns a code: 200 and the image stream is deleted.

3.4.7.2. DELETE Request to Delete Image Stream

Request Header

curl -k -v \
-X DELETE  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/imagestreams/{$IMAGESTREAM}

3.5. Image Stream Tags

3.5.1. Description of Resource

An ImageStreamTag represents an Image that is retrieved by tag name from an ImageStream.

3.5.2. Adding an Image Stream Tag

3.5.2.1. Request Breakdown

Adding a tag to an image stream requires one request:

A PUT request to the image stream tag name in the imagestreamtags subresource of the namespace.

The PUT request uses an ImageStreamTag configuration in the request body.

The following example adds an image stream tag to the default ruby image stream in the openshift namespace.

3.5.2.2. PUT Request to Add an Image Stream Tag

Request Header

curl -k -v \
-X PUT  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/openshift/imagestreamtags/ruby:{$IMAGESTREAMTAG}

Request Body

kind: ImageStreamTag
metadata:
  name: ruby:{$IMAGESTREAMTAG}
tag:
  from:
    kind: ImageStreamImage
    namespace: openshift
    name: ruby@sha256:9cfdf4b811ace13d4c555335b249ab831832a384113035512abc9d4d5cc59716

3.5.3. Deleting an Image Stream Tag

3.5.3.1. Request Breakdown

Deleting an image stream tag requires one request:

A DELETE request to the image stream tag name in the imagestreamtags subresource of the namespace.

The DELETE request returns a code: 200 and the image stream tag is deleted.

The following example deletes the image stream tag, added in the previous example, from the default ruby image stream in the openshift namespace.

3.5.3.2. DELETE Request to Delete Image Stream Tag

Request Header

curl -k -v \
-X DELETE  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/openshift/imagestreamtags/ruby:{$IMAGESTREAMTAG}