From c9f3a39c7c9583ca6f101b2f7c7618a9a13e108a Mon Sep 17 00:00:00 2001 From: deerskindoll Date: Tue, 8 Jul 2025 13:48:58 +0200 Subject: [PATCH 1/2] RHDEVDOCS-6488 --- modules/ob-creating-a-buildpacks-build.adoc | 257 ++++++++++++++++++++ modules/ob-deleting-a-resource.adoc | 21 ++ work_with_builds/using-builds.adoc | 2 + 3 files changed, 280 insertions(+) create mode 100644 modules/ob-creating-a-buildpacks-build.adoc diff --git a/modules/ob-creating-a-buildpacks-build.adoc b/modules/ob-creating-a-buildpacks-build.adoc new file mode 100644 index 000000000000..b5ad43de5327 --- /dev/null +++ b/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 - < + + 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 +---- +<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- --buildref-name buildpack-nodejs-build <1> +---- +<1> Flag referencing the build. + +. Follow the logs: ++ +[source,terminal] +---- +$ shp buildrun logs buildpack-nodej- --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`. +==== \ No newline at end of file diff --git a/modules/ob-deleting-a-resource.adoc b/modules/ob-deleting-a-resource.adoc index 25f0897e7b15..d2386338b1d8 100644 --- a/modules/ob-deleting-a-resource.adoc +++ b/modules/ob-deleting-a-resource.adoc @@ -43,6 +43,20 @@ $ oc delete buildrun $ shp buildrun delete ---- + +* Delete a `BuildRun` resource used by buildpacks by running the following command: ++ +.Using `oc` CLI +[source,terminal] +---- +$ oc delete buildrun +---- ++ +.Using `shp` CLI +[source,terminal] +---- +$ shp delete buildrun +---- ++ * Delete a `BuildStrategy` resource by running the following command: + .Using `oc` CLI @@ -50,3 +64,10 @@ $ shp buildrun delete ---- $ oc delete buildstrategies ---- + +[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]. +==== \ No newline at end of file diff --git a/work_with_builds/using-builds.adoc b/work_with_builds/using-builds.adoc index 4954c1726cb2..5c5fbdb61968 100644 --- a/work_with_builds/using-builds.adoc +++ b/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"] From f28d6a8806e5c4eea54d6902a833cce932c904dc Mon Sep 17 00:00:00 2001 From: deerskindoll Date: Tue, 15 Jul 2025 11:50:59 +0200 Subject: [PATCH 2/2] feedback --- modules/ob-creating-a-buildpacks-build.adoc | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/modules/ob-creating-a-buildpacks-build.adoc b/modules/ob-creating-a-buildpacks-build.adoc index b5ad43de5327..4033fb872473 100644 --- a/modules/ob-creating-a-buildpacks-build.adoc +++ b/modules/ob-creating-a-buildpacks-build.adoc @@ -27,8 +27,15 @@ For more information about the support scope of Red{nbsp}Hat Technology Preview * 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. + +[IMPORTANT] +==== +Using `shp` CLI with buildpacks requires additional permissions setup +you must complete before you start creating a buildpacks build. +==== + .Procedure -. Grant permission to access the image registry in the `buildpacks-example` project to the `pipeline` service with the two following commands: +. OPTIONAL: To use the `shp` CLI with buildpacks, you must first grant permission to the `pipeline` service to access the image registry in the `buildpacks-example` project with the following two commands: + [source,terminal] ---- @@ -39,13 +46,13 @@ $ oc policy add-role-to-user system:image-puller system:serviceaccount:default:p ---- $ oc policy add-role-to-user system:image-pusher system:serviceaccount:default:pipeline --namespace=buildpacks-example ---- -. Switch back to the primary working project: +. OPTIONAL: Continue with `shp` CLI by switching back to the primary working project: + [source,terminal] ---- $ oc project default ---- -. Apply the permission: +. OPTIONAL: Finish `shp` CLI setup by applying the permission: + [source,terminal] ----