DOCSEARCHbyAlgolia
Submit Docs

Shipwright Build

repository·main·Indexed 21 days ago

https://github.com/shipwright-io/build

An open-source API implementation for building container images on Kubernetes. It supports Dockerfile-based and Dockerfile-less strategies (including Kaniko, BuildKit, Buildah, Buildpacks-v3, Source-to-Image, and ko) using Kubernetes Custom Resources such as Build, BuildRun, and BuildStrategy. The package includes specialized utilities: a Git Clone Wrapper for source retrieval, an image-processing CLI for OCI annotations and labels, a waiter CLI for application lifecycle management, and a bundle command for unpacking container images.

Tokens
52.7K
Snippets
135
Records
200
Agent score
71%

What's inside shipwright-io/build

  1. Overview of the Git Clone Wrapper

    main
    The Git Clone Wrapper is a Shipwright-owned utility designed to retrieve source code during a build process. It wraps the git CLI in a minimal container setup, providing a more integrated alternative to using external resources like Tekton Git Resources. It is specifically designed to handle various authentication and repository types within a containerized build environment.

  2. Overview of Build Controllers

    main

    Build (codenamed build-v2) is an open-source API implementation for building container images on Kubernetes. It supports both dockerfile-based and source-based approaches.

    Instead of managing complex image construction details, developers use Kubernetes Custom Resources (CRDs) to define their desired build strategy (such as source-to-image, buildpack-v3, kaniko, jib, or buildah).

  4. Available Shipwright build strategies

    main

    Shipwright provides several built-in strategies for building container images in a Kubernetes cluster. The default installation includes:

    • Buildpacks-v3 (via Paketo or Heroku)
    • Kaniko
    • BuildKit
    • Source-to-Image
    • Buildah
    • ko

    Choose a strategy based on whether your source code requires a Dockerfile or can be built directly from the source.

  5. What is a Build resource

    main

    A Build resource is a Kubernetes Custom Resource Definition (CRD) instance used to define the specification for a container build process. It is scoped to a specific namespace and acts as a template for creating BuildRun objects (the actual executions).

    A Build allows you to configure:

    • Source: Where the code comes from (e.g., Git).
    • Strategy: The build logic to use (e.g., Dockerfile, Kaniko).
    • Parameters: Custom values passed to the build strategy via paramValues.
    • Output: Where the resulting image is pushed and which platforms it supports.
    • Triggers: Events that automatically start a build (e.g., GitHub webhooks, new images).
    • Environment: Environment variables for the build steps.
    • Resources & Scheduling: volumes, stepResources, nodeSelector, tolerations, schedulerName, and runtimeClassName.
    • Retention: How long build artifacts or logs are kept.

  6. How the Build Controller works

    main

    The Shipwright Build Controller manages the lifecycle of Build resources by watching for updates to the CRD instances. When a Build is created or updated, the controller performs several pre-flight validations to ensure the build can execute successfully.

    The controller validates:

    1. Strategy Existence: Ensures the referenced Strategy (either namespace-scoped or cluster-scoped) exists.
    2. Parameter Integrity: Checks that all paramValues provided exist in the referenced strategy's spec.parameters and that they do not collide with Shipwright reserved names.
    3. Secret Availability: Verifies that the container registry output secret exists.
    4. Source Accessibility: Validates that the spec.source.git.url endpoint is reachable (for HTTP/HTTPS protocols).

  7. Configure Build triggers

    main

    Triggers allow for event-driven builds. This requires the Shipwright Triggers project to be installed in the cluster.

    Supported Trigger Types

    • GitHub: Reacts to WebHooks. Matches builds based on the repository URL and branch name.
      • If branches is empty, it uses spec.source.git.revision.
      • If revision is also empty, it defaults to main.
    • Image: Watches for changes in specific container image tags (requires the Image controller).
    • Tekton Pipeline: Watches for Pipeline resources reaching a specific status (e.g., Succeeded) via objectRef.status. You can identify pipelines by name or selector.
    # GitHub Trigger Example
