Added documentation for Runtime class

_topic_maps/_topic_map.yml

@@ -55,6 +55,8 @@ Topics:
   File: configuring-build-strategies
 - Name: Configuring build runs
   File: configuring-build-runs
+- Name: Isolate build workloads for security and compliance
+  File: isolate-build-workloads-for-security-and-compliance
 ---
 Name: Work with Builds
 Dir: work_with_builds
@@ -92,6 +94,13 @@ Topics:
 - Name: Monitoring
   File: monitoring
 ---
+Name: Troubleshooting
+Dir: troubleshooting
+Distros: openshift-builds
+Topics:
+- Name: Troubleshooting RuntimeClass
+  File: troubleshooting-runtime-class
+---
 Name: Uninstall
 Dir: uninstalling
 Distros: openshift-builds

configuring/isolate-build-workloads-for-security-and-compliance.adoc

@@ -0,0 +1,28 @@
+:_mod-docs-content-type: ASSEMBLY
+
+[id="isolate-build-workloads-for-security-and-compliance_{context}"]
+= Isolate build workloads for security and compliance
+
+include::_attributes/common-attributes.adoc[]
+
+:context: isolate-build-workloads
+
+toc::[]
+
+[role="_abstract"]
+Configure builds to run with alternative container runtimes by using the `runtimeClassName` field to improve workload isolation or meet specific compliance requirements.
+
+:FeatureName: Builds in sandbox containers
+include::snippets/technology-preview.adoc[]
+
+include::modules/ob-runtimeclass-prerequisites-and-precedence.adoc[leveloffset=+1]
+
+include::modules/ob-isolate-all-project-builds-using-a-specific-runtimeclass.adoc[leveloffset=+1]
+
+include::modules/ob-override-runtimeclass-for-specific-build-run.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+== Additional resources
+
+* link:https://docs.redhat.com/en/documentation/openshift_sandboxed_containers/[OpenShift Sandboxed Containers documentation]
+* link:https://kubernetes.io/docs/concepts/containers/runtime-class/[Kubernetes RuntimeClass documentation]

modules/ob-isolate-all-project-builds-using-a-specific-runtimeclass.adoc

@@ -0,0 +1,88 @@
+// This module is included in the following assembly:
+//
+// * configuring/isolate-build-workloads-for-security-and-compliance.adoc
+
+:_mod-docs-content-type: PROCEDURE
+
+[id="ob-isolate-all-project-builds-using-a-specific-runtimeclass_{context}"]
+= Isolate all project builds using a specific RuntimeClass
+
+[role="_abstract"]
+Set the `runtimeClassName` field on a `Build` resource to apply a specific container runtime to all associated build executions by default.
+
+.Prerequisites
+
+* A RuntimeClass resource exists in your cluster, such as `kata` for OpenShift Sandboxed Containers.
+* Worker nodes have sufficient capacity. Kata Containers allocate 2 GiB of RAM and 1 CPU per pod as base overhead, plus any additional resources defined in your build.
+* The `runtimeClassName` value is a valid DNS subdomain name (lowercase alphanumeric characters, hyphens, or dots).
+
+.Procedure
+
+. Create or edit a `Build` resource and set the `spec.runtimeClassName` field to the name of a RuntimeClass that exists in your cluster:
++
+[source,yaml]
+----
+apiVersion: shipwright.io/v1beta1
+kind: Build
+metadata:
+  name: buildah-build-kata
+spec:
+  source:
+    type: Git
+    git:
+      url: https://github.com/shipwright-io/sample-go
+    contextDir: docker-build
+  strategy:
+    name: buildah
+    kind: ClusterBuildStrategy
+  paramValues:
+    - name: dockerfile
+      value: Dockerfile
+  output:
+    image: image-registry.openshift-image-registry.svc:5000/example/sample-go:latest
+    pushSecret: registry-credentials
+  runtimeClassName: kata
+----
++
+where:
+
+`spec.source`:: Defines the Git repository and context directory containing the source code to build.
+`spec.strategy`:: Specifies the build strategy to use. In this example, the `buildah` ClusterBuildStrategy is used.
+`spec.output.image`:: Specifies the destination for the built container image.
+`spec.runtimeClassName`:: Specifies the RuntimeClass to use for build isolation. For example, `kata` for OpenShift Sandboxed Containers.
++
+[NOTE]
+====
+If you also define `spec.runtimeClassName` in the `BuildRun` resource, the `BuildRun` value overrides the `Build` value.
+====
+
+. Run the following command to apply the resource:
++
+[source,terminal]
+----
+$ oc apply -f build.yaml
+----
+
+.Verification
+
+. Run the following command to verify that the Build was registered successfully:
++
+[source,terminal]
+----
+$ oc get build buildah-build-kata
+----
++
+A `Succeeded` status reason confirms that the `Build` passed validation. If the `runtimeClassName` value is not a valid DNS subdomain name, the status shows `RuntimeClassNameNotValid`.
+
+. Verify the RuntimeClass is configured correctly:
++
+[source,terminal]
+----
+$ oc get build buildah-build-kata -o jsonpath='{.spec.runtimeClassName}'
+----
++
+.Example output
+[source,terminal]
+----
+kata
+----

