How shipwright-io/build works
Main Components
• Build Controller & Reconcilers: This is the core component, found in pkg/controller and pkg/reconciler. It orchestrates custom resources (Build, BuildRun, BuildStrategy, and ClusterBuildStrategy) and implements the control loop pattern.
• CRDs & API Schemas: Located in deploy/crds and pkg/apis, these define the custom resource definitions corresponding to the Shipwright API (e.g., build and buildrun objects).
• Command Line Tools and Entrypoints: Under the cmd folder, there are multiple binaries (such as “bundle”, “git”, “image-processing”, “waiter”, and webhooks). These represent specific runtime executables that start different aspects of Shipwright (e.g., controller, webhook serving, or auxiliary tooling).
• Client Libraries and Informers: Under pkg/client and pkg/client/informers (and corresponding “listers”), these provide necessary convenience abstractions to interact with the Kubernetes API server for working with the custom resources.
• Webhook Component: In pkg/webhook (and in cmd/shipwright-build-webhook) covers dynamic conversion or validation tasks, ensuring that CRD changes are applied correctly.
• Image Processing and Git Integration Modules: Seen in pkg/image and pkg/git, these components handle specialized tasks such as mutating or processing images and interfacing with Git repositories.
• Deployment & Infrastructure Files: The deploy directory houses YAMLs that set up namespaces, roles, service accounts, and the controllers themselves in a Kubernetes cluster.
Relationships/Interactions Between Components
• Controllers (in pkg/controller/reconciler) watch the Kubernetes API for changes in custom resources. They use client libraries (informers, listers) to efficiently “observe” Build, BuildRun, etc.
• When a user creates a Build CR (via YAML deployment as detailed in the README), the controller picks it up, reconciles its desired state, and triggers associated actions (like starting a BuildRun).
• The webhook (packaged as cmd/shipwright-build-webhook and code in pkg/webhook) validates and/or converts incoming requests to the correct API version.
• The command-line tools (cmd/git, cmd/image-processing) executed in containers (whose Dockerfiles are in images/*) perform isolated tasks (e.g., fetching source code, mutating OCI images) as part of the build process.
• External integrations (container registries, Tekton Pipelines) are indirectly reached via the Build strategies that call out to these tools – as referenced in the README instructions.
Architectural Patterns & Design Principles
• Kubernetes Controller Pattern: The system heavily relies on CRDs, informers, listers and reconcilers to observe and act upon changes in the cluster.
• Modular Design: Separation of functionalities (APIs, controllers, webhooks, stand-alone command line tools) across subdirectories promotes maintainability and independent evolution.
• Extensibility: The project supports multiple build strategies by having a flexible API design and a pluggable reconciling mechanism.
• Continuous Integration & Development: Presence of extensive test directories (test/e2e, test/integration) and CI workflow configurations in /.github shows a commitment to automated testing and deployment practices.
Relevant Technologies/Frameworks
• Kubernetes (with Custom Resource Definitions)
• Tekton Pipelines, which is a key dependency for build process execution
• Go modules for dependency management (go.mod, go.sum)
• Container images built using Dockerfiles under images/*
• Git for source code versioning (cmd/git, pkg/git)
• Maintain clarity by grouping related components (for example, grouping all client libraries and informers together) so that the interactions are obvious.