Work with Builds

builds for Red Hat OpenShift 1.2

Using Builds

Red Hat OpenShift Documentation Team

Abstract

This document provides procedural examples for using Builds.

Chapter 1. Running Builds

After installing Builds, you can create a buildah or source-to-image build for use. You can also delete custom resources that are not required for a build.

1.1. Creating a buildah build

You can create a buildah build and push the created image to the target registry.

Prerequisites

You have installed the Builds for Red Hat OpenShift Operator on the OpenShift Container Platform cluster.
You have created a ShipwrightBuild resource.
You have installed the oc CLI.
Optional: You have installed the shp CLI.

Procedure

Create a Build resource and apply it to the OpenShift Container Platform cluster by using one of the CLIs:
Example: Using oc CLI
```
$ oc apply -f - <<EOF
apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-golang-build
spec:
  source: 1
    type: Git
    git:
      url: https://github.com/shipwright-io/sample-go
    contextDir: docker-build
  strategy: 2
    name: buildah
    kind: ClusterBuildStrategy
  paramValues: 3
  - name: dockerfile
    value: Dockerfile
  output: 4
    image: image-registry.openshift-image-registry.svc:5000/buildah-example/sample-go-app
EOF
```
1
The location where the source code is placed.
2
The build strategy that you use to build the container.
3
The parameter defined in the build strategy. To set the value of the dockerfile strategy parameter, specify the Dockerfile location required to build the output image.
4
The location where the built image is pushed. In this procedural example, the built image is pushed to the OpenShift Container Platform cluster internal registry. buildah-example is the name of the current project. Ensure that the specified project exists to allow the image push.
Example: Using shp CLI
```
$ shp build create buildah-golang-build \
--source-url="https://github.com/redhat-openshift-builds/samples" --source-context-dir="buildah-build" \1
--strategy-name="buildah" \2
--dockerfile="Dockerfile" \3
--output-image="image-registry.openshift-image-registry.svc:5000/buildah-example/go-app" 4
```
1
The location where the source code is placed.
2
The build strategy that you use to build the container.
3
The parameter defined in the build strategy. To set the value of the dockerfile strategy parameter, specify the Dockerfile location required to build the output image.
4
The location where the built image is pushed. In this procedural example, the built image is pushed to the OpenShift Container Platform cluster internal registry. buildah-example is the name of the current project. Ensure that the specified project exists to allow the image push.
Check if the Build resource is created by using one of the CLIs:
Example: Using oc CLI
```
$ oc get builds.shipwright.io buildah-golang-build
```
Example: Using shp CLI
```
$ shp build list
```
Create a BuildRun resource and apply it to the OpenShift Container Platform cluster by using one of the CLIs:
Example: Using oc CLI
```
$ oc apply -f - <<EOF
apiVersion: shipwright.io/v1beta1
kind: BuildRun
metadata:
  name: buildah-golang-buildrun
spec:
  build:
    name: buildah-golang-build 1
EOF
```
1
The spec.build.name field denotes the respective build to run, which is expected to be available in the same namespace.
Example: Using shp CLI
```
$ shp build run buildah-golang-build --follow 1
```
1
Optional: By using the --follow flag, you can view the build logs in the output result.
Check if the BuildRun resource is created by running one of the following commands:
Example: Using oc CLI
```
$ oc get buildrun buildah-golang-buildrun
```
Example: Using shp CLI
```
$ shp buildrun list
```
The BuildRun resource creates a TaskRun resource, which then creates the pods to execute build strategy steps.

Verification

After all the containers complete their tasks, verify the following:
- Check whether the pod shows the STATUS field as Completed:
```
$ oc get pods -w
```
  Example output
```
NAME                                READY   STATUS    RESTARTS   AGE
buildah-golang-buildrun-dtrg2-pod   2/2     Running   0          4s
buildah-golang-buildrun-dtrg2-pod   1/2     NotReady  0          7s
buildah-golang-buildrun-dtrg2-pod   0/2     Completed 0          55s
```
- Check whether the respective TaskRun resource shows the SUCCEEDED field as True:
```
$ oc get tr
```
  Example output
```
NAME                           SUCCEEDED  REASON     STARTTIME   COMPLETIONTIME
buildah-golang-buildrun-dtrg2  True       Succeeded  11m         8m51s
```
- Check whether the respective BuildRun resource shows the SUCCEEDED field as True:
```
$ oc get br
```
  Example output
