Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 3. Builds and Images

3.1. BuildConfigs
Copy link

3.1.1. Description of Resource
Copy link

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
Copy link

3.1.2.1. Request Breakdown
Copy link

Creating a new buildconfig requires one request:

  1. 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
Copy link

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
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

3.1.3. Listing All BuildConfigs in an Environment
Copy link

3.1.3.1. Request Breakdown
Copy link

Listing all the buildconfigs in an environment requires one request:

  1. A GET request to the buildconfigs resource.

The GET request returns the BuildConfigList, listing the details of all buildconfigs in the 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
Copy to Clipboard Toggle word wrap

3.1.4. Listing all BuildConfigs in a Namespace
Copy link

3.1.4.1. Request Breakdown
Copy link

Listing all the buildconfigs in a namespace requires one request:

  1. 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.

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
Copy to Clipboard Toggle word wrap

3.1.5.1. Request Breakdown
Copy link

Listing a specific buildconfig configuration requires one request:

  1. 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.

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}
Copy to Clipboard Toggle word wrap

3.1.6. Deleting a BuildConfig
Copy link

3.1.6.1. Request Breakdown
Copy link

Deleting a buildconfig requires one request:

  1. 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
Copy link

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}
Copy to Clipboard Toggle word wrap

3.2. Builds
Copy link

3.2.1. Description of Resource
Copy link

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
Copy link

3.2.2.1. Request Breakdown
Copy link

Listing all the builds in an environment requires one request:

  1. A GET request to the builds resource.

The GET request returns the BuildList, listing the details of all builds in the 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
Copy to Clipboard Toggle word wrap

3.2.3. Listing all Builds in a Namespace
Copy link

3.2.3.1. Request Breakdown
Copy link

Listing all the builds in a namespace requires one request:

  1. 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
Copy link

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
Copy to Clipboard Toggle word wrap

3.2.4. Listing a Specific Build Configuration
Copy link

3.2.4.1. Request Breakdown
Copy link

Listing a specific build configuration requires one request:

  1. 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.

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}
Copy to Clipboard Toggle word wrap

3.2.5. Starting a Build
Copy link

3.2.5.1. Request Breakdown
Copy link

Starting a build requires one request:

  1. 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
Copy link

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}
Copy to Clipboard Toggle word wrap

Request Body 

kind: BuildRequest
apiVersion: v1
metadata:
  name: {$BUILDCONFIG}
triggeredBy:
- message: Manually triggered
Copy to Clipboard Toggle word wrap

3.2.6. Cancelling a Build
Copy link

3.2.6.1. Request Breakdown
Copy link

Cancelling a build consists of two requests:

  1. A GET request to the build name in the builds subresource of the namespace.
  2. 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
Copy link

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}
Copy to Clipboard Toggle word wrap

3.2.6.3. PUT Request to Cancel a Build
Copy link

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}
Copy to Clipboard Toggle word wrap

Request Body Snippet 

...
spec:
  status:
    cancelled: "true"
...
Copy to Clipboard Toggle word wrap

3.2.7. Deleting a Build
Copy link

3.2.7.1. Request Breakdown
Copy link

Deleting a build requires one request:

  1. 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
Copy link

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}
Copy to Clipboard Toggle word wrap

3.3. Images
Copy link

3.3.1. Description of Resource
Copy link

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
Copy link

3.3.2.1. Request Breakdown
Copy link

Creating a new image requires one request:

  1. 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
Copy link

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
Copy to Clipboard Toggle word wrap

Request Body 

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

3.3.3. Listing All Images in a Cluster
Copy link

3.3.3.1. Request Breakdown
Copy link

Listing all the images in a cluster requires one request:

  1. A GET request to the images resource.

The GET request returns the ImageList, listing the details of all images in the 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
Copy to Clipboard Toggle word wrap

3.3.4. Listing a Specific Image Configuration
Copy link

3.3.4.1. Request Breakdown
Copy link

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

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

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

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}
Copy to Clipboard Toggle word wrap

3.3.5. Deleting an Image
Copy link

3.3.5.1. Request Breakdown
Copy link

Deleting an Image requires one request:

  1. 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
Copy link

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}
Copy to Clipboard Toggle word wrap

3.4. Image Streams
Copy link

3.4.1. Description of Resource
Copy link

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
Copy link

3.4.2.1. Request Breakdown
Copy link

Creating a new image stream requires one request:

  1. 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
Copy link

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
Copy to Clipboard Toggle word wrap

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'
Copy to Clipboard Toggle word wrap

3.4.3. Importing an Image Stream
Copy link

3.4.3.1. Request Breakdown
Copy link

Importing an image stream requires one request:

  1. 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
Copy link

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
Copy to Clipboard Toggle word wrap

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}'
Copy to Clipboard Toggle word wrap

3.4.4. Listing All Image Streams in a Cluster
Copy link

3.4.4.1. Request Breakdown
Copy link

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

  1. A GET request to the imagestreams resource.

The GET request returns the ImageStreamList, listing the details of all image streams in the 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
Copy to Clipboard Toggle word wrap

3.4.5. Listing all Image Streams in a Namespace
Copy link

3.4.5.1. Request Breakdown
Copy link

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

  1. 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.

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
Copy to Clipboard Toggle word wrap

3.4.6.1. Request Breakdown
Copy link

Listing a specific image stream configuration requires one request:

  1. 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.

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}
Copy to Clipboard Toggle word wrap

3.4.7. Deleting an Image Stream
Copy link

3.4.7.1. Request Breakdown
Copy link

Deleting a image stream requires one request:

  1. 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
Copy link

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}
Copy to Clipboard Toggle word wrap

3.5. Image Stream Tags
Copy link

3.5.1. Description of Resource
Copy link

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

3.5.2. Adding an Image Stream Tag
Copy link

3.5.2.1. Request Breakdown
Copy link

Adding a tag to an image stream requires one request:

  1. 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
Copy link

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}
Copy to Clipboard Toggle word wrap

Request Body 

kind: ImageStreamTag
metadata:
  name: ruby:{$IMAGESTREAMTAG}
tag:
  from:
    kind: ImageStreamImage
    namespace: openshift
    name: ruby@sha256:9cfdf4b811ace13d4c555335b249ab831832a384113035512abc9d4d5cc59716
Copy to Clipboard Toggle word wrap

3.5.3. Deleting an Image Stream Tag
Copy link

3.5.3.1. Request Breakdown
Copy link

Deleting an image stream tag requires one request:

  1. 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
Copy link

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}
Copy to Clipboard Toggle word wrap
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat