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/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 a3f8516f6374..8306a313593a 100644 --- a/modules/ob-creating-a-buildpacks-build.adoc +++ b/modules/ob-creating-a-buildpacks-build.adoc @@ -2,6 +2,7 @@ [id="ob-creating-a-buildpacks-build_{context}"] = Creating a buildpacks build +[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 @@ -60,7 +61,8 @@ $ oc create rolebinding allow-builds-to-push \ ---- . Create a `Build` resource and apply it to the {ocp-product-title} cluster by using one of the following CLIs: -.. Using `oc` CLI + +* Using `oc` CLI + [source,terminal] ---- @@ -118,8 +120,9 @@ EOF <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] ---- @@ -138,13 +141,14 @@ $ shp build create buildpack-nodejs-build \ ---- . Check if the `Build` resource was created by using one of the following CLIs: -.. Using `oc` CLI: +* Using `oc` CLI: + [source,terminal] ---- $ oc get builds.shipwright.io buildpack-nodejs-build ---- -.. Using `shp` CLI: + +* Using `shp` CLI: + [source,terminal] ---- @@ -152,7 +156,8 @@ $ shp build list ---- . Create a `BuildRun` resource and apply it to the {ocp-product-title} cluster by using one of the following CLIs: -.. Using `oc` CLI: + +* Using `oc` CLI: + [source,terminal] ---- @@ -168,7 +173,8 @@ spec: EOF ---- <1> Specifies the `buildpack-nodejs-build` resource that will be executed. -.. Using `shp` CLI: + +* Using `shp` CLI: + [source,terminal] ---- @@ -197,13 +203,14 @@ $ shp buildrun logs buildpack-nodej- --follow ==== . Check if the `BuildRun` resource was created by using one of the following CLIs: -.. Using `oc` CLI: +* 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..e1d86c2b6729 --- /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. \ No newline at end of file diff --git a/modules/ob-editing-the-resources.adoc b/modules/ob-editing-the-resources.adoc new file mode 100644 index 000000000000..dcc1f7940e91 --- /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 9e3c9d6f65b5..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::[] @@ -22,13 +22,16 @@ 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-uploading-the-OCI-artifact-manually.adoc[leveloffset=+2] +include::modules/ob-deleting-the-resources.adoc[leveloffset=+1] -include::modules/ob-viewing-logs.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-deleting-a-resource.adoc[leveloffset=+1] [role="_additional-resources"] [id="additional-resources_using-builds"]