```
NAME                     SUCCEEDED   REASON       STARTTIME     COMPLETIONTIME
buildah-golang-buildrun  True        Succeeded    13m           11m
```
  During verification, if a build run fails, you can check the status.failureDetails field in your BuildRun resource to identify the exact point where the failure happened in the pod or container.
  Note
  The pod might switch to a NotReady state because one of the containers has completed its task. This is an expected behavior.
Validate whether the image has been pushed to the registry that is specified in the build.spec.output.image field. You can try to pull the image by running the following command from a node that can access the internal registry:
```
$ podman pull image-registry.openshift-image-registry.svc:5000/<project>/<image> 1
```
1
The project name and image name used when creating the Build resource. For example, you can use buildah-example as the project name and sample-go-app as the image name.

1.1.1. Creating buildah build in a network-restricted environment

You can create a buildah build in a network-restricted environment by mirroring the images required by the buildah build strategy.

Prerequisites

Your cluster can connect and interact with the git source that you can use to create the buildah build.

Procedure

Run the following command to mirror the images required by the buildah build strategy:

$ oc image mirror --insecure -a <registry_authentication> registry.redhat.io/ubi8/buildah@sha256:1c89cc3cab0ac0fc7387c1fe5e63443468219aab6fd531c8dad6d22fd999819e <mirror_registry>/<repo>/ubi8_buildah

Perform the steps mentioned in the "Creating a buildah build" section.

1.2. Creating a source-to-image build

You can create a source-to-image build and push the created image to a custom Quay repository.

Prerequisites

You have installed the Builds for Red Hat OpenShift Operator on the OpenShift Container Platform cluster.
You have created a ShipwrightBuild resource.
You have installed the oc CLI.
Optional: You have installed the shp CLI.

Procedure

Create a Build resource and apply it to the OpenShift Container Platform cluster by using one of the CLIs:
Example: Using oc CLI
```
$ oc apply -f - <<EOF
apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: s2i-nodejs-build
spec:
  source: 1
    type: Git
    type: Git
        git:
          url: https://github.com/redhat-openshift-builds/samples
        contextDir: s2i-build/nodejs
  strategy: 2
    name: source-to-image
    kind: ClusterBuildStrategy
  paramValues: 3
  - name: builder-image
    value: quay.io/centos7/nodejs-12-centos7:master
  output:
    image: quay.io/<repo>/s2i-nodejs-example 4
    pushSecret: registry-credential 5
EOF
```
1
The location where the source code is placed.
2
The build strategy that you use to build the container.
3
The parameter defined in the build strategy. To set the value of the builder-image strategy parameter, specify the builder image location required to build the output image.
4
The location where the built image is pushed. You can push the built image to a custom Quay.io repository. Replace repo with a valid Quay.io organization or your Quay user name.
5
The secret name that stores the credentials for pushing container images. To generate a secret of the type docker-registry for authentication, see "Authentication to container registries".
Example: Using shp CLI
```
$ shp build create s2i-nodejs-build \
--source-url="https://github.com/redhat-openshift-builds/samples" --source-context-dir="s2i-build/nodejs" \1
--strategy-name="source-to-image" \2
--builder-image="quay.io/centos7/nodejs-12-centos7" \3
--output-image="quay.io/<repo>/s2i-nodejs-example" \4
--output-credentials-secret="registry-credential" 5
```
1
The location where the source code is placed.
2
The build strategy that you use to build the container.
3
The parameter defined in the build strategy. To set the value of the builder-image strategy parameter, specify the builder image location required to build the output image.
4
The location where the built image is pushed. You can push the built image to a custom Quay.io repository. Replace repo with a valid Quay.io organization or your Quay user name.
5
The secret name that stores the credentials for pushing container images. To generate a secret of the type docker-registry for authentication, see "Authentication to container registries".
Check if the Build resource is created by using one of the CLIs:
Example: Using oc CLI
```
$ oc get builds.shipwright.io s2i-nodejs-build
```
Example: Using shp CLI
```
$ shp build list
```
Create a BuildRun resource and apply it to the OpenShift Container Platform cluster by using one of the CLIs:
Example: Using oc CLI
```
$ oc apply -f - <<EOF
apiVersion: shipwright.io/v1beta1
kind: BuildRun
metadata:
  name: s2i-nodejs-buildrun
spec:
  build:
    name: s2i-nodejs-build 1
EOF
```
1
The spec.build.name field denotes the respective build to run, which is expected to be available in the same namespace.
Example: Using shp CLI
```
$ shp build run s2i-nodejs-build --follow 1
```
1
Optional: By using the --follow flag, you can view the build logs in the output result.
Check if the BuildRun resource is created by running one of the following commands:
Example: Using oc CLI
```
$ oc get buildrun s2i-nodejs-buildrun
```
Example: Using shp CLI
```
$ shp buildrun list
```
The BuildRun resource creates a TaskRun resource, which then creates the pods to execute build strategy steps.

