Work with Builds

Procedure

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

   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.

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

   Copy to Clipboard Toggle word wrap

   Example: Using shp CLI

   $ shp build list

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

   1

   Optional: By using the --follow flag, you can view the build logs in the output result.

4. Check if the BuildRun resource is created by running one of the following commands:

   Example: Using oc CLI

   $ oc get buildrun buildah-golang-buildrun

   Copy to Clipboard Toggle word wrap

   Example: Using shp CLI

   $ shp buildrun list

   Copy to Clipboard Toggle word wrap

   The BuildRun resource creates a TaskRun resource, which then creates the pods to execute build strategy steps.

Verification

1. After all the containers complete their tasks, verify the following:

   • Check whether the pod shows the STATUS field as Completed:

     $ oc get pods -w

     Copy to Clipboard Toggle word wrap

     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

     Copy to Clipboard Toggle word wrap

   • Check whether the respective TaskRun resource shows the SUCCEEDED field as True:

     $ oc get tr

     Copy to Clipboard Toggle word wrap

     Example output

     NAME                           SUCCEEDED  REASON     STARTTIME   COMPLETIONTIME
     buildah-golang-buildrun-dtrg2  True       Succeeded  11m         8m51s

     Copy to Clipboard Toggle word wrap

   • Check whether the respective BuildRun resource shows the SUCCEEDED field as True:

     $ oc get br

     Copy to Clipboard Toggle word wrap

     Example output

     NAME                     SUCCEEDED   REASON       STARTTIME     COMPLETIONTIME
     buildah-golang-buildrun  True        Succeeded    13m           11m

     Copy to Clipboard Toggle word wrap

     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.

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

   Copy to Clipboard Toggle word wrap

   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.

Procedure

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

   Example: Using shp CLI

   $ shp build list

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

   1

   Optional: By using the --follow flag, you can view the build logs in the output result.

4. Check if the BuildRun resource is created by running one of the following commands:

   Example: Using oc CLI

   $ oc get buildrun s2i-nodejs-buildrun

   Copy to Clipboard Toggle word wrap

   Example: Using shp CLI

   $ shp buildrun list

   Copy to Clipboard Toggle word wrap

   The BuildRun resource creates a TaskRun resource, which then creates the pods to execute build strategy steps.

Verification

1. After all the containers complete their tasks, verify the following:

   • Check whether the pod shows the STATUS field as Completed:

     $ oc get pods -w

     Copy to Clipboard Toggle word wrap

     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

     Copy to Clipboard Toggle word wrap

   • Check whether the respective TaskRun resource shows the SUCCEEDED field as True:

     $ oc get tr

     Copy to Clipboard Toggle word wrap

     Example output

     NAME                           SUCCEEDED  REASON     STARTTIME   COMPLETIONTIME
     s2i-nodejs-buildrun-phxxm      True       Succeeded  2m39s        13s

     Copy to Clipboard Toggle word wrap

   • Check whether the respective BuildRun resource shows the SUCCEEDED field as True:

     $ oc get br

     Copy to Clipboard Toggle word wrap

     Example output

     NAME                     SUCCEEDED   REASON       STARTTIME     COMPLETIONTIME
     s2i-nodejs-buildrun      True        Succeeded    2m41s           15s

     Copy to Clipboard Toggle word wrap

     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.

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

   Copy to Clipboard Toggle word wrap

   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.

Procedure

1. Optional: To use the shp CLI with buildpacks, you must first grant permission to the pipeline service account to access the image registry in the buildpacks-example project with the following two commands:

   $ oc policy add-role-to-user system:image-puller system:serviceaccount:default:pipeline --namespace=buildpacks-example

   Copy to Clipboard Toggle word wrap

   $ oc policy add-role-to-user system:image-pusher system:serviceaccount:default:pipeline --namespace=buildpacks-example

   Copy to Clipboard Toggle word wrap

2. Optional: Continue with shp CLI by switching back to the primary working project:

   $ oc project default

   Copy to Clipboard Toggle word wrap