modules/ob-override-runtimeclass-for-specific-build-run.adoc

@@ -0,0 +1,84 @@
+// This module is included in the following assembly:
+//
+// * configuring/isolate-build-workloads-for-security-and-compliance.adoc
+
+:_mod-docs-content-type: PROCEDURE
+
+[id="ob-override-runtimeclass-for-specific-build-run_{context}"]
+= Override the RuntimeClass for a specific build run
+
+[role="_abstract"]
+When you need to run a specific build execution with a different container runtime than what the `Build` defines, set the `runtimeClassName` on the `BuildRun`. This is useful when you want to test a build under a different runtime without modifying the `Build`, or when a one-off build needs stronger isolation.
+
+When `runtimeClassName` is specified in both the `Build` and the `BuildRun`, the `BuildRun` value takes precedence.
+
+[IMPORTANT]
+====
+The `runtimeClassName` override on a `BuildRun` can only be used when referencing an existing `Build` by name (`spec.build.name`). It cannot be combined with an embedded build specification (`spec.build.spec`). If you are using an embedded spec, set the `runtimeClassName` inside `spec.build.spec` directly.
+====
+
+.Prerequisites
+
+* You have an existing `Build` resource.
+* A RuntimeClass resource exists in your cluster that you want to use for this specific build run.
+
+.Procedure
+
+. Create a `BuildRun` resource that references an existing `Build` and set the `spec.runtimeClassName` field:
++
+[source,yaml]
+----
+apiVersion: shipwright.io/v1beta1
+kind: BuildRun
+metadata:
+  name: buildah-buildrun-kata
+spec:
+  build:
+    name: buildah-build-kata
+  runtimeClassName: kata
+----
++
+where:
+
+`metadata.name`:: Specifies the name of the `BuildRun` resource.
+`spec.build.name`:: References the existing `Build` resource to use.
+`spec.runtimeClassName`:: Specifies the `RuntimeClass` to use for this specific build run. This value overrides the `runtimeClassName` defined in the `Build` resource.
+
+. Run the following command to apply the `BuildRun` resource:
++
+[source,terminal]
+----
+$ oc apply -f buildrun.yaml
+----
+
+. Monitor the `BuildRun` status:
++
+[source,terminal]
+----
+$ oc get buildrun buildah-buildrun-kata
+----
+
+The following `BuildRun` overrides the `kata` runtime defined on the `Build` with `gvisor` for this single execution:
+
+[source,yaml]
+----
+apiVersion: shipwright.io/v1beta1
+kind: BuildRun
+metadata:
+  name: buildah-buildrun-gvisor
+spec:
+  build:
+    name: buildah-build-kata
+  runtimeClassName: gvisor
+----
+
+.Verification
+
+Run the following command to confirm the pod is executing with the specified runtime:
+
+[source,terminal]
+----
+$ oc get pod -l build.shipwright.io/name=buildah-build-kata -o jsonpath='{.items[0].spec.runtimeClassName}'
+----
+
+The command returns the `RuntimeClass` name specified in the `BuildRun`, such as `kata` or `gvisor`.

modules/ob-runtimeclass-prerequisites-and-precedence.adoc

