From 58dda619d3fe4452aa5d344261b0605d80f1adf2 Mon Sep 17 00:00:00 2001 From: Shivani Sathe Date: Tue, 14 Oct 2025 16:51:13 +0530 Subject: [PATCH] updated content as per CQA --- _topic_maps/_topic_map.yml | 10 +- ...s-in-a-network-restricted-environment.adoc | 22 --- installing/installing-openshift-builds.adoc | 2 +- ...b-creating-a-build-with-oci-artifacts.adoc | 164 +++++++++++++++--- ...d-in-a-network-restricted-environment.adoc | 34 ++++ modules/ob-creating-a-buildah-build.adoc | 90 +++++++--- modules/ob-creating-a-buildpacks-build.adoc | 130 +++++++------- ...d-in-a-network-restricted-environment.adoc | 35 ++++ modules/ob-creating-a-s2i-build.adoc | 101 +++++++---- ...d-in-a-network-restricted-environment.adoc | 27 --- ...d-in-a-network-restricted-environment.adoc | 27 --- modules/ob-deleting-a-build-resource.adoc | 34 +++- modules/ob-deleting-a-buildrun-resource.adoc | 35 +++- .../ob-deleting-a-buildstrategy-resource.adoc | 31 +++- modules/ob-deleting-the-resources.adoc | 7 - modules/ob-editing-the-resources.adoc | 8 +- modules/ob-verifying-cluster-wide-proxy.adoc | 21 --- modules/ob-verifying-proxy-details.adoc | 69 ++++++++ ...verifying-proxy-environment-variables.adoc | 28 --- ...s-in-a-network-restricted-environment.adoc | 27 +++ .../creating-container-images.adoc | 27 +++ work_with_builds/docinfo.xml | 4 +- work_with_builds/managing-builds.adoc | 26 +++ work_with_builds/using-builds.adoc | 43 ----- 24 files changed, 654 insertions(+), 348 deletions(-) delete mode 100644 configuring/using-builds-in-a-network-restricted-environment.adoc create mode 100644 modules/ob-creating-a-buildah-build-in-a-network-restricted-environment.adoc create mode 100644 modules/ob-creating-a-s2i-build-in-a-network-restricted-environment.adoc delete mode 100644 modules/ob-creating-buildah-build-in-a-network-restricted-environment.adoc delete mode 100644 modules/ob-creating-s2i-build-in-a-network-restricted-environment.adoc delete mode 100644 modules/ob-deleting-the-resources.adoc delete mode 100644 modules/ob-verifying-cluster-wide-proxy.adoc create mode 100644 modules/ob-verifying-proxy-details.adoc delete mode 100644 modules/ob-verifying-proxy-environment-variables.adoc create mode 100644 work_with_builds/creating-container-images-in-a-network-restricted-environment.adoc create mode 100644 work_with_builds/creating-container-images.adoc create mode 100644 work_with_builds/managing-builds.adoc delete mode 100644 work_with_builds/using-builds.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index ed57fc4716e8..67adc0fb99e6 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -55,15 +55,17 @@ Topics: File: configuring-build-strategies - Name: Configuring build runs File: configuring-build-runs -- Name: Using Builds in a network-restricted environment - File: using-builds-in-a-network-restricted-environment --- Name: Work with Builds Dir: work_with_builds Distros: openshift-builds Topics: -- Name: Managing Builds - File: using-builds +- Name: Creating container images + File: creating-container-images +- Name: Creating container images in a network restricted environment + File: creating-container-images-in-a-network-restricted-environment +- Name: Managing builds + File: managing-builds --- Name: Work with Shared Resources Dir: work_with_shared_resources diff --git a/configuring/using-builds-in-a-network-restricted-environment.adoc b/configuring/using-builds-in-a-network-restricted-environment.adoc deleted file mode 100644 index 041a93b1bf89..000000000000 --- a/configuring/using-builds-in-a-network-restricted-environment.adoc +++ /dev/null @@ -1,22 +0,0 @@ -:_mod-docs-content-type: ASSEMBLY -include::_attributes/common-attributes.adoc[] -[id="using-builds-in-a-network-restricted-environment"] -= Using {builds-shortname} in a network-restricted environment - -:context: using-builds-in-a-network-restricted-environment - -toc::[] - -[role="_abstract"] -The {pipelines-operator} provides support for injecting the proxy environment variables in the network-restricted environments. - -include::modules/ob-verifying-cluster-wide-proxy.adoc[leveloffset=+1] - -include::modules/ob-verifying-proxy-environment-variables.adoc[leveloffset=+1] - -[role="_additional-resources"] -[id="additional-resources_using-builds"] -== Additional resources - -* link:https://docs.openshift.com/pipelines/1.16/install_config/installing-pipelines.html#op-pipelines-operator-in-restricted-environment_installing-pipelines[Red Hat OpenShift Pipelines Operator in a restricted environment] -* link:https://docs.openshift.com/container-platform/4.17/networking/enable-cluster-wide-proxy.html[Configuring cluster-wide proxy] diff --git a/installing/installing-openshift-builds.adoc b/installing/installing-openshift-builds.adoc index b24bee76531b..2eed77de09cb 100644 --- a/installing/installing-openshift-builds.adoc +++ b/installing/installing-openshift-builds.adoc @@ -20,4 +20,4 @@ include::modules/ob-disabling-shipwrightBuilds-components.adoc[leveloffset=+1] == Additional resources * link:https://docs.openshift.com/container-platform/latest/operators/admin/olm-adding-operators-to-cluster.html#olm-adding-operators-to-a-cluster[Adding Operators to a cluster] -* xref:../work_with_builds/using-builds.adoc[Managing Builds] +* xref:../work_with_builds/creating-container-images.adoc[Creating container images] diff --git a/modules/ob-creating-a-build-with-oci-artifacts.adoc b/modules/ob-creating-a-build-with-oci-artifacts.adoc index a1ff71402251..36321c0347ef 100644 --- a/modules/ob-creating-a-build-with-oci-artifacts.adoc +++ b/modules/ob-creating-a-build-with-oci-artifacts.adoc @@ -3,11 +3,11 @@ // * work-with-builds/using-builds.adoc :_mod-docs-content-type: PROCEDURE -[id="Creating-a-build-with-OCI-artifacts_{context}"] +[id="ob-creating-a-build-with-OCI-artifacts_{context}"] = Creating a build with OCI artifacts [role="_abstract"] -You can create a build using an Open Container Initiative(OCI) artifact as your source code. An OCI artifact, also known as a scratch image, contains only the source code and is not intended to run as a container. You can pull the OCI artifact from a container registry and extract its contents to use as source code to run the build. +Use Open Container Initiative (OCI) artifacts, also called scratch images, that you store in a registry as source code to build a container image. Pull and extract them to use as the source for your build; they contain only source code, not a runnable container. .Prerequisites @@ -25,36 +25,42 @@ $ oc apply -f - < + name: spec: source: type: OCI ociArtifact: - image: #<2> + image: strategy: - name: # <3> + name: kind: ClusterBuildStrategy output: - image: #<4> - pushSecret: #<5> + image: + pushSecret: EOF ---- -<1> Defines the name of the `Build` resource. -<2> Replace `` with the location of the OCI artifact source image. -<3> Replace `` with the name of the build strategy to build the container (`buildah` or `source-to-image`). -<4> Replace `` with the location where you want to push the built image. -<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] ++ +where: + +``:: Specifies the name of the `Build` resource. +``:: Specifies the location of the OCI artifact source image. +``:: Specifies the name of the build strategy to build the container. +``:: Specifies the location where you want to push the built image. +``:: (Optional) Specifies 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: +* Upload the source code using 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> +$ shp build upload ---- -<1> Defines the name of the `Build` resource. ++ +where: + +``:: Specifies the name of the `Build` resource. * Upload the OCI artifact manually: @@ -70,22 +76,138 @@ COPY . / + [source,terminal] ---- -$ podman build -t /: # <1> +$ podman build -t /: . +---- ++ +where: + +``:: Specifies the build location for the registry where the image is stored. +``:: Specifies the name of the container image. +``:: Specifies the tag of the image. ++ + +When the container image is built successfully, a success message is displayed. See the following example command and output: ++ +[source,terminal] +---- +podman build -t quay.io/example/oci:latest . +---- ++ +[source,terminal] +---- +STEP 1/2: FROM scratch +STEP 2/2: COPY . / +--> Using cache 31f2530b092a8e0d75586407052900e9946043eca09deb9a2c9e50c2541bfcfd +COMMIT quay.io/example/oci:latest +--> 31f2530b092a +Successfully tagged quay.io/example/oci:latest +31f2530b092a8e0d75586407052900e9946043eca09deb9a2c9e50c2541bfcfd ---- -<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> +$ podman push /: ---- -<1> Replace /: with the location where you want to push the built image. ++ +where: + +``:: Specifies the build location for the registry where the image is stored. +``:: Specifies the name of the container image. +``:: Specifies the tag of the image. .. Run the build using the following command: + [source,terminal] ---- -$ shp build run my-oci-build # <1> +$ shp build run +---- ++ +where: + +``:: Specifies the name of the `Build` resource. + +.Verification + +After all the containers complete their tasks, verify the statuses of the following resources: + +. Check whether the pod shows the `STATUS` field as `Completed`: ++ +[source,terminal] +---- +$ oc get pods -w +---- ++ +Example output: ++ +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +oci-artifact-buildrun-pxg9w-pod 2/2 Running 0 58s +oci-artifact-buildrun-pxg9w-pod 0/2 Completed 0 1m42s +---- + +. Check whether the respective `TaskRun` resource shows the `SUCCEEDED` field as `True`: ++ +[source,terminal] +---- +$ oc get tr +---- ++ +Example output: ++ +[source,terminal] +---- +NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME +oci-artifact-buildrun-pxg9w True Succeeded 2m10s 28s +---- + +. Check whether the respective `BuildRun` resource shows the `SUCCEEDED` field as `True`: ++ +[source,terminal] +---- +$ oc get br +---- ++ +Example output: ++ +[source,terminal] +---- +NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME +oci-artifact-buildrun True Succeeded 2m12s 30s +---- + +. 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. +==== + +. Validate whether the image has been pushed to the registry that is specified in the `build.spec.output.image` field. Log in to the registry and run the following command to pull the image: ++ +[source,terminal] +---- +$ podman manifest inspect image-registry.openshift-image-registry.svc:5000/oci-artifacts-example/taxi-app +---- ++ +In the previous example, the project name is `oci-artifacts-example`, and the image name is `taxi-app`. ++ +Example output: ++ +[source,terminal] +---- + "schemaVersion": 2, + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "manifests": [ + { + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "size": 594, + "digest": "sha256:6a05100e302c86c03fec6277f4b3107f1fdde6c69d3ca9a4207e4735a5213e32", + "platform": { + "architecture": "amd64", + "os": "linux" + } + ] ---- -<1> Defines the name of the `Build` resource. diff --git a/modules/ob-creating-a-buildah-build-in-a-network-restricted-environment.adoc b/modules/ob-creating-a-buildah-build-in-a-network-restricted-environment.adoc new file mode 100644 index 000000000000..cba5a107758c --- /dev/null +++ b/modules/ob-creating-a-buildah-build-in-a-network-restricted-environment.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +//* builds/work-with-builds.adoc + +:_mod-docs-content-type: PROCEDURE +[id='ob-creating-a-buildah-build-in-a-network-restricted-environment_{context}'] += Creating a buildah build in a network-restricted environment + +[role="_abstract"] +Create a `buildah` build in a network-restricted environment by mirroring the images that `buildah` build strategy requires. Mirroring the images eliminates the need for public registry access. This ensures clusters use only images that comply with external content controls. + +.Prerequisites + +* You have installed the `oc` CLI. +* Your cluster can connect and interact with the Git source that you can use to create the buildah build. +* You have the builder-image required to create the `buildah` build in your local registry. If the builder-image is not present in the local registry, mirror the source image. + +.Procedure + +. Run the following command to mirror the images that `buildah` build strategy requires: ++ +[source,terminal] +---- +$ oc image mirror --insecure -a registry.redhat.io/ubi8/buildah@sha256:1c89cc3cab0ac0fc7387c1fe5e63443468219aab6fd531c8dad6d22fd999819e //ubi8_buildah +---- ++ +where: + +``:: Specifies the authentication credentials used to access a container registry. This is required when pushing to or pulling from a private registry. +``:: Specifies the registry where the image you want to mirror is stored. +``:: Specifies the name of the image. +``:: Specifies the tag of the image. + +. Perform the steps mentioned in the "Creating a buildah build" section. \ No newline at end of file diff --git a/modules/ob-creating-a-buildah-build.adoc b/modules/ob-creating-a-buildah-build.adoc index c9ea0c834e99..6c44934cf4a3 100644 --- a/modules/ob-creating-a-buildah-build.adoc +++ b/modules/ob-creating-a-buildah-build.adoc @@ -7,7 +7,7 @@ = Creating a buildah build [role="_abstract"] -You can create a `buildah` build and push the created image to the target registry. +Use a `buildah` build strategy to build and push a container image using a Dockerfile. .Prerequisites @@ -28,39 +28,48 @@ kind: Build metadata: name: buildah-golang-build spec: - source: # <1> + source: type: Git git: url: https://github.com/shipwright-io/sample-go contextDir: docker-build - strategy: # <2> + strategy: name: buildah kind: ClusterBuildStrategy - paramValues: # <3> + paramValues: - name: dockerfile value: Dockerfile - output: # <4> + output: image: image-registry.openshift-image-registry.svc:5000/buildah-example/sample-go-app EOF ---- -<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 {ocp-product-title} cluster internal registry. `buildah-example` is the name of the current project. Ensure that the specified project exists to allow the image push. ++ +-- +where: + +`source`:: Defines the location where the source code is placed. +`strategy`:: Defines the build strategy that you use to build the container. +`paramValues`:: Defines 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. +`output`:: Defines the location where the built image is pushed. In this procedural example, the built image is pushed to the {ocp-product-title} cluster internal registry. `buildah-example` is the name of the current project. Ensure that the specified project exists to allow the image push. +-- + [source,terminal] ---- $ 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> +--source-url="https://github.com/redhat-openshift-builds/samples" +--source-context-dir="buildah-build" \ +--strategy-name="buildah" \ +--dockerfile="Dockerfile" \ +--output-image="image-registry.openshift-image-registry.svc:5000/buildah-example/go-app" ---- -<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 {ocp-product-title} cluster internal registry. `buildah-example` is the name of the current project. Ensure that the specified project exists to allow the image push. ++ +where: + +`source-context-dir`:: Defines the location where the source code is placed. +`strategy-name`:: Defines the build strategy that you use to build the container. +`dockerfile`:: Defines the parameter defined in the build strategy. To set the value of the `dockerfile` strategy parameter, specifies the Dockerfile location required to build the output image. +`output-image`:: Defines the location where the built image is pushed. In this procedural example, the built image is pushed to the {ocp-product-title} cluster internal registry. `buildah-example` is the name of the current project. Ensure that the specified project exists to allow the image push. . Check if the `Build` resource is created. You can do so by using the `oc` command or the `shp` command: @@ -87,17 +96,20 @@ metadata: name: buildah-golang-buildrun spec: build: - name: buildah-golang-build # <1> + name: buildah-golang-build EOF ---- -<1> The `spec.build.name` field denotes the respective build to run, which is expected to be available in the same namespace. ++ +where: + +`spec.build.name`:: Defines the build to run, which is expected to be available in the same namespace. + [source,terminal] ---- -$ shp build run buildah-golang-build --follow # <1> +$ shp build run buildah-golang-build --follow ---- -<1> Optional: By using the `--follow` flag, you can view the build logs in the output result. +* `--follow`:: (Optional) Use the `--follow` flag to view the build logs in the output result. . Check if the `BuildRun` resource is created. You can do so by using the `oc` command or the `shp` command: @@ -117,7 +129,7 @@ The `BuildRun` resource creates a `TaskRun` resource, which then creates the pod .Verification -After all the containers complete their tasks, verify the following: +After all the containers complete their tasks, verify the following resources: . Check whether the pod shows the `STATUS` field as `Completed`: + @@ -126,7 +138,8 @@ After all the containers complete their tasks, verify the following: $ oc get pods -w ---- + -.Example output +Example output: ++ [source,terminal] ---- NAME READY STATUS RESTARTS AGE @@ -142,7 +155,8 @@ buildah-golang-buildrun-dtrg2-pod 0/2 Completed 0 55s $ oc get tr ---- + -.Example output +Example output: ++ [source,terminal] ---- NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME @@ -156,7 +170,8 @@ buildah-golang-buildrun-dtrg2 True Succeeded 11m 8m51s $ oc get br ---- + -.Example output +Example output: ++ [source,terminal] ---- NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME @@ -170,10 +185,29 @@ buildah-golang-buildrun True Succeeded 13m 11m The pod might switch to a `NotReady` state because one of the containers has completed its task. This is an expected behavior. ==== -. 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: +. Validate whether the image has been pushed to the registry that is specified in the `build.spec.output.image` field. Run the following command to pull the image from a node that can access the internal registry: + [source,terminal] ---- -$ podman pull image-registry.openshift-image-registry.svc:5000// # <1> +$ podman manifest inspect image-registry.openshift-image-registry.svc:5000/buildah-example/taxi-app +---- ++ +In the previous example, the project name is `buildah-example`, and the image name is `taxi-app`. ++ +Example output: ++ +[source,terminal] ---- -<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. \ No newline at end of file + "schemaVersion": 2, + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "manifests": [ + { + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "size": 594, + "digest": "sha256:6a05100e302c86c03fec6277f4b3107f1fdde6c69d3ca9a4207e4735a5213e32", + "platform": { + "architecture": "amd64", + "os": "linux" + } + ] +---- \ No newline at end of file diff --git a/modules/ob-creating-a-buildpacks-build.adoc b/modules/ob-creating-a-buildpacks-build.adoc index 8fd43e63deaa..219dc673db0d 100644 --- a/modules/ob-creating-a-buildpacks-build.adoc +++ b/modules/ob-creating-a-buildpacks-build.adoc @@ -3,19 +3,11 @@ = 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 -* `buildpacks-extender` strategy - -[NOTE] -==== -The `buildpacks-extender` strategy is compatible with the experimental buildpacks extender lifecycle phase. You can use this strategy for {builds-shortname} on Node.js and Python. For {builds-shortname} on Quarkus and Golang, use the `buildpacks` strategy. -==== +Use a `buildpacks` build to create and push container images to the target registry. The `buildpacks` cluster build strategy supports `buildpacks` and `buildpacks-extender` strategies. [IMPORTANT] ==== -{builds-title-uppercase} supports the execution process for Cloud Native Buildpacks within the build strategies. Since the builder and runtime images are provided by the {builds-shortname} users, Red Hat does not provide support for these images. +{builds-title-uppercase} supports the execution process for Cloud Native Buildpacks (CNB) within the build strategies. Red{nbsp}Hat does not provide support for the content of user-provided builder and runtime images. For more information on Cloud Native Buildpacks (CNB), see link:https://buildpacks.io/[Cloud Native Buildpacks]. ==== .Prerequisites @@ -23,7 +15,7 @@ The `buildpacks-extender` strategy is compatible with the experimental buildpack * 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 is stored by using the command `oc new-project buildpacks-example`. -* Optional: You have installed the `shp` CLI. +* Optional: You have installed the link:https://console.redhat.com/openshift/downloads[`shp` CLI]. [IMPORTANT] ==== @@ -33,7 +25,7 @@ you must complete before you start creating a buildpacks build. .Procedure -. 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: +. Optional: Run the following commands to use the `shp` CLI with `buildpacks` and grant the `pipeline` service account permission to access the image registry in the `buildpacks-example` project. + [source,terminal] ---- @@ -52,7 +44,7 @@ $ oc policy add-role-to-user system:image-pusher system:serviceaccount:default:p $ oc project default ---- -. Optional: Finish `shp` CLI setup by applying the permission: +. Optional: Run the following command to apply the permission and finish `shp` CLI setup: + [source,terminal] ---- @@ -71,72 +63,49 @@ $ oc create rolebinding allow-builds-to-push \ ---- $ oc apply -f - < - + source: type: Git - git: - url: https://github.com/redhat-openshift-builds/samples.git - - strategy: <2> - + strategy: name: buildpacks - kind: ClusterBuildStrategy - retention: - atBuildDeletion: true - - paramValues: <3> - - - name: run-image <4> - + paramValues: + - name: run-image value: paketobuildpacks/run-ubi8-base:latest - - - name: cnb-builder-image <5> - + - name: cnb-builder-image value: paketobuildpacks/builder-jammy-tiny:0.0.344 - - - name: source-subpath <6> - + - name: source-subpath value: "buildpacks/nodejs" - - output: <7> + output: image: image-registry.openshift-image-registry.svc:5000/buildpacks-example/taxi-app EOF ---- -<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. ++ +where: + +`source`:: Specifies the Git repository containing your application source code. +`strategy`:: Specifies the build strategy to build the container. +`paramValues`:: Specifies the parameters set for the buildpacks strategy. +`name: run-image`:: Specifies the base image on which your application runs. +`name: cnb-builder-image`:: Specifies the builder image used by Cloud Native Buildpacks (CNB) to detect and build your application. +`name: source-subpath`:: Specifies the subdirectory within your Git repository where the application source code is located. +`output`:: Specifies the location where the built image is pushed. + [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" ---- @@ -166,16 +135,22 @@ metadata: namespace: builds-test spec: build: - name: buildpack-nodejs-build <1> + name: buildpack-nodejs-build EOF ---- -<1> Specifies the `buildpack-nodejs-build` resource that will be executed. ++ +where: + +`spec.build.name`:: Specifies the `buildpack-nodejs-build` resource that will be executed. + +-- [source,terminal] ---- $ shp build run buildpack-nodejs-buildrun --follow ---- +-- + + [IMPORTANT] ==== @@ -186,9 +161,14 @@ You must create the name manually: + [source,terminal] ---- -$ shp buildrun create buildpack-nodejs- --buildref-name buildpack-nodejs-build <1> +$ shp buildrun create buildpack-nodejs- --buildref-name buildpack-nodejs-build ---- -<1> Specifies the flag referencing the build. ++ +where: + +``:: Specifies the buildrun resource name + +`--buildref-name buildpack-nodejs-build`:: Defines the flag referencing the build. . Follow the logs: + @@ -210,6 +190,7 @@ $ oc get buildrun buildpack-nodejs-buildrun ---- $ shp buildrun list ---- + + [NOTE] ==== @@ -227,7 +208,8 @@ The `BuildRun` resource creates a `TaskRun` resource, which then creates the pod $ oc get pods -w ---- + -.Example output +Example output: ++ [source,terminal] ---- NAME READY STATUS RESTARTS AGE @@ -243,7 +225,8 @@ buildpack-go-build-ttwkl-d8x97-pod 0/8 Completed 0 73s $ oc get tr ---- + -.Example output +Example output: ++ [source,terminal] ---- NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME @@ -257,7 +240,8 @@ buildpack-go-build-ttwkl-d8x97 True Succeeded 112s 38s $ oc get br ---- + -.Example output +Example output: ++ [source,terminal] ---- NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME @@ -271,17 +255,29 @@ If the build run fails, you can check the `status.failureDetails` field in your 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: +. Run the following command from a node that can access internal registry to pull the image to check if the image has been pushed to the registry you specified in the `build.spec.output.image` field: + [source,terminal] ---- -$ podman pull +$ podman manifest inspect image-registry.openshift-image-registry.svc:5000/buildpacks-example/taxi-app ---- + -.Example output +In the previous example, the project name is `buildpacks-example`, and the image name is `taxi-app`. ++ +Example output: ++ [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 + "schemaVersion": 2, + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "manifests": [ + { + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "size": 594, + "digest": "sha256:6a05100e302c86c03fec6277f4b3107f1fdde6c69d3ca9a4207e4735a5213e32", + "platform": { + "architecture": "amd64", + "os": "linux" + } + ] +---- \ No newline at end of file diff --git a/modules/ob-creating-a-s2i-build-in-a-network-restricted-environment.adoc b/modules/ob-creating-a-s2i-build-in-a-network-restricted-environment.adoc new file mode 100644 index 000000000000..70be6add720a --- /dev/null +++ b/modules/ob-creating-a-s2i-build-in-a-network-restricted-environment.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * builds/work-with-builds.adoc + +:_mod-docs-content-type: PROCEDURE +[id='ob-creating-a-source-to-image-build-in-a-network-restricted-environment_{context}'] += Creating a source-to-image build in a network-restricted environment + +[role="_abstract"] +Create a `source-to-image` build in a network-restricted environment by mirroring the images that `source-to-image` build strategy requires. Mirroring the images eliminates the need for public registry access. This ensures clusters use only images that comply with external content controls. + +.Prerequisites + +* You have installed the `oc` CLI. +* Your cluster can connect and interact with the Git source used to create the `source-to-image` build. +* You have the builder-image required to create the `source-to-image` build in your local registry. If the builder-image is not present in the local registry, mirror the source image. + +.Procedure + +. Run the following command to mirror the images that `source-to-image` build strategy requires: ++ +[source,terminal] +---- +$ oc image mirror --insecure -a registry.redhat.io/source-to-image/source-to-image-rhel8@sha256:d041c1bbe503d152d0759598f79802e257816d674b342670ef61c6f9e6d401c5 //source-to-image-source-to-image-rhel8 +---- ++ +where: + +``:: Specifies the authentication credentials used to access a container registry. This is required when pushing to or pulling from a private registry. +``:: Specifies the registry where the image you want to mirror is stored. +``:: Specifies the name of the mirror image. +``:: Specifies the tag of the image. + + +. Perform the steps mentioned in the "Creating a source-to-image build" section. \ No newline at end of file diff --git a/modules/ob-creating-a-s2i-build.adoc b/modules/ob-creating-a-s2i-build.adoc index 1b311f488d03..07fedca4cd4a 100644 --- a/modules/ob-creating-a-s2i-build.adoc +++ b/modules/ob-creating-a-s2i-build.adoc @@ -7,7 +7,7 @@ = Creating a source-to-image build [role="_abstract"] -You can create a `source-to-image` build and push the created image to a custom Quay repository. +Use a `source-to-image`(S2I) build strategy to turn application source code into a container image using a base image. .Prerequisites @@ -27,43 +27,51 @@ kind: Build metadata: name: s2i-nodejs-build spec: - source: # <1> + source: type: Git git: url: https://github.com/redhat-openshift-builds/samples contextDir: s2i-build/nodejs - strategy: # <2> + strategy: name: source-to-image kind: ClusterBuildStrategy - paramValues: # <3> + paramValues: - name: builder-image value: quay.io/centos7/nodejs-12-centos7:master output: - image: quay.io//s2i-nodejs-example # <4> - pushSecret: registry-credential # <5> + image: quay.io//s2i-nodejs-example + pushSecret: registry-credential EOF ---- -<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". ++ +-- +where: + +`source`:: Defines the location where the source code is placed. +`strategy`:: Defines the build strategy that you use to build the container. +`paramValues`:: Defines 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. +`output`:: Defines the location where the built image is pushed. In this procedural example, the built image is pushed to the {ocp-product-title} cluster internal registry. `buildah-example` is the name of the current project. Ensure that the specified project exists to allow the image push. +`pushSecret`:: Defines 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". +-- + [source,terminal] ---- $ 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//s2i-nodejs-example" \// # <4> ---output-credentials-secret="registry-credential" # <5> ----- -<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". +--source-url="https://github.com/redhat-openshift-builds/samples" --source-context-dir="s2i-build/nodejs" \ +--strategy-name="source-to-image" \ +--builder-image="quay.io/centos7/nodejs-12-centos7" \ +--output-image="quay.io//s2i-nodejs-example" \ +--output-credentials-secret="registry-credential" +---- ++ +where: + +`source-context-dir`:: Defines the location where the source code is placed. +`strategy-name`:: The build strategy that you use to build the container. +`dockerfile`:: 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. +`output-image`:: The location where the built image is pushed. In this procedural example, the built image is pushed to the {ocp-product-title} cluster internal registry. `buildah-example` is the name of the current project. Ensure that the specified project exists to allow the image push. +`output-credentials-secret`:: 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". . Check if the `Build` resource is created. You can do so by using the `oc` command or the `shp` command: + @@ -89,17 +97,23 @@ metadata: name: s2i-nodejs-buildrun spec: build: - name: s2i-nodejs-build # <1> + name: s2i-nodejs-build EOF ---- -<1> The `spec.build.name` field denotes the respective build to run, which is expected to be available in the same namespace. ++ +where: + +`spec.build.name`:: Specifies the respective build to run, which is expected to be available in the same namespace. + [source,terminal] ---- -$ shp build run s2i-nodejs-build --follow # <1> +$ shp build run s2i-nodejs-build --follow ---- -<1> Optional: By using the `--follow` flag, you can view the build logs in the output result. ++ +where: + +`--follow`:: (Optional) Use the `--follow` flag to view the build logs in the output result. . Check if the `BuildRun` resource is created. You can do so by using the `oc` command or the `shp` command: + @@ -118,7 +132,7 @@ The `BuildRun` resource creates a `TaskRun` resource, which then creates the pod .Verification -After all the containers complete their tasks, verify the following: +After all the containers complete their tasks, verify the statuses of the following resources: . Check whether the pod shows the `STATUS` field as `Completed`: + @@ -127,7 +141,8 @@ After all the containers complete their tasks, verify the following: $ oc get pods -w ---- + -.Example output +Example output: ++ [source,terminal] ---- NAME READY STATUS RESTARTS AGE @@ -143,7 +158,8 @@ s2i-nodejs-buildrun-phxxm-pod 0/2 Completed 0 2m $ oc get tr ---- + -.Example output +Example output: ++ [source,terminal] ---- NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME @@ -157,7 +173,8 @@ s2i-nodejs-buildrun-phxxm True Succeeded 2m39s 13s $ oc get br ---- + -.Example output +Example output: ++ [source,terminal] ---- NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME @@ -171,10 +188,28 @@ s2i-nodejs-buildrun True Succeeded 2m41s 15s The pod might switch to a `NotReady` state because one of the containers has completed its task. This is an expected behavior. ==== -. 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: +. Validate whether the image has been pushed to the registry that is specified in the `build.spec.output.image` field. Log in to the registry and run the following command to pull the image: ++ +[source,terminal] +---- +$ podman manifest inspect image-registry.openshift-image-registry.svc:5000/s2i-example/taxi-app +---- +In the previous example, the project name is `s2i-example`, and the image name is `taxi-app`. ++ +Example output: + [source,terminal] ---- -$ podman pull quay.io// <1> + "schemaVersion": 2, + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "manifests": [ + { + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "size": 594, + "digest": "sha256:6a05100e302c86c03fec6277f4b3107f1fdde6c69d3ca9a4207e4735a5213e32", + "platform": { + "architecture": "amd64", + "os": "linux" + } + ] ---- -<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. \ No newline at end of file diff --git a/modules/ob-creating-buildah-build-in-a-network-restricted-environment.adoc b/modules/ob-creating-buildah-build-in-a-network-restricted-environment.adoc deleted file mode 100644 index 5524ad0c45d7..000000000000 --- a/modules/ob-creating-buildah-build-in-a-network-restricted-environment.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/work-with-builds.adoc - -:_mod-docs-content-type: PROCEDURE -[id='ob-creating-buildah-build-in-a-network-restricted-environment_{context}'] -= Creating buildah build in a network-restricted environment - -[role="_abstract"] -You can create a `buildah` build in a network-restricted environment by mirroring the images required by the `buildah` build strategy. - -.Prerequisites - -* Your cluster can connect and interact with the git source that you can use to create the buildah build. - -.Procedure - -. Run the following command to mirror the images required by the `buildah` build strategy: -+ -[source,terminal] ----- -$ oc image mirror --insecure -a registry.redhat.io/ubi8/buildah@sha256:1c89cc3cab0ac0fc7387c1fe5e63443468219aab6fd531c8dad6d22fd999819e //ubi8_buildah ----- -+ - -. Perform the steps mentioned in the "Creating a buildah build" section. - diff --git a/modules/ob-creating-s2i-build-in-a-network-restricted-environment.adoc b/modules/ob-creating-s2i-build-in-a-network-restricted-environment.adoc deleted file mode 100644 index 52696a869c30..000000000000 --- a/modules/ob-creating-s2i-build-in-a-network-restricted-environment.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/work-with-builds.adoc - -:_mod-docs-content-type: PROCEDURE -[id='ob-creating-source-to-image-build-in-a-network-restricted-environment_{context}'] -= Creating source-to-image build in a network-restricted environment - -[role="_abstract"] -You can create a `source-to-image` build in a network-restricted environment by mirroring the images required by the `source-to-image` build strategy. - -.Prerequisites - -* Your cluster can connect and interact with the git source that you can use to create the source-to-image build. -* You have the builder-image required to create the `source-to-image` build in your local registry. If you do not have the builder-image in the local registry, mirror the source image. - -.Procedure - -. Run the following command to mirror the images required by the `source-to-image` build strategy: -+ -[source,terminal] ----- -$ oc image mirror --insecure -a registry.redhat.io/source-to-image/source-to-image-rhel8@sha256:d041c1bbe503d152d0759598f79802e257816d674b342670ef61c6f9e6d401c5 //source-to-image-source-to-image-rhel8 ----- -+ - -. Perform the steps mentioned in the "Creating a source-to-image build" section. \ No newline at end of file diff --git a/modules/ob-deleting-a-build-resource.adoc b/modules/ob-deleting-a-build-resource.adoc index 0f5971beeff4..df616b784c2f 100644 --- a/modules/ob-deleting-a-build-resource.adoc +++ b/modules/ob-deleting-a-build-resource.adoc @@ -3,12 +3,12 @@ = Deleting a build resource [role="_abstract"] -You can delete a `build` resource if it is not required in your project. +Delete a `build` resource created by the `buildah`, `source-to-image` (S2I), and `buildpacks` build processes using the `oc` CLI or the `shp` CLI. This cleanup ensures that unused build configurations are removed, keeping your project organized and efficient. .Prerequisites * You have installed the `oc` CLI. -* Optional: You have installed the shp CLI. +* Optional: You have installed the `shp` CLI. .Procedure @@ -16,13 +16,35 @@ You can delete a `build` resource if it is not required in your project. + [source,terminal] ---- -$ oc delete builds # <1> +$ oc delete builds ---- -<1> Replace with the name of the `build` resource. + [source,terminal] ---- -$ shp build delete # <1> +$ shp build delete ---- -<1> Replace with the name of the `build` resource. \ No newline at end of file ++ +where: + +``:: Specifies the name of the `build` resource. + +.Verification + +* Verify that the `build` resource is deleted by using the `oc` CLI or `shp` CLI: ++ +[source,terminal] +---- +$ oc get build | grep +---- ++ +[source,terminal] +---- +$ shp build list | grep +---- ++ +where: + +``:: Specifies the name of the `build` resource. ++ +If the `build` resource is successfully deleted, the commands do not return any output. \ No newline at end of file diff --git a/modules/ob-deleting-a-buildrun-resource.adoc b/modules/ob-deleting-a-buildrun-resource.adoc index da3b784abb65..c39049193aa8 100644 --- a/modules/ob-deleting-a-buildrun-resource.adoc +++ b/modules/ob-deleting-a-buildrun-resource.adoc @@ -3,12 +3,12 @@ = Deleting a buildrun resource [role="_abstract"] -You can delete a `buildrun` resource if it is not required in your project. +Delete a `buildrun` resource created by the `buildah`, `source-to-image` (S2I), and `buildpacks` build processes if it is not required in your project. Deleting the resources helps you clean up build configurations that are no longer required in your project. .Prerequisites * You have installed the `oc` CLI. -* Optional: You have installed the shp CLI. +* Optional: You have installed the `shp` CLI. .Procedure @@ -16,13 +16,36 @@ You can delete a `buildrun` resource if it is not required in your project. + [source,terminal] ---- -$ oc delete buildrun #<1> +$ oc delete buildrun ---- -<1> Replace with the name of the `buildrun` resource. ++ +[source,terminal] +---- +$ shp build list | grep +---- ++ +where: + +``:: Specifies the name of the `buildrun` resource. ++ +If the `buildrun` resource has been successfully deleted, the commands do not return any output. + +.Verification +* Verify that the `buildrun` resource is deleted by using the `oc` CLI or `shp` CLI: + [source,terminal] ---- -$ shp buildrun delete # <1> +$ oc get buildrun | grep ---- -<1> Replace with the name of the `buildrun` resource. ++ +[source,terminal] +---- +$ shp buildrun list | grep +---- ++ +where: + +``:: Specifies the name of the `buildrun` resource. ++ +If the `buildrun` resource is successfully deleted, the commands do not return any output. \ No newline at end of file diff --git a/modules/ob-deleting-a-buildstrategy-resource.adoc b/modules/ob-deleting-a-buildstrategy-resource.adoc index 04d40ffa0a0d..fa473109b4b4 100644 --- a/modules/ob-deleting-a-buildstrategy-resource.adoc +++ b/modules/ob-deleting-a-buildstrategy-resource.adoc @@ -3,11 +3,13 @@ = Deleting a buildstrategy resource [role="_abstract"] -You can delete a `buildstrategy` resource if it is not required in your project. +Delete a `buildstrategy` resource to remove unused build configurations and keep your project clean and efficient. .Prerequisites * You have installed the `oc` CLI. +* Optional: You have installed the `shp` CLI. + .Procedure @@ -15,6 +17,29 @@ You can delete a `buildstrategy` resource if it is not required in your project. + [source,terminal] ---- -$ oc delete buildstrategy # <1> +$ oc delete buildstrategy +---- ++ +where: + +``:: Specifies the name of the `buildstrategy` resource. + +.Verification + +* Verify that the `buildstrategy` resource is deleted by using the `oc` CLI or `shp` CLI: ++ +[source,terminal] +---- +$ oc get buildstrategy | grep +---- ++ +[source,terminal] +---- +$ shp buildstrategy list | grep ---- -<1> Replace with the name of the `buildstrategy` resource. \ No newline at end of file ++ +where: + +``:: Specifies the name of the `buildstrategy` resource. ++ +If the `buildstrategy` resource has been successfully deleted, the commands do not return any output. \ No newline at end of file diff --git a/modules/ob-deleting-the-resources.adoc b/modules/ob-deleting-the-resources.adoc deleted file mode 100644 index 0878d1ad2529..000000000000 --- a/modules/ob-deleting-the-resources.adoc +++ /dev/null @@ -1,7 +0,0 @@ -:_mod-docs-content-type: CONCEPT -[id="ob-deleting-the-resources_{context}"] -= Deleting the resources - -[role="_abstract"] -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 index dcc1f7940e91..4718a3be342b 100644 --- a/modules/ob-editing-the-resources.adoc +++ b/modules/ob-editing-the-resources.adoc @@ -15,8 +15,12 @@ You can edit the resources that are created by `buildah`, `source-to-image` and + [source,terminal] ---- -$ oc edit # <1> +$ oc edit ---- -<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. ++ +where: + +``:: Specifies the name of the resource (`build`, `buildrun` or `buildstrategy`) +``:: Specifies 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-verifying-cluster-wide-proxy.adoc b/modules/ob-verifying-cluster-wide-proxy.adoc deleted file mode 100644 index 81c92e70eca4..000000000000 --- a/modules/ob-verifying-cluster-wide-proxy.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// This module is included in the following assembly: -// -// * configuring/using-builds-in-a-restricted-environment.adoc - -:_mod-docs-content-type: PROCEDURE -[id="ob-verifying-cluster-wide-proxy_{context}"] -= Verifying cluster-wide proxy - -[role="_abstract"] -As a cluster administrator, you can verify the cluster-wide proxy settings. - -.Procedure - -* To verify if the cluster-wide proxy is correctly configured, run the following command: -+ -[source,terminal] ----- -$ oc describe proxy/cluster ----- -+ -The cluster proxy object displays the proxy server and certificate information. \ No newline at end of file diff --git a/modules/ob-verifying-proxy-details.adoc b/modules/ob-verifying-proxy-details.adoc new file mode 100644 index 000000000000..bb7c3539ed38 --- /dev/null +++ b/modules/ob-verifying-proxy-details.adoc @@ -0,0 +1,69 @@ +// This module is included in the following assembly: +// +// * configuring/using-builds-in-a-restricted-environment.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ob-verifying-proxy-details_{context}"] += Verifying proxy details + +[role="_abstract"] +If you run a cluster behind a proxy, ensure that cluster-wide proxy settings and environment variables are correctly configured in the {ocp-product-title} cluster. This ensures all {builds-shortname} traffic is routed through the monitored outbound proxy gateway. + +.Prerequisites + +* You have installed the `oc` CLI. + +.Procedure + +. To verify the cluster-wide proxy settings, run the following command: ++ +[source,terminal] +---- +$ oc describe proxy/cluster +---- ++ +Example output: ++ +[source,terminal] +---- +Name: cluster +Namespace: +Labels: hypershift.openshift.io/managed=true +Annotations: hypershift.io/hosted-cluster-proxy-config: true + include.release.openshift.io/ibm-cloud-managed: true + include.release.openshift.io/self-managed-high-availability: true + release.openshift.io/create-only: true +API Version: config.openshift.io/v1 +Kind: Proxy +Metadata: + Creation Timestamp: 2026-01-05T09:56:06Z + Generation: 2 + Owner References: + API Version: config.openshift.io/v1 + Kind: ClusterVersion + Name: version + UID: bfb9588f-106f-4e9f-965b-03daa0cd8c33 + Resource Version: 1451 + UID: 8bbf0aef-6d78-479d-abdf-ddbb34bf3ff1 +Spec: + Trusted CA: + Name: +Events: +---- + +. To verify the environment variables, run the following command: ++ +[source,terminal] +---- +$ oc set env deployment/openshift-builds-operator --list -n openshift-builds | grep PROXY +---- ++ +Example output: ++ +[source,terminal] +---- +HTTP_PROXY=http://192.168.130.1:3128 +HTTPS_PROXY=https://192.168.130.1:3129 +NO_PROXY=.cluster.local,.svc,.testing,10.217.0.0/22,10.217.4.0/23,127.0.0.1,192.168.126.0/24,192.168.1 +30.11,api-int.crc.testing,localhost +---- \ No newline at end of file diff --git a/modules/ob-verifying-proxy-environment-variables.adoc b/modules/ob-verifying-proxy-environment-variables.adoc deleted file mode 100644 index 78627a3e185d..000000000000 --- a/modules/ob-verifying-proxy-environment-variables.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// This module is included in the following assembly: -// -// * configuring/using-builds-in-a-restricted-environment.adoc - -:_mod-docs-content-type: PROCEDURE -[id="ob-verifying-the-proxy-environment-variables_{context}"] -= Verifying the proxy environment variables - -[role="_abstract"] -As a cluster administrator, you can verify the environment variables to ensure that the proxy settings are correctly configured for {builds-title} on an {ocp-product-title} cluster. - -.Procedure - -* To verify the environment variables, run the following command: -[source,terminal] ----- -$ oc set env deployment/openshift-builds-operator --list -n openshift-builds | grep PROXY ----- -+ - -.Example output -[source,terminal] ----- -HTTP_PROXY=http://192.168.130.1:3128 -HTTPS_PROXY=https://192.168.130.1:3129 -NO_PROXY=.cluster.local,.svc,.testing,10.217.0.0/22,10.217.4.0/23,127.0.0.1,192.168.126.0/24,192.168.1 -30.11,api-int.crc.testing,localhost ----- \ No newline at end of file diff --git a/work_with_builds/creating-container-images-in-a-network-restricted-environment.adoc b/work_with_builds/creating-container-images-in-a-network-restricted-environment.adoc new file mode 100644 index 000000000000..8146cb969e15 --- /dev/null +++ b/work_with_builds/creating-container-images-in-a-network-restricted-environment.adoc @@ -0,0 +1,27 @@ +:_mod-docs-content-type: ASSEMBLY +[id="managing-builds-in-a-network-restricted-environment"] +include::_attributes/common-attributes.adoc[] += Creating container images in a network restricted environment + +:context: using-builds-in-a-network-restricted-environment + +toc::[] + +[role="_abstract"] +As an application developer, configure {ocp-product-title} with an HTTP or HTTPS proxy to enforce security and prevent direct internet access for your build processes. This setup enforces security by routing build pulls of dependencies, images, and code through a monitored outgoing proxy gateway. + +include::modules/ob-creating-a-buildah-build-in-a-network-restricted-environment.adoc[leveloffset=+1] + +include::modules/ob-creating-a-s2i-build-in-a-network-restricted-environment.adoc[leveloffset=+1] + +include::modules/ob-verifying-proxy-details.adoc[leveloffset=+1] + +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources + +* xref:../work_with_builds/creating-container-images.adoc#ob-creating-a-buildah-build_using-builds[Creating a buildah build] +* xref:../work_with_builds/creating-container-images.adoc#ob-creating-a-s2i-build_using-builds[Creating a source to image build] +* link:https://docs.openshift.com/pipelines/1.16/install_config/installing-pipelines.html#op-pipelines-operator-in-restricted-environment_installing-pipelines[Red Hat OpenShift Pipelines Operator in a restricted environment] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/configuring_network_settings/enable-cluster-wide-proxy[Configuring cluster-wide proxy] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/disconnected_environments/installing-mirroring-installation-images[Mirroring images for a disconnected installation by using the oc adm command] diff --git a/work_with_builds/creating-container-images.adoc b/work_with_builds/creating-container-images.adoc new file mode 100644 index 000000000000..48a770557a20 --- /dev/null +++ b/work_with_builds/creating-container-images.adoc @@ -0,0 +1,27 @@ +:_mod-docs-content-type: ASSEMBLY +[id="creating-container-images"] +include::_attributes/common-attributes.adoc[] += Creating container images + +:context: using-builds + +toc::[] + +[role="_abstract"] +As an application developer, create container images using `buildah`, `source-to-image`, or the `buildpacks` strategy, depending on your source code, framework, and automation requirements. You can also use Open Container Initiative (OCI) artifacts to build container images. + +include::modules/ob-creating-a-buildah-build.adoc[leveloffset=+1] + +include::modules/ob-creating-a-s2i-build.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] + +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources + +* xref:../authenticating/understanding-authentication-at-runtime.adoc#ob-authentication-to-container-registries_understanding-authentication-at-runtime[Authentication to container registries] +* xref:../about/build-strategies.adoc[Build strategies] +* xref:../installing/installing-openshift-builds.adoc[Installing builds] diff --git a/work_with_builds/docinfo.xml b/work_with_builds/docinfo.xml index 3326c6c6bd38..46e8e7d3a063 100644 --- a/work_with_builds/docinfo.xml +++ b/work_with_builds/docinfo.xml @@ -1,9 +1,9 @@ Work with Builds {product-title} {product-version} -Using Builds +Managing Builds - This document provides procedural examples for using Builds. + This document provides procedural examples for managing Builds. Red Hat OpenShift Documentation Team diff --git a/work_with_builds/managing-builds.adoc b/work_with_builds/managing-builds.adoc new file mode 100644 index 000000000000..21bc6ab318b6 --- /dev/null +++ b/work_with_builds/managing-builds.adoc @@ -0,0 +1,26 @@ +:_mod-docs-content-type: ASSEMBLY +[id="managing-builds"] +include::_attributes/common-attributes.adoc[] += Managing {builds-shortname} + +:context: managing-builds + +toc::[] + +[role="_abstract"] +As an application developer, modify or delete the custom resources (CR) that are not used in builds. This helps in maintaining a clean and efficient build configuration. + +include::modules/ob-editing-the-resources.adoc[leveloffset=+1] + +include::modules/ob-deleting-a-build-resource.adoc[leveloffset=+1] + +include::modules/ob-deleting-a-buildrun-resource.adoc[leveloffset=+1] + +include::modules/ob-deleting-a-buildstrategy-resource.adoc[leveloffset=+1] + + +//[role="_additional-resources"] +//[id="additional-resources_managing-builds"] +//== Additional resources + + diff --git a/work_with_builds/using-builds.adoc b/work_with_builds/using-builds.adoc deleted file mode 100644 index be421b52b30c..000000000000 --- a/work_with_builds/using-builds.adoc +++ /dev/null @@ -1,43 +0,0 @@ -:_mod-docs-content-type: ASSEMBLY -[id="managing-builds"] -include::_attributes/common-attributes.adoc[] -= Managing {builds-shortname} - -:context: using-builds - -toc::[] - -[role="_abstract"] -After installing {builds-shortname}, you can create builds using `buildah`, `source-to-image`, or `buildpacks`. You can also use an Open Container Initiative (OCI) to create your build. You can also delete custom resources that are not required for a build. - - -include::modules/ob-creating-a-buildah-build.adoc[leveloffset=+1] - -include::modules/ob-creating-buildah-build-in-a-network-restricted-environment.adoc[leveloffset=+2] - -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-creating-a-buildpacks-build.adoc[leveloffset=+1] - -include::modules/ob-creating-a-build-with-oci-artifacts.adoc[leveloffset=+1] - -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] - - -[role="_additional-resources"] -[id="additional-resources_using-builds"] -== Additional resources - -* xref:../authenticating/understanding-authentication-at-runtime.adoc#ob-authentication-to-container-registries_understanding-authentication-at-runtime[Authentication to container registries] -* xref:../installing/installing-openshift-builds.adoc#creating-a-shipwright-build-resource-console_installing-openshift-builds[Creating a ShipwrightBuild resource by using the web console] -* link:https://docs.openshift.com/container-platform/latest/disconnected/mirroring/installing-mirroring-installation-images.html[Mirroring images for a disconnected installation by using the oc adm command]