3. Optional: Finish shp CLI setup by applying the permission:

   $ oc create rolebinding allow-builds-to-push \
   
     --clusterrole=edit \
   
    --serviceaccount=default:pipeline \
   
   --namespace=buildpacks-example

   Copy to Clipboard Toggle word wrap

4. Create a Build resource and apply it to the OpenShift Container Platform cluster by using one of the following CLIs:

   • Using oc CLI

     $ oc apply -f - <<EOF
     apiVersion: shipwright.io/v1beta1
     
     kind: Build
     
     metadata:
     
       name: buildpack-nodejs-build
     
     spec:
     
       source: 

     1

     
     
         type: Git
     
         git:
     
           url: https://github.com/redhat-openshift-builds/samples.git
     
       strategy: 

     2

     
     
         name: buildpacks
     
         kind: ClusterBuildStrategy
     
       retention:
     
         atBuildDeletion: true
     
       paramValues: 

     3

     
     
         - name: run-image 

     4

     
     
           value: paketobuildpacks/run-ubi8-base:latest
     
         - name: cnb-builder-image 

     5

     
     
           value: paketobuildpacks/builder-jammy-tiny:0.0.344
     
         - name: source-subpath 

     6

     
     
           value: "buildpacks/nodejs"
     
       output: 

     7

     
         image: image-registry.openshift-image-registry.svc:5000/buildpacks-example/taxi-app
     EOF

     Copy to Clipboard Toggle word wrap

     1

     Defines the Git repository containing your application source code.

     2

     Defines the build strategy to build the container.

     3

     Defines the parameters set for the buildpacks strategy.

     4

     Specifies the base image on which your application runs.

     5

     Specifies the builder image used by Cloud Native Buildpacks (CNB) to detect and build your application.

     6

     Specifies the subdirectory within your Git repository where the application source code is located.

     7

     Specifies the location where the built image is pushed.

   • Using shp CLI:

     $ shp build create buildpack-nodejs-build \
     
     --source-git-url="https://github.com/redhat-openshift-builds/samples.git" \
     
     --strategy-name="buildpacks" \
     
     --output-image="image-registry.openshift-image-registry.svc:5000/buildpacks-example/taxi-app" \
     
     --param-value="source-subpath=buildpacks/nodejs" \
     
     --param-value="cnb-builder-image=paketobuildpacks/builder-jammy-tiny:0.0.344" \
     --param-value="run-image=paketobuildpacks/run-ubi8-base:latest"

     Copy to Clipboard Toggle word wrap

5. Check if the Build resource was created by using one of the following CLIs:

   • Using oc CLI:

     $ oc get builds.shipwright.io buildpack-nodejs-build

     Copy to Clipboard Toggle word wrap

   • Using shp CLI:

     $ shp build list

     Copy to Clipboard Toggle word wrap

6. Create a BuildRun resource and apply it to the OpenShift Container Platform cluster by using one of the following CLIs:

   • Using oc CLI:

     $ oc apply -f - <<EOF
     apiVersion: shipwright.io/v1beta1
     kind: BuildRun
     metadata:
       name: buildpack-nodejs-buildrun
       namespace: builds-test
     spec:
       build:
         name: buildpack-nodejs-build 

     1

     
     EOF

     Copy to Clipboard Toggle word wrap

     1

     Specifies the buildpack-nodejs-build resource that will be executed.

   • Using shp CLI:

     …​

1. Check if the BuildRun resource was created by using one of the following CLIs:

   • Using oc CLI:

     $ oc get buildrun buildpack-nodejs-buildrun

     Copy to Clipboard Toggle word wrap

   • Using shp CLI:

     $ shp buildrun list

     Copy to Clipboard Toggle word wrap
     Note

     The BuildRun resource creates a TaskRun resource, which then creates the pods to execute build strategy steps.

Verification

1. Wait for all containers to complete their tasks.

2. Check if the pod shows the STATUS field as Completed:

   $ oc get pods -w

   Copy to Clipboard Toggle word wrap

   Example output

   NAME                                 READY   STATUS     RESTARTS   AGE
   buildpack-go-build-ttwkl-d8x97-pod   2/8     NotReady   0          63s
   buildpack-go-build-ttwkl-d8x97-pod   0/8     Completed   0          72s
   buildpack-go-build-ttwkl-d8x97-pod   0/8     Completed   0          73s

   Copy to Clipboard Toggle word wrap

