From 01afe98294f9b8c5ca50a83a302d17224ec297a2 Mon Sep 17 00:00:00 2001 From: Shivani Sathe Date: Wed, 10 Sep 2025 13:01:47 +0530 Subject: [PATCH] Updated work with builds section for 1.5 --- _topic_maps/_topic_map.yml | 8 +- about/build-strategies.adoc | 6 +- ...b-creating-a-build-with-oci-artifacts.adoc | 45 ++++++++++- modules/ob-creating-a-buildpacks-build.adoc | 63 ++++++++-------- modules/ob-deleting-a-build-resource.adoc | 31 ++++++++ modules/ob-deleting-a-buildrun-resource.adoc | 31 ++++++++ .../ob-deleting-a-buildstrategy-resource.adoc | 20 +++++ modules/ob-deleting-a-resource.adoc | 74 ------------------- modules/ob-deleting-the-resources.adoc | 6 ++ modules/ob-editing-the-resources.adoc | 22 ++++++ ...ing-the-OCI-artifact-by-using-the-CLI.adoc | 18 ----- ...b-uploading-the-OCI-artifact-manually.adoc | 42 ----------- observability/logging.adoc | 13 ++++ ...ler-observability.adoc => monitoring.adoc} | 6 +- .../ob-openshift-builds-release-notes.adoc | 2 +- work_with_builds/using-builds.adoc | 19 +++-- 16 files changed, 222 insertions(+), 184 deletions(-) create mode 100644 modules/ob-deleting-a-build-resource.adoc create mode 100644 modules/ob-deleting-a-buildrun-resource.adoc create mode 100644 modules/ob-deleting-a-buildstrategy-resource.adoc delete mode 100644 modules/ob-deleting-a-resource.adoc create mode 100644 modules/ob-deleting-the-resources.adoc create mode 100644 modules/ob-editing-the-resources.adoc delete mode 100644 modules/ob-uploading-the-OCI-artifact-by-using-the-CLI.adoc delete mode 100644 modules/ob-uploading-the-OCI-artifact-manually.adoc create mode 100644 observability/logging.adoc rename observability/{build-controller-observability.adoc => monitoring.adoc} (81%) diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index ea7f79d90c35..ed57fc4716e8 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -62,7 +62,7 @@ Name: Work with Builds Dir: work_with_builds Distros: openshift-builds Topics: -- Name: Running Builds +- Name: Managing Builds File: using-builds --- Name: Work with Shared Resources @@ -83,8 +83,10 @@ Name: Observability Dir: observability Distros: openshift-builds Topics: -- Name: Build controller observability - File: build-controller-observability +- Name: Logging + File: logging +- Name: Monitoring + File: monitoring --- Name: Uninstall Dir: uninstalling diff --git a/about/build-strategies.adoc b/about/build-strategies.adoc index 13c6247a085e..e2a572097074 100644 --- a/about/build-strategies.adoc +++ b/about/build-strategies.adoc @@ -14,10 +14,8 @@ You can use a curated set of build strategies or cluster build strategies on the * `buildah`: Supported on all platforms * `source-to-image`: Supported on the linux/amd64 platform -[NOTE] -==== -The `buildpacks` build strategy is currently in link:https://access.redhat.com/support/offerings/devpreview[Developer Preview]. For more information, see the link:https://github.com/redhat-developer/openshift-builds-catalog/blob/main/clusterBuildStrategy/buildpacks/README.md[buildpacks example]. -==== +:FeatureName: The `buildpacks` build strategy +include::snippets/technology-preview.adoc[] include::modules/ob-about-buildah.adoc[leveloffset=+1] diff --git a/modules/ob-creating-a-build-with-oci-artifacts.adoc b/modules/ob-creating-a-build-with-oci-artifacts.adoc index 9a9b3cad554e..a1ff71402251 100644 --- a/modules/ob-creating-a-build-with-oci-artifacts.adoc +++ b/modules/ob-creating-a-build-with-oci-artifacts.adoc @@ -46,5 +46,46 @@ EOF <5> Optional: Replace `` with the secret name that stores the credentials for pushing container images. To generate a secret for a private registry for authentication, see link:https://docs.redhat.com/en/documentation/builds_for_red_hat_openshift/1.5/html-single/authentication/index#ob-authentication-to-container-registries_understanding-authentication-at-runtime[Authentication to container registries] . Choose one of the following methods to upload your source code to the required registry and run the build: -.. Use the shp CLI -.. Manually upload the OCI artifact \ No newline at end of file +* 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: ++ +[source,terminal] +---- +$ shp build upload my-oci-build # <1> +---- +<1> Defines the name of the `Build` resource. + +* Upload the OCI artifact manually: + +.. Create a `Containerfile` in the root directory of your source code and add the following configuration: ++ +[source,dockerfile] +---- +FROM scratch +COPY . / +---- + +.. Run the following command in the root directory of your source code to build the container image using Podman: ++ +[source,terminal] +---- +$ podman build -t /: # <1> +---- +<1> Replace /: with the build location for the container image. + +.. Push the container image to the required location using the following command: ++ +[source,terminal] +---- +$ podman push /: # <1> +---- +<1> Replace /: with the location where you want to push the built image. + +.. Run the build using the following command: ++ +[source,terminal] +---- +$ shp build run my-oci-build # <1> +---- +<1> Defines the name of the `Build` resource. diff --git a/modules/ob-creating-a-buildpacks-build.adoc b/modules/ob-creating-a-buildpacks-build.adoc index eb994a8447f6..476f48177d1e 100644 --- a/modules/ob-creating-a-buildpacks-build.adoc +++ b/modules/ob-creating-a-buildpacks-build.adoc @@ -2,8 +2,8 @@ [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 available for {builds-title}: +[role="_abstract"] +You can create a `buildpacks` build and push the created image to the target registry. The following types of `buildpacks` cluster build strategy are available for {builds-title}: * `buildpacks` strategy * `buildpacks-extender` strategy @@ -13,12 +13,8 @@ There are two buildpacks `ClusterBuildStrategy` options available for {builds-ti The `buildpacks-extender` strategy is compatible with the experimental buildpacks `extender` lifecycle phase. You can use this strategy, for example, for builds based on Node.js. However, the `extender` phase does not support Quarkus, or any other Java-based builds. For such builds, you 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]. -==== +:FeatureName: The `buildpacks` build strategy +include::snippets/technology-preview.adoc[] .Prerequisites @@ -64,8 +60,10 @@ $ oc create rolebinding allow-builds-to-push \ --namespace=buildpacks-example ---- -. Create a `Build` resource and apply it to the {ocp-product-title} cluster: -.. Using `oc` CLI + +. Create a `Build` resource and apply it to the {ocp-product-title} cluster by using one of the following CLIs: + +* Using `oc` CLI + [source,terminal] ---- @@ -116,15 +114,16 @@ spec: 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 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. +<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: +* Using `shp` CLI: + [source,terminal] ---- @@ -141,21 +140,25 @@ $ shp build create buildpack-nodejs-build \ --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: + +. Check if the `Build` resource was created by using one of the following CLIs: +* Using `oc` CLI: + [source,terminal] ---- $ oc get builds.shipwright.io buildpack-nodejs-build ---- -.. Using `shp` CLI: + +* Using `shp` CLI: + [source,terminal] ---- $ shp build list ---- -. Create a `BuildRun` resource and apply it to the {ocp-product-title} cluster: -.. .. Using `oc` CLI: + +. Create a `BuildRun` resource and apply it to the {ocp-product-title} cluster by using one of the following CLIs: + +* Using `oc` CLI: + [source,terminal] ---- @@ -170,10 +173,10 @@ spec: name: buildpack-nodejs-build <1> EOF ---- -<1> Reference to the `buildpack-nodejs-build` resource that will be executed. -.. Using `shp` CLI: +<1> Specifies the `buildpack-nodejs-build` resource that will be executed. + +* Using `shp` CLI: + -... [source,terminal] ---- $ shp build run buildpack-nodejs-buildrun --follow @@ -199,14 +202,16 @@ $ shp buildrun create buildpack-nodejs- --buildref-name $ shp buildrun logs buildpack-nodej- --follow ---- ==== -. Check if the `BuildRun` resource was created: -.. Using `oc` CLI: + +. Check if the `BuildRun` resource was created by using one of the following CLIs: +* Using `oc` CLI: + [source,terminal] ---- $ oc get buildrun buildpack-nodejs-buildrun ---- -.. Using `shp` CLI: + +* Using `shp` CLI: + [source,terminal] ---- diff --git a/modules/ob-deleting-a-build-resource.adoc b/modules/ob-deleting-a-build-resource.adoc new file mode 100644 index 000000000000..ca70c807fe82 --- /dev/null +++ b/modules/ob-deleting-a-build-resource.adoc @@ -0,0 +1,31 @@ +:_mod-docs-content-type: PROCEDURE +[id="ob-deleting-a-build-resources_{context}"] += Deleting a build resource + +[role="_abstract"] +You can delete a `build` 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 following CLIs: + +** Using `oc` CLI ++ +[source,terminal] +---- +$ oc delete builds # <1> +---- +<1> Replace with the name of the `build` resource. + +** Using `shp` CLI ++ +[source,terminal] +---- +$ shp build delete # <1> +---- +<1> Replace with the name of the `build` resource. \ No newline at end of file diff --git a/modules/ob-deleting-a-buildrun-resource.adoc b/modules/ob-deleting-a-buildrun-resource.adoc new file mode 100644 index 000000000000..c24b404b8b6b --- /dev/null +++ b/modules/ob-deleting-a-buildrun-resource.adoc @@ -0,0 +1,31 @@ +:_mod-docs-content-type: PROCEDURE +[id="ob-deleting-a-buildrun-resources_{context}"] += Deleting a buildrun resource + +[role="_abstract"] +You can delete a `buildrun` 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 following CLIs: + +** Using `oc` CLI ++ +[source,terminal] +---- +$ oc delete buildrun #<1> +---- +<1> Replace with the name of the `buildrun` resource. + +** Using `shp` CLI ++ +[source,terminal] +---- +$ oc delete buildrun # <1> +---- +<1> Replace with the name of the `buildrun` resource. diff --git a/modules/ob-deleting-a-buildstrategy-resource.adoc b/modules/ob-deleting-a-buildstrategy-resource.adoc new file mode 100644 index 000000000000..04d40ffa0a0d --- /dev/null +++ b/modules/ob-deleting-a-buildstrategy-resource.adoc @@ -0,0 +1,20 @@ +:_mod-docs-content-type: PROCEDURE +[id="ob-deleting-a-buildstrategy-resources_{context}"] += Deleting a buildstrategy resource + +[role="_abstract"] +You can delete a `buildstrategy` resource if it is not required in your project. + +.Prerequisites + +* You have installed the `oc` CLI. + +.Procedure + +* Delete a `buildstrategy` resource by using the `oc` CLI: ++ +[source,terminal] +---- +$ oc delete buildstrategy # <1> +---- +<1> Replace with the name of the `buildstrategy` resource. \ No newline at end of file diff --git a/modules/ob-deleting-a-resource.adoc b/modules/ob-deleting-a-resource.adoc deleted file mode 100644 index c1e90aa2c556..000000000000 --- a/modules/ob-deleting-a-resource.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// This module is included in the following assembly: -// -// * work-with-builds/using-builds.adoc - -:_mod-docs-content-type: PROCEDURE -[id="ob-deleting-a-resource_{context}"] -= Deleting a resource - -[role="_abstract"] -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 -[source,terminal] ----- -$ oc delete builds.shipwright.io ----- -+ -.Using `shp` CLI -[source,terminal] ----- -$ shp build delete ----- -+ -* Delete a `BuildRun` resource by using one of the CLIs: -+ -.Using `oc` CLI -[source,terminal] ----- -$ oc delete buildrun ----- -+ -.Using `shp` CLI -[source,terminal] ----- -$ 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 -[source,terminal] ----- -$ 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/modules/ob-deleting-the-resources.adoc b/modules/ob-deleting-the-resources.adoc new file mode 100644 index 000000000000..9ae6e2e33fd3 --- /dev/null +++ b/modules/ob-deleting-the-resources.adoc @@ -0,0 +1,6 @@ +:_mod-docs-content-type: CONCEPT +[id="ob-deleting-the-resources_{context}"] += Deleting the resources + +You can delete resources created by the Buildah, Source-to-Image (S2I), and Buildpacks build processes using the oc CLI or the shp CLI. Deleting these resources helps you to +clean up build configurations that are no longer required in your project. diff --git a/modules/ob-editing-the-resources.adoc b/modules/ob-editing-the-resources.adoc new file mode 100644 index 000000000000..5f4803c10bbb --- /dev/null +++ b/modules/ob-editing-the-resources.adoc @@ -0,0 +1,22 @@ +:_mod-docs-content-type: PROCEDURE +[id="ob-editing-the-resources_{context}"] += Editing the resources + +[role="_abstract"] +You can edit the resources that are created by `buildah`, `source-to-image` and `buildpacks` build processes using the `oc` CLI. You can modify the resources as needed in your project. + +.Prerequisites + +* You have installed the `oc` CLI. + +.Procedure + +. Run the following command to open the YAML definition in the default editor: ++ +[source,terminal] +---- +$ oc edit # <1> +---- +<1> Replace `` with the name of the resource (`build`, `buildrun` or `buildstrategy`) and `` with the name of the build resource that you want to edit. + +. Edit the YAML definition and save the file. \ No newline at end of file diff --git a/modules/ob-uploading-the-OCI-artifact-by-using-the-CLI.adoc b/modules/ob-uploading-the-OCI-artifact-by-using-the-CLI.adoc deleted file mode 100644 index 892ae4a189d7..000000000000 --- a/modules/ob-uploading-the-OCI-artifact-by-using-the-CLI.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// This module is included in the following assembly: -// -// * work-with-builds/using-builds.adoc - -:_mod-docs-content-type: PROCEDURE -[id="uploading-the-OCI-artifact-by-using-the-CLI_{context}"] -= Uploading the OCI artifact by using the CLI - -[role="_abstract"] -You can upload your source code to the required registry by using the 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: -+ -[source,terminal] ----- -$ shp build upload my-oci-build <1> ----- -<1> Defines the name of the `Build` resource. \ No newline at end of file diff --git a/modules/ob-uploading-the-OCI-artifact-manually.adoc b/modules/ob-uploading-the-OCI-artifact-manually.adoc deleted file mode 100644 index 1d40df0e30e1..000000000000 --- a/modules/ob-uploading-the-OCI-artifact-manually.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// This module is included in the following assembly: -// -// * work-with-builds/using-builds.adoc - -:_mod-docs-content-type: PROCEDURE -[id="uploading-the-OCI-artifact-manually_{context}"] -= Uploading the OCI artifact manually - -[role="_abstract"] -You can upload your source code manually to the required registry and run the build. - -. Create a `Containerfile` in the root directory of your source code and add the following content: -+ -[source,dockerfile] ----- -FROM scratch -COPY . / ----- - -. Run the following command in the root directory of your source code to build the container image using Podman: -+ -[source,terminal] ----- -$ podman build -t /: # <1> ----- -<1> Replace /: with the build location for the container image. - -. Push the container image to the required location using the following command: -+ -[source,terminal] ----- -$ podman push /: # <1> ----- -<1> Replace /: with the location where you want to push the built image. - -. Run the build using the following command: -+ -[source,terminal] ----- -$ shp build run my-oci-build # <1> ----- -<1> Defines the name of the `Build` resource. diff --git a/observability/logging.adoc b/observability/logging.adoc new file mode 100644 index 000000000000..1dc58c4d803a --- /dev/null +++ b/observability/logging.adoc @@ -0,0 +1,13 @@ +:_mod-docs-content-type: ASSEMBLY +[id="logging"] += Logging +include::_attributes/common-attributes.adoc[] +:context: logging + +toc::[] + +[role="_abstract"] +When a build fails or behaves unexpectedly, accessing detailed logs can help you identify the issue. The logs provide information about what happened during the build run. + +include::modules/ob-viewing-logs.adoc[leveloffset=+1] + diff --git a/observability/build-controller-observability.adoc b/observability/monitoring.adoc similarity index 81% rename from observability/build-controller-observability.adoc rename to observability/monitoring.adoc index 778c8ac213f2..73bce308a9b3 100644 --- a/observability/build-controller-observability.adoc +++ b/observability/monitoring.adoc @@ -1,8 +1,8 @@ :_mod-docs-content-type: ASSEMBLY -[id="build-controller-observability"] -= Build controller observability +[id="monitoring"] += Monitoring include::_attributes/common-attributes.adoc[] -:context: build-controller-observability +:context: monitoring toc::[] diff --git a/release_notes/ob-openshift-builds-release-notes.adoc b/release_notes/ob-openshift-builds-release-notes.adoc index 8c036066e71a..bfc7aa528712 100644 --- a/release_notes/ob-openshift-builds-release-notes.adoc +++ b/release_notes/ob-openshift-builds-release-notes.adoc @@ -1,6 +1,6 @@ :_mod-docs-content-type: ASSEMBLY -include::_attributes/common-attributes.adoc[] [id="ob-openshift-builds-release-notes"] +include::_attributes/common-attributes.adoc[] = {builds-title-uppercase} release notes :context: ob-openshift-builds-release-notes diff --git a/work_with_builds/using-builds.adoc b/work_with_builds/using-builds.adoc index f69b875acee4..e7ff3d204b79 100644 --- a/work_with_builds/using-builds.adoc +++ b/work_with_builds/using-builds.adoc @@ -1,7 +1,7 @@ :_mod-docs-content-type: ASSEMBLY -[id="using-builds"] +[id="managing-builds"] include::_attributes/common-attributes.adoc[] -= Running {builds-shortname} += Managing {builds-shortname} :context: using-builds toc::[] @@ -18,17 +18,20 @@ include::modules/ob-creating-a-s2i-build.adoc[leveloffset=+1] include::modules/ob-creating-s2i-build-in-a-network-restricted-environment.adoc[leveloffset=+2] -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] include::modules/ob-creating-a-build-with-oci-artifacts.adoc[leveloffset=+1] -include::modules/ob-uploading-the-OCI-artifact-by-using-the-CLI.adoc[leveloffset=+2] +include::modules/ob-editing-the-resources.adoc[leveloffset=+1] + +include::modules/ob-deleting-the-resources.adoc[leveloffset=+1] + +include::modules/ob-deleting-a-build-resource.adoc[leveloffset=+2] + +include::modules/ob-deleting-a-buildrun-resource.adoc[leveloffset=+2] + +include::modules/ob-deleting-a-buildstrategy-resource.adoc[leveloffset=+2] -include::modules/ob-uploading-the-OCI-artifact-manually.adoc[leveloffset=+2] [role="_additional-resources"] [id="additional-resources_using-builds"]