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:

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

      The Git repository containing your application source code.

      2

      The build strategy to build the container.

      3

      Parameters set for the buildpacks strategy.

      4

      The base image on which your application runs.

      5

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

      6

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

      7

      The location where the built image is pushed.

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

   1. Using oc CLI:

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

      Copy to Clipboard Toggle word wrap

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

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

      Reference to the buildpack-nodejs-build resource that will be executed.

   2. Using shp CLI:

      …​

1. Check if the BuildRun resource was created:

   1. Using oc CLI:

      $ oc get buildrun buildpack-nodejs-buildrun

      Copy to Clipboard Toggle word wrap

   2. Using shp CLI:

      $ shp buildrun list

      Copy to Clipboard Toggle word wrap

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

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

   $ oc get tr

   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
   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
   Note

   An example output of the podman pull command might look like this:

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

   1. Use the shp CLI
   2. Manually upload the OCI artifact