3. Check if the TaskRun resource shows the SUCCESS field as True:

   $ oc get tr

   Copy to Clipboard Toggle word wrap

   Example output

   NAME                             SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
   buildpack-go-build-ttwkl-d8x97   True        Succeeded   112s        38s

   Copy to Clipboard Toggle word wrap

4. Check if the BuildRun resource shows the SUCCESS field as True:

   $ oc get br

   Copy to Clipboard Toggle word wrap

   Example output

   NAME                       SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
   buildpack-go-build-ttwkl   True        Succeeded   107s        33s

   Copy to Clipboard Toggle word wrap
   Note

   If the 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.

   The pod might switch to a NotReady state because one of the containers has completed its task. This is an expected behavior.

5. Check if the image has been pushed to the registry you specified in the build.spec.output.image field by running the following command from a node that can access the internal registry to pull the image:

   $ podman pull

   Copy to Clipboard Toggle word wrap

   Example output

   $ image-registry.openshift-image-registry.svc:5000/buildpacks-example/taxi-app

   Copy to Clipboard Toggle word wrap

   The project name in this example is buildpacks-example, and the image name is taxi-app.

Procedure

1. Create a Build resource and apply it to the OpenShift Container Platform cluster. See the following example configuration:

   $ oc apply -f - <<EOF
   apiVersion: shipwright.io/v1beta1
   kind: Build
   metadata:
     name: my-oci-build 

   1

   
   spec:
     source:
       type: OCI
       ociArtifact:
         image: <quay.io/org/image:tag> 

   2

   
     strategy:
       name: <strategy-name> 

   3

   
       kind: ClusterBuildStrategy
     output:
       image: <target-image-registry/repository/image:tag> 

   4

   
       pushSecret: <secret-name-for-credentials> 

   5

   
   EOF

   Copy to Clipboard Toggle word wrap

   1

   Defines the name of the Build resource.

   2

   Replace <quay.io/org/image:tag> with the location of the OCI artifact source image.

   3

   Replace <strategy-name> with the name of the build strategy to build the container (buildah or source-to-image).

   4

   Replace <target-image-registry/repository/image:tag> with the location where you want to push the built image.

   5

   Optional: Replace <secret-name-for-credentials> with the secret name that stores the credentials for pushing container images. To generate a secret for a private registry for authentication, see Authentication to container registries

2. Choose one of the following methods to upload your source code to the required registry and run the build:

   • Use the shp CLI:

     • Run the following command in the directory containing the local source code. It packages your source code into a scratch container image, pushes it to the required registry, and runs the build:

       $ shp build upload my-oci-build 

       1

       Copy to Clipboard Toggle word wrap

       1

       Defines the name of the Build resource.

   • Upload the OCI artifact manually:

     1. Create a Containerfile in the root directory of your source code and add the following configuration:

        FROM scratch
        COPY . /

        Copy to Clipboard Toggle word wrap

     2. Run the following command in the root directory of your source code to build the container image using Podman:

        $ podman build -t <registry-path>/<image-name>:<tag> 

        1

        Copy to Clipboard Toggle word wrap

        1

        Replace <registry-path>/<image-name>:<tag> with the build location for the container image.

     3. Push the container image to the required location using the following command:

        $ podman push <registry-path>/<image-name>:<tag>  

        1

        Copy to Clipboard Toggle word wrap

        1

        Replace <registry-path>/<image-name>:<tag> with the location where you want to push the built image.

     4. Run the build using the following command:

        $ shp build run my-oci-build 

        1

        Copy to Clipboard Toggle word wrap

        1

        Defines the name of the Build resource.

Procedure

1. Run the following command to open the YAML definition in the default editor:

   $ oc edit <resource-name> <build_resource-name> 

   1

   Copy to Clipboard Toggle word wrap

   1

   Replace <resource-name> with the name of the resource (build, buildrun or buildstrategy) and <build_resource-name> with the name of the build resource that you want to edit.

2. Edit the YAML definition and save the file.