Verification

After all the containers complete their tasks, verify the following:
- Check whether the pod shows the STATUS field as Completed:
```
$ oc get pods -w
```
  Example output
```
NAME                                READY   STATUS     RESTARTS   AGE
s2i-nodejs-buildrun-phxxm-pod       2/2     Running    0          10s
s2i-nodejs-buildrun-phxxm-pod       1/2     NotReady   0          14s
s2i-nodejs-buildrun-phxxm-pod       0/2     Completed  0          2m
```
- Check whether the respective TaskRun resource shows the SUCCEEDED field as True:
```
$ oc get tr
```
  Example output
```
NAME                           SUCCEEDED  REASON     STARTTIME   COMPLETIONTIME
s2i-nodejs-buildrun-phxxm      True       Succeeded  2m39s        13s
```
- Check whether the respective BuildRun resource shows the SUCCEEDED field as True:
```
$ oc get br
```
  Example output
```
NAME                     SUCCEEDED   REASON       STARTTIME     COMPLETIONTIME
s2i-nodejs-buildrun      True        Succeeded    2m41s           15s
```
  During verification, if a build run fails, you can check the status.failureDetails field in your BuildRun resource to identify the exact point where the failure happened in the pod or container.
  Note
  The pod might switch to a NotReady state because one of the containers has completed its task. This is an expected behavior.
Validate whether the image has been pushed to the registry that is specified in the build.spec.output.image field. You can try to pull the image by running the following command after logging in to the registry:
```
$ podman pull quay.io/<repo>/<image> 1
```
1
The repository name and image name used when creating the Build resource. For example, you can use s2i-nodejs-example as the image name.

Additional resources

Authentication to container registries

1.2.1. Creating source-to-image build in a network-restricted environment

You can create a source-to-image build in a network-restricted environment by mirroring the images required by the source-to-image build strategy.

Prerequisites

Your cluster can connect and interact with the git source that you can use to create the source-to-image build.
You have the builder-image required to create the source-to-image build in your local registry. If you do not have the builder-image in the local registry, mirror the source image.

Procedure

Run the following command to mirror the images required by the source-to-image build strategy:

$ oc image mirror --insecure -a <registry_authentication> registry.redhat.io/source-to-image/source-to-image-rhel8@sha256:d041c1bbe503d152d0759598f79802e257816d674b342670ef61c6f9e6d401c5 <mirror_registry>/<repo>/source-to-image-source-to-image-rhel8

Perform the steps mentioned in the "Creating a source-to-image build" section.

1.3. Viewing logs

You can view the logs of a build run to identify any runtime errors and to resolve them.

Prerequisites

You have installed the oc CLI.
Optional: You have installed the shp CLI.

Procedure

View logs of a build run by using one of the CLIs:

Using oc CLI

$ oc logs <buildrun_resource_name>

Using shp CLI

$ shp buildrun logs <buildrun_resource_name>

1.4. Deleting a resource

You can delete a Build, BuildRun, or BuildStrategy resource if it is not required in your project.

Prerequisites

You have installed the oc CLI.
Optional: You have installed the shp CLI.

Procedure

Delete a Build resource by using one of the CLIs:

Using oc CLI

$ oc delete builds.shipwright.io <build_resource_name>

Using shp CLI

$ shp build delete <build_resource_name>

Delete a BuildRun resource by using one of the CLIs:

Using oc CLI

$ oc delete buildrun <buildrun_resource_name>

Using shp CLI

$ shp buildrun delete <buildrun_resource_name>

Delete a BuildStrategy resource by running the following command:
Using oc CLI
```
$ oc delete buildstrategies <buildstartegy_resource_name>
```

1.5. Additional resources

Legal Notice

OpenShift documentation is licensed under the Apache License 2.0 (https://www.apache.org/licenses/LICENSE-2.0).

Modified versions must remove all Red Hat trademarks.

Portions adapted from https://github.com/kubernetes-incubator/service-catalog/ with modifications by Red Hat.

Red Hat, Red Hat Enterprise Linux, the Red Hat logo, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation’s permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Work with Builds

Using Builds

Chapter 1. Running Builds

1.1. Creating a buildah build

1.1.1. Creating buildah build in a network-restricted environment

1.2. Creating a source-to-image build

1.2.1. Creating source-to-image build in a network-restricted environment

1.3. Viewing logs

1.4. Deleting a resource

1.5. Additional resources

Legal Notice

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links