Chapter 1. Overview of Builds
Chapter 1. Overview of Builds Builds is an extensible build framework based on the Shipwright project , which you can use to build container images on an OpenShift Container Platform cluster. You can build container images from source code and Dockerfiles by using image build tools, such as Source-to-Image (S2I) and Buildah. You can create and apply build resources, view logs of build runs, and manage builds in your OpenShift Container Platform namespaces. Builds includes the following capabilities: Standard Kubernetes-native API for building container images from source code and Dockerfiles Support for Source-to-Image (S2I) and Buildah build strategies Extensibility with your own custom build strategies Execution of builds from source code in a local directory Shipwright CLI for creating and viewing logs, and managing builds on the cluster Integrated user experience with the Developer perspective of the OpenShift Container Platform web console Builds consists of the following custom resources (CRs): Build BuildStrategy and ClusterBuildStrategy BuildRun 1.1. Build resource The Build resource defines the source code of your application and the location where your application images will be pushed. The following example shows a simple build that consists of a Git source, a build strategy, and an output image: apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-golang-build spec: source: git: url: https://github.com/username/taxi strategy: name: buildah kind: ClusterBuildStrategy output: image: registry.mycompany.com/my-org/taxi-app:latest You can also extend a Build resource to push your images to a private registry or use a Dockerfile. 1.2. BuildStrategy and ClusterBuildStrategy resources The BuildStrategy and ClusterBuildStrategy resources define a series of steps to assemble an application. You can use the BuildStrategy resources within a namespace and the ClusterBuildStrategy resources within a cluster. The specification of a BuildStrategy or ClusterBuildStrategy resource consists of a steps object. The following example shows the specification of the buildah cluster build strategy: apiVersion: shipwright.io/v1beta1 kind: ClusterBuildStrategy metadata: name: buildah spec: steps: - name: build-and-push image: quay.io/containers/buildah:v1.31.0 workingDir: USD(params.shp-source-root) command: - /bin/bash # ... # ... 1.3. BuildRun resource A BuildRun resource invokes a build on your cluster, similar to any cluster job or Tekton task run. The BuildRun resource represents a workload on your cluster, which results in a running pod. A BuildRun is the running instance of a build. It instantiates a build for execution with specific parameters on a cluster. A BuildRun resource helps you to define the following elements: A unique BuildRun name to monitor the status of the build A referenced Build instance to use during the build A service account to host all secrets for the build Each BuildRun resource is available within a namespace. 1.4. Build controller The build controller monitors any updates in the Build resource and performs the following tasks: Validates if the referenced Strategy object exists in the Build resource. Validates if the specified parameters in the Build CR exist in the referenced build strategy. It also validates if the parameter names collide with any reserved names. Validates if the container registry output secret exists in the Build resource. Validates if the referenced spec.source.git.url endpoint URL exists in the Build resource. The build run controller monitors any updates in the Build or TaskRun resource and performs the following tasks: Searches for any existing TaskRun resource and updates its parent BuildRun resource status. Retrieves the specified service account and sets it along with the output secret in the Build resource. If a TaskRun resource does not exist, the controller generates a new Tekton TaskRun resource and sets a reference to the TaskRun resource. For any subsequent updates in the TaskRun resource, the controller updates the parent BuildRun resource. 1.4.1. Build validations To avoid triggering BuildRun resources that will fail because of incorrect or missing dependencies or configuration settings, the build controller validates them in advance. If all validations are successful, you view a status.reason field named Succeeded . However, if any validations fail, you must check the status.reason and status.message fields to understand the root cause. Table 1.1. Validation of builds by the build controller status.reason field Description BuildStrategyNotFound The referenced strategy at namespace level does not exist. ClusterBuildStrategyNotFound The referenced strategy at cluster level does not exist. SetOwnerReferenceFailed Setting owner references between a Build and a BuildRun resources failed. This status is triggered when you set the spec.retention.atBuildDeletion field to true in a build. SpecSourceSecretRefNotFound The secret used to authenticate to Git does not exist. SpecOutputSecretRefNotFound The secret used to authenticate to the container registry does not exist. SpecBuilderSecretRefNotFound The secret used to authenticate to the container registry does not exist. MultipleSecretRefNotFound Multiple secrets used for authentication are missing. RestrictedParametersInUse One or many defined params are colliding with any reserved parameters. UndefinedParameter The parameters are not defined in the referenced strategy. You must define those parameters in the spec.parameters specification in your strategy. RemoteRepositoryUnreachable The defined spec.source.git.url specification was not found. This validation only takes place for HTTP and HTTPS protocols. BuildNameInvalid The build name in the metadata.name field is invalid. You must use a valid label value for the build name. SpecEnvNameCanNotBeBlank Indicates that the name for a user-provided environment variable is blank. SpecEnvValueCanNotBeBlank Indicates that the value for a user-provided environment variable is blank. 1.5. Additional resources Installing Builds by using the console Installing Builds by using the CLI
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-golang-build spec: source: git: url: https://github.com/username/taxi strategy: name: buildah kind: ClusterBuildStrategy output: image: registry.mycompany.com/my-org/taxi-app:latest apiVersion: shipwright.io/v1beta1 kind: ClusterBuildStrategy metadata: name: buildah spec: steps: - name: build-and-push image: quay.io/containers/buildah:v1.31.0 workingDir: USD(params.shp-source-root) command: - /bin/bash #