@@ -0,0 +1,73 @@
+// This module is included in the following assembly:
+//
+// * configuring/isolate-build-workloads-for-security-and-compliance.adoc
+
+:_mod-docs-content-type: CONCEPT
+
+[id="ob-runtimeclass-prerequisites-and-precedence_{context}"]
+= Runtime selection requirements and precedence
+
+[role="_abstract"]
+Meet cluster configuration requirements and understand how the system resolves `runtimeClassName` conflicts across Build and BuildRun resources before using alternative runtimes.
+
+* On {product-title}, OpenShift Sandboxed Containers Operator supports `runtimeClass` for Kata Containers. This operator manages the full lifecycle of the Kata Containers runtime on your cluster. As a cluster administrator, you must install the operator from OperatorHub and then create a `KataConfig` custom resource. The operator then:
+** Installs the required RHCOS extensions (QEMU, kata-containers) on worker nodes.
+** Configures CRI-O with the correct Kata runtime handlers.
+** Create a `runtimeClass` resource to define the specific scheduling requirements and resource allocations needed to run builds using Kata Containers.
++
+[NOTE]
+====
+Creating the `KataConfig` CR triggers an automatic reboot of worker nodes. This reboot can take from 10 to more than 60 minutes. Sandboxed containers are only supported on bare-metal clusters.
+====
+
+* After the operator finishes setup, verify that the `kata` runtimeClass is available:
++
+[source,terminal]
+----
+$ oc get runtimeclasses
+----
++
+The operator creates a `runtimeClass` similar to the following:
++
+[source,yaml]
+----
+apiVersion: node.k8s.io/v1
+kind: RuntimeClass
+metadata:
+  name: kata
+handler: kata
+overhead:
+  podFixed:
+    cpu: 250m
+    memory: 350Mi
+scheduling:
+  nodeSelector:
+    node-role.kubernetes.io/kata-oc: ""
+----
++
+where:
+
+`overhead`:: Specifies the additional CPU and memory consumed by the QEMU process and guest kernel. By default, Kata Containers allocate 2Gi of RAM and 1 CPU per pod, and any resource limits you set on your build are added on top of this base allocation.
+
+* The nodes where build pods are scheduled must have the Kata Containers runtime installed. By default, the operator installs Kata on all worker nodes. To install only on specific nodes, label those nodes and specify the label in the `KataConfig` CR. If no nodes support the runtime, the build pod remains in a `Pending` state with a `FailedScheduling` event.
+
+* If your `Build` or `BuildRun` defines a `nodeSelector` or `tolerations`, the targeted nodes must also support the specified RuntimeClass. The `kata` RuntimeClass created by the operator includes its own `scheduling.nodeSelector` (`node-role.kubernetes.io/kata-oc: ""`); the combined constraints from both the RuntimeClass and the build must match at least one available node.
+
+* The `runtimeClassName` value must conform to RFC 1123: lowercase alphanumeric characters, hyphens (`-`), or dots (`.`), starting and ending with an alphanumeric character. Invalid names are rejected at build registration time with a `RuntimeClassNameNotValid` status.
+
+RuntimeClass precedence::
+
+The following table summarizes how the system resolves which runtime to use when `runtimeClassName` is set in both the `Build` and `BuildRun` resources:
+
+.Compatibility and support matrix
+[options="header"]
+|===
+
+| Build runtimeClassName | BuildRun runtimeClassName | Effective RuntimeClass
+
+| Not set | Not set | Cluster default |
+| kata    | Not set | kata |
+| Not set | gvisor  | gvisor |
+| kata | gvisor | gvisor |
+
+|===

modules/ob-troubleshoot-build-pod-pending.adoc

@@ -0,0 +1,45 @@
+// This module is included in the following assembly:
+//
+// * troubleshooting/troubleshooting-runtime-class.adoc
+
+:_mod-docs-content-type: PROCEDURE
+
+[id="ob-troubleshoot-build-pod-pending_{context}"]
+= Resolving build pods in Pending state
+
+[role="_abstract"]
+When a build pod fails to schedule, examine the pod events for diagnostic details to identify the root cause.
+
+.Procedure
+
+. Run the following command to examine the pod events:
++
+[source,terminal]
+----
+$ oc describe pod <build-pod-name>
+----
+
+. Identify any `FailedScheduling` events, which often result from the following scenarios:
+
+* The `Build` validation only checks string format, a name that is syntactically valid but refers to a missing `RuntimeClass` will fail during scheduling. Run the following command to verify the resource exists:
++
+[source,terminal]
+----
+$ oc get runtimeclass kata
+----
+
+* The targeted nodes must have the Kata runtime properly installed. Confirm the `KataConfig` status and node readiness:
++
+[source,terminal]
+----
+$ oc get kataconfig -o yaml
+----
++
+Check `status.installationStatus` to ensure the installation on worker nodes was successful.
+
+* The operator-managed `kata` runtimeClass applies a `node-role.kubernetes.io/kata-oc: ""` selector. If your build configuration defines additional selectors, they must intersect with the `runtimeClass` requirements. Verify node labels:
++
+[source,terminal]
+----
+$ oc get nodes --show-labels | grep kata
+----

modules/ob-troubleshoot-buildrun-field-override-forbidden.adoc

@@ -0,0 +1,47 @@
+// This module is included in the following assembly:
+//
+// * troubleshooting/troubleshooting-runtime-class.adoc
+
+:_mod-docs-content-type: PROCEDURE
+
+[id="ob-troubleshoot-buildrun-field-override-forbidden_{context}"]
+= Resolve buildRun failures with BuildRunBuildFieldOverrideForbidden
+
+[role="_abstract"]
+The `BuildRunBuildFieldOverrideForbidden` error occurs if you try to set `runtimeClassName` on a `BuildRun` that has an embedded `spec.build.spec` rather than a reference to a named `Build`.
+
+.Procedure
+
+. Run the following command to check the `BuildRun` status message:
++
+[source,terminal]
+----
+$ oc get buildrun <buildrun-name> -o jsonpath='{.status.conditions[0].message}'
+----
+
+. To resolve this issue, use one of the following methods:
+
+.. Define the `runtimeClassName` directly within the inline `spec.build.spec` block:
++
+[source,yaml]
+----
+apiVersion: shipwright.io/v1beta1
+kind: BuildRun
+spec:
+  build:
+    spec:
+      # ... source and strategy fields ...
+      runtimeClassName: kata
+----
+
+.. Reference a standalone `Build` by name to use the override field:
++
+[source,yaml]
+----
+apiVersion: shipwright.io/v1beta1
+kind: BuildRun
+spec:
+  build:
+    name: buildah-build-kata
+  runtimeClassName: kata
+----