Troubleshooting

builds for Red Hat OpenShift 1.8

Troubleshooting Builds

Red Hat OpenShift Documentation Team

Abstract

This document provides information about troubleshooting Builds.

Chapter 1. Troubleshooting RuntimeClass

Diagnose and resolve common build configuration errors related to RuntimeClass isolation. Identifying these issues ensures that builds run in the intended isolated environments and helps maintain cluster security.

1.1. Resolving build failures with RuntimeClassNameNotValid

If the runtimeClassName value violates DNS subdomain naming conventions, the Build or BuildRun status is set to RuntimeClassNameNotValid.

Procedure

Run the following command to check the build status:
```
$ oc get build buildah-build-kata -o jsonpath='{.status.reason}'
```
To fix this issue, update the runtimeClassName to use only lowercase alphanumeric characters, dots (.), or hyphens (-), and ensure it begins and ends with an alphanumeric character.
The following example output displays the invalid names:

runtimeClassName: My_Runtime!  # Invalid: uppercase, underscore, and special character
runtimeClassName: Kata         # Invalid: uppercase letter
runtimeClassName: -kata        # Invalid: starts with hyphen

+ The following example output displays the valid names:

runtimeClassName: kata              # Valid
runtimeClassName: gvisor.runsc      # Valid: contains dot
runtimeClassName: kata-containers   # Valid: contains hyphen

1.2. Resolving build pods in Pending state

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:
```
$ 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:
```
$ oc get runtimeclass kata
```
- The targeted nodes must have the Kata runtime properly installed. Confirm the KataConfig status and node readiness:
```
$ 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:
```
$ oc get nodes --show-labels | grep kata
```

1.3. Resolve buildRun failures with BuildRunBuildFieldOverrideForbidden

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:
```
$ 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:

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:

apiVersion: shipwright.io/v1beta1
kind: BuildRun
spec:
  build:
    name: buildah-build-kata
  runtimeClassName: kata

1.4. Resolving build pod failures with RuntimeClass not found error

If events report that the runtimeClass is missing, the operator setup might be incomplete.

Procedure

Confirm the operator is active:

$ oc get csv -n openshift-sandboxed-containers-operator

Check the KataConfig installation status:

$ oc get kataconfig -o jsonpath='{.items[0].status.installationStatus}'

Ensure all worker nodes have completed the mandatory reboot process.

1.5. Additional resources

Legal Notice

Except as otherwise noted below, the text of and illustrations in this documentation are licensed by Red Hat under the Creative Commons Attribution–Share Alike 3.0 Unported license . If you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, the Red Hat logo, JBoss, Hibernate, and RHCE are trademarks or registered trademarks of Red Hat, LLC. or its subsidiaries in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

XFS is a trademark or registered trademark of Hewlett Packard Enterprise Development LP or its subsidiaries in the United States and other countries.

The OpenStack® Word Mark and OpenStack logo are trademarks or registered trademarks of the Linux Foundation, used under license.

All other trademarks are the property of their respective owners.