RHDEVDOCS-6488: creating build with buildpacks

modules/ob-creating-a-buildpacks-build.adoc

@@ -0,0 +1,257 @@
+:_mod-docs-content-type: PROCEDURE
+[id="ob-creating-a-buildpacks-build_{context}"]
+= Creating a buildpacks build
+
+Learn how to create a buildpacks build and push the created image into the target registry.
+There are two buildpacks `ClusterBuildStrategy` options are available for {builds-title}:
+
+* `buildpacks` strategy
+* `buildpacks-extender`strategy
+
+[NOTE]
+====
+The `buildpacks-extender`strategy is compatible with the experimental buildpacks`extender` lifecycle phase. You can use this strategy e.g for builds based on Node.js. However, the `extender` phase does not support Quarkus or any other Java-based builds. For such builds, you should use the `buildpacks` strategy instead.
+====
+
+[IMPORTANT]
+====
+Buildpacks is a Technology Preview feature only. Technology Preview features are not supported with Red{nbsp}Hat production service level agreements (SLAs) and might not be functionally complete. Red{nbsp}Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
+
+For more information about the support scope of Red{nbsp}Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope].
+====
+
+.Prerequisites
+
+* You have installed the {builds-operator} on the {ocp-product-title} cluster.
+* You have installed the `oc` CLI.
+* You have created the project where your final application image will be stored by using the command `oc new-project buildpacks-example`.
+* Optional: You have installed the `shp` CLI.
+
+.Procedure
+. Grant permission to access the image registry in the `buildpacks-example` project to the `pipeline` service with the two following commands:
++
+[source,terminal]
+----
+$ oc policy add-role-to-user system:image-puller system:serviceaccount:default:pipeline --namespace=buildpacks-example
+----
++
+[source,terminal]
+----
+$ oc policy add-role-to-user system:image-pusher system:serviceaccount:default:pipeline --namespace=buildpacks-example
+----
+. Switch back to the primary working project:
++
+[source,terminal]
+----
+$ oc project default
+----
+. Apply the permission:
++
+[source,terminal]
+----
+$ oc create rolebinding allow-builds-to-push \
+
+  --clusterrole=edit \
+
+ --serviceaccount=default:pipeline \
+
+--namespace=buildpacks-example
+----
+. Create a `Build` resource and apply it to the {ocp-product-title} cluster:
+.. Using `oc` CLI
++
+[source,terminal]
+----
+$ 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
+----
+<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 will run.
+<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.
++
+.. Using `shp` CLI:
++
+[source,terminal]
+----
+$ 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"
+----
+. Check if the `Build` resource was created:
+.. Using `oc` CLI:
++
+[source,terminal]
+----
+$ oc get builds.shipwright.io buildpack-nodejs-build
+----
+.. Using `shp` CLI:
++
+[source,terminal]
+----
+$ shp build list
+----
+. Create a `BuildRun` resource and apply it to the {ocp-product-title} cluster:
+.. .. Using `oc` CLI:
++
+[source,terminal]
+----
+$ 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
+----
+<1> Reference to the `buildpack-nodejs-build` resource that will be executed.
+.. Using `shp` CLI:
++
+...
+[source,terminal]
+----
+$ shp build run buildpack-nodejs-buildrun --follow
+----
++
+[IMPORTANT]
+====
+The `shp` CLI version 0.16.0 cannot automatically generate a name for the `BuildRun` resource.
+You must create the name manually:
+
+. Create a `BuilRun` resource with a unique name
++
+[source,terminal]
+----
+$ shp buildrun create buildpack-nodejs-<buildrun_resource_name>  --buildref-name buildpack-nodejs-build <1>
+----
+<1> Flag referencing the build.
+
+. Follow the logs:
++
+[source,terminal]
+----
+$ shp buildrun logs buildpack-nodej-<buildrun_resource_name> --follow
+----
+====
+. Check if the `BuildRun` resource was created:
+.. Using `oc` CLI:
++
+[source,terminal]
+----
+$ oc get buildrun buildpack-nodejs-buildrun
+----
+.. Using `shp` CLI:
++
+[source,terminal]
+----
+$ shp buildrun list
+----
+[NOTE]
+====
+The `BuildRun` resource creates a `TaskRun` resource, which then creates the pods to execute build strategy steps.
+====
+
+.Verification
+. Wait for all containers to complete their tasks.
+. Check if the pod shows the `STATUS` field as `Completed`:
++
+[source,terminal]
+----
+$ oc get pods -w
+----
+. Check if the `TaskRun` resource shows the `SUCCESS` field as `True`:
++
+[source,terminal]
+----
+$ oc get tr
+----
+. Check if the `BuildRun` resource shows the `SUCCESS` field as `True`:
++
+[source,terminal]
+----
+$ oc get br
+----
++
+[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.
+====
+. 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:
++
+[source,terminal]
+----
+$ podman pull
+----
++
+[NOTE]
+====
+An example output of the `podman pull` command might look like this:
+
+[source,terminal]
+----
+$ image-registry.openshift-image-registry.svc:5000/buildpacks-example/taxi-app
+----
+
+The project name in this example is `buildpacks-example`, and the image name is `taxi-app`.
+====

modules/ob-deleting-a-resource.adoc

@@ -43,10 +43,31 @@ $ oc delete buildrun <buildrun_resource_name>
 $ shp buildrun delete <buildrun_resource_name>
 ----
 +
+* Delete a `BuildRun` resource used by buildpacks by running the following command:
++
+.Using `oc` CLI
+[source,terminal]
+----
+$ oc delete buildrun <buildpacks_buildrun_resource_name>
+----
++
+.Using `shp` CLI
+[source,terminal]
+----
+$ shp delete buildrun <buildpacks_buildrun_resource_name>
+----
++
 * Delete a `BuildStrategy` resource by running the following command:
 +
 .Using `oc` CLI
 [source,terminal]
 ----
 $ oc delete buildstrategies <buildstartegy_resource_name>
 ----
+
+[IMPORTANT]
+====
+Buildpacks is a Technology Preview feature only. Technology Preview features are not supported with Red{nbsp}Hat production service level agreements (SLAs) and might not be functionally complete. Red{nbsp}Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
+
+For more information about the support scope of Red{nbsp}Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope].
+====

work_with_builds/using-builds.adoc

@@ -22,6 +22,8 @@ include::modules/ob-viewing-logs.adoc[leveloffset=+1]
 
 include::modules/ob-deleting-a-resource.adoc[leveloffset=+1]
 
+include::modules/ob-creating-a-buildpacks-build.adoc[leveloffset=+1]
+
 
 
 [role="_additional-resources"]