spec:
  trigger:
    when:
      - name: push and pull-request on the main branch
        type: GitHub
        github:
          events:
            - Push
            - PullRequest
          branches:
            - main

# Tekton Pipeline Trigger Example
spec:
  trigger:
    when:
      - name: watching over for the Tekton Pipeline
        type: Pipeline
        objectRef:
          status:
            - Succeeded
          selector:
            label: value

  8. Use the Buildah ClusterBuildStrategy

    main

    The buildah ClusterBuildStrategy utilizes buildah to build and push container images from a Dockerfile. When using this strategy, you must specify the Dockerfile on the Build resource.

    There are two distinct push management formats available:

    • buildah-shipwright-managed-push: Shipwright manages the image push process.
    • buildah-strategy-managed-push: The strategy itself manages the image push process.

    Refer to the documentation on "Output directory vs. output image" to decide which push management type fits your workflow.

    # To install both Buildah push management variants:
kubectl apply -f samples/v1beta1/buildstrategy/buildah/buildstrategy_buildah_shipwright_managed_push_cr.yaml
kubectl apply -f samples/v1beta1/buildstrategy/buildah/buildstrategy_buildah_strategy_managed_push_cr.yaml

  9. How Build, BuildRun, and BuildStrategy work together

    main

    Shipwright uses a hierarchy of Kubernetes Custom Resources to manage the image building lifecycle:

    • Build: The primary resource where users provide high-level information. It defines the build strategy, the source input, and the desired output (e.g., a specific container registry).
    • BuildRun: Represents a specific instance of an image construction. It abstracts the execution details by leveraging Tekton Pipelines to perform the actual build.
    • BuildStrategy: Defines the specific list of steps to be executed within the Tekton Task during a BuildRun execution.
    • ClusterBuildStrategy: A cluster-scoped version of BuildStrategy.

  10. Understand the BuildRun resource

    main

    A BuildRun (buildruns.shipwright.io/v1beta1) represents the execution of a Build resource definition within a Kubernetes cluster. It is the primary resource used to monitor the status of an image construction process.

    Key responsibilities of a BuildRun include:

    • Providing a unique name to monitor the build status.
    • Referencing a specific Build instance to execute.
    • Associating a ServiceAccount to host the secrets required for the build process.

    BuildRun resources are namespace-scoped.

    apiVersion: shipwright.io/v1beta1
kind: BuildRun
metadata:
  name: my-build-run
  namespace: my-namespace
spec:
  buildRef:
    name: my-build-definition
  serviceAccountName: build-sa

  11. Understand BuildRun status conditions

    main

    The BuildRun resource uses standard Kubernetes status.conditions to communicate its state. The primary condition type is Succeeded.

    Common states include:

    • Unknown / Pending: Waiting on a Pod.
    • Unknown / Running: Build has started.
    • Unknown / BuildRunCanceled: Cancellation requested but not yet complete.
    • True / Succeeded: Build completed successfully.
    • False / Failed: A build step failed.
    • False / BuildRunTimeout: The build exceeded its timeout.
    • False / VulnerabilitiesFound: The build failed because vulnerabilities were detected (if failOnFinding is set to true).
    • False / [Various Reasons]: Specific errors like MissingParameterValues, ServiceAccountNotFound, or StepOutOfMemory.

  12. Execute a build using the BuildRun API

    main

    A BuildRun is an immutable Custom Resource (CR) that represents a single execution of a Build. While a Build defines the blueprint, the BuildRun triggers the actual execution and allows for overriding specific configuration values that vary by environment (such as resource requirements or target image repositories).

    To trigger a build, create a BuildRun object and reference the desired Build via the spec.buildRef.name field.

    apiVersion: build.dev/v1alpha1
kind: BuildRun
metadata:
  generateName: account-service-build-
spec:
  buildRef:
    name: kaniko-golang-build