api

package
v0.8.9 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package api implements the build provider layer for the BlanketOps Environments build domain.

This file owns the Buildah provider — the concrete implementation that translates a resolved BlanketOps Build contract into Shipwright resources and dispatches execution.

The provider sits below the application service layer and above the Shipwright API. It is responsible for:

  • Constructing Shipwright Build and BuildRun specs from the resolved contract.
  • Applying owner references so Shipwright resources are garbage-collected with the parent Build CR.
  • Ensuring idempotent upsert of the Shipwright Build (create or update).
  • Creating the BuildRun only when no run for the current execution hash exists, preventing duplicate builds on re-reconciliation.

The provider does NOT wait for the BuildRun to complete. Completion is observed asynchronously by the buildrun observer (internal/controller/observers/buildrun). Run() returns Triggered=true, Success=false to signal intent dispatch — the final outcome is written to the Build CR by the observer.

This file owns the Buildpacks provider — structurally identical to the Buildah provider but registered under the "buildpacks-v3" strategy name. Shipwright selects the ClusterBuildStrategy at run time; the provider layer is responsible only for constructing the correct spec and dispatching execution.

See buildah.go for the canonical documentation of the shared pipeline pattern. TODO: consolidate Buildah, Buildpacks, and Kaniko into a single generic provider parameterised by strategy name once the provider interface is stable.

This file owns the helpers that keep the build providers declarative: a Shipwright object carries what the Build contract declares and nothing it does not.

Each helper returns nil for an undeclared value, so the field is left off the object rather than written with an empty name that Shipwright would then try to resolve. They are shared by the Buildah, Kaniko and Buildpacks providers.

Package api implements the build provider layer for the BlanketOps Environments build domain.

This file owns the Kaniko provider — structurally identical to the Kaniko provider but registered under the "kaniko" strategy name. Shipwright selects the ClusterBuildStrategy at run time; the provider layer constructs the spec and dispatches execution.

The provider sits below the application service layer and above the Shipwright API. It is responsible for:

  • Constructing Shipwright Build and BuildRun specs from the resolved contract.
  • Applying owner references so Shipwright resources are garbage-collected with the parent Build CR.
  • Ensuring idempotent upsert of the Shipwright Build (create or update).
  • Creating the BuildRun only when no run for the current execution hash exists, preventing duplicate builds on re-reconciliation.

The provider does NOT wait for the BuildRun to complete. Completion is observed asynchronously by the buildrun observer (internal/controller/observers/buildrun). Run() returns Triggered=true, Success=false to signal intent dispatch — the final outcome is written to the Build CR by the observer.

This file owns the Provider interface — the execution contract that all build backend implementations (Buildah, Kaniko, Buildpacks) must satisfy.

A Provider receives a resolved Build and a domain spec, dispatches a Shipwright BuildRun, and returns immediately. It does not block on completion — the buildrun observer writes the final outcome back to the Build CR asynchronously.

Concrete implementations live alongside this file (buildah.go, kaniko.go, buildpacks.go). The BackendSelector (pkg/build/application/backend_selector.go) routes a resolved BuildSpec to the correct provider based on the strategy name.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExtractTriggerContext

func ExtractTriggerContext(build *buildv1.Build) domain.TriggerContext

ExtractTriggerContext derives execution trigger metadata from Build annotations. It is the only place in the provider layer that reads Kubernetes object metadata — all other inputs arrive via the resolved spec.

Annotations are written by the BuildTrigger domain when it patches the Build CR before dispatching. If none are present the trigger is assumed to be manual (operator or CI invoking the reconciler directly).

The returned TriggerContext is fed into utils.ComputeExecutionHash to produce the execution identity used for BuildRun deduplication.

func PatchBuildTriggerFromGitHubEvent

func PatchBuildTriggerFromGitHubEvent(ctx context.Context, c client.Client, build *buildv1.Build) error

PatchBuildTriggerFromGitHubEvent looks up the latest push GitHubEvent for the given Build's repository and patches the Build's annotations with the trigger metadata. No-op if no matching event with payload exists.

This is called by the provider before creating the BuildRun so the execution hash includes the correct commit SHA.

Types

type BuildahProvider

type BuildahProvider struct {
	Client client.Client
	Scheme *runtime.Scheme
	Log    logr.Logger

	Recorder events.EventRecorder
}

BuildahProvider orchestrates Shipwright Build and BuildRun resources on behalf of the BlanketOps build domain. It is the only component in the platform that writes Shipwright API objects directly.

func NewBuildahProvider

func NewBuildahProvider(client client.Client, scheme *runtime.Scheme, log logr.Logger, recorder events.EventRecorder) *BuildahProvider

NewBuildahProvider constructs a BuildahProvider with the given dependencies. rec may be nil — the provider does not emit events directly.

func (*BuildahProvider) CreateBuildRunSpec

func (p *BuildahProvider) CreateBuildRunSpec(build *buildResolution.ResolvedBuild, shipwrightBuild *shipwrightv1alpha1.Build, fullHash string) *shipwrightv1alpha1.BuildRun

CreateBuildRunSpec constructs a Shipwright BuildRun for the given resolved Build and execution hash. The run name is derived from the Build name and a short hash suffix, ensuring a unique run per execution identity.

Labels carry the execution identity for the buildrun observer to resolve the owning Build CR and for retry counting (list by build name + hash). The full hash is preserved in an annotation for audit purposes.

func (*BuildahProvider) CreateBuildSpec

CreateBuildSpec translates a domain.BuildSpec and resolved Build contract into a Shipwright Build object. Validates that SourceURL and Image are present — both are required for Shipwright to accept the Build.

The returned Build has labels for domain ownership tracking ("build.blanketops.dev/name") but no owner reference — that is applied by the caller via controllerutil.SetControllerReference before creation.

Timeout is intentionally omitted from the Shipwright BuildSpec — timeout policy is enforced at the BuildRun level by Shipwright's own machinery.

func (*BuildahProvider) Run

Run orchestrates the full Shipwright dispatch pipeline for the given resolved Build and spec. It upserts the Shipwright Build and creates the BuildRun, then returns immediately with Triggered=true.

Run does NOT block on BuildRun completion. The buildrun observer (internal/controller/observers/buildrun) watches for terminal state and writes the final outcome back to the Build CR asynchronously.

Idempotency: the Shipwright Build is always upserted. The BuildRun is only created if no run for the current execution hash exists — a hash collision (same spec + same trigger context) is treated as "already triggered" and the existing run is reused.

func (*BuildahProvider) Teardown

Teardown deletes the Shipwright Build and all BuildRuns this provider created for the given Build CR. Unlike Run, which creates at most one BuildRun per execution hash, Teardown removes every BuildRun labeled with this Build's name — CreateBuildRunSpec names runs by hash, so multiple runs can accumulate across generations and all must be cleared.

Idempotent — a missing Build or empty BuildRun list is not an error. Ownership is via controllerutil.SetControllerReference, so Kubernetes GC would eventually reclaim these once the parent Build CR is deleted, but teardown deletes explicitly and synchronously rather than depending on GC timing to complete before the finalizer is removed.

type BuildpacksProvider

type BuildpacksProvider struct {
	Client   client.Client
	Scheme   *runtime.Scheme
	Log      logr.Logger
	Recorder events.EventRecorder // optional; may be nil
}

BuildpacksProvider orchestrates Shipwright Build and BuildRun resources using the buildpacks-v3 ClusterBuildStrategy.

func NewBuildpacksProvider

func NewBuildpacksProvider(
	c client.Client,
	scheme *runtime.Scheme,
	log logr.Logger,
	rec events.EventRecorder,
) *BuildpacksProvider

NewBuildpacksProvider constructs a BuildpacksProvider with the given dependencies.

func (*BuildpacksProvider) CreateBuildRunSpec

func (p *BuildpacksProvider) CreateBuildRunSpec(
	build *buildResolution.ResolvedBuild,
	shipwrightBuild *shipwrightv1alpha1.Build,
	fullHash string,
) *shipwrightv1alpha1.BuildRun

CreateBuildRunSpec constructs a Shipwright BuildRun for the given resolved Build and execution hash. Run name is derived from the Build name and a short hash suffix. Full hash is preserved in an annotation for audit.

func (*BuildpacksProvider) CreateBuildSpec

CreateBuildSpec translates a domain.BuildSpec into a Shipwright Build object. Validates SourceURL and Image — both are required by Shipwright. Owner reference is applied by the caller before creation.

func (*BuildpacksProvider) Run

Run upserts the Shipwright Build and creates the BuildRun, then returns immediately with Triggered=true, Success=false. Completion is observed asynchronously by the buildrun observer.

func (*BuildpacksProvider) Teardown

Teardown deletes the Shipwright Build and all BuildRuns this provider created for the given Build CR. Unlike Run, which creates at most one BuildRun per execution hash, Teardown removes every BuildRun labeled with this Build's name — CreateBuildRunSpec names runs by hash, so multiple runs can accumulate across generations and all must be cleared.

Idempotent — a missing Build or empty BuildRun list is not an error. Ownership is via controllerutil.SetControllerReference, so Kubernetes GC would eventually reclaim these once the parent Build CR is deleted, but teardown deletes explicitly and synchronously rather than depending on GC timing to complete before the finalizer is removed.

type KanikoProvider

type KanikoProvider struct {
	Client   client.Client
	Scheme   *runtime.Scheme
	Log      logr.Logger
	Recorder events.EventRecorder
}

KanikoProvider orchestrates Shipwright Build and BuildRun resources on behalf of the BlanketOps build domain. It is the only component in the platform that writes Shipwright API objects directly.

func NewKanikoProvider

func NewKanikoProvider(client client.Client, scheme *runtime.Scheme, log logr.Logger, recorder events.EventRecorder) *KanikoProvider

NewKanikoProvider constructs a KanikoProvider with the given dependencies. rec may be nil — the provider does not emit events directly.

func (*KanikoProvider) CreateBuildRunSpec

func (p *KanikoProvider) CreateBuildRunSpec(build *buildResolution.ResolvedBuild, shipwrightBuild *shipwrightv1alpha1.Build, fullHash string) *shipwrightv1alpha1.BuildRun

CreateBuildRunSpec constructs a Shipwright BuildRun for the given resolved Build and execution hash. The run name is derived from the Build name and a short hash suffix, ensuring a unique run per execution identity.

Labels carry the execution identity for the buildrun observer to resolve the owning Build CR and for retry counting (list by build name + hash). The full hash is preserved in an annotation for audit purposes.

func (*KanikoProvider) CreateBuildSpec

CreateBuildSpec translates a domain.BuildSpec and resolved Build contract into a Shipwright Build object. Validates that SourceURL and Image are present — both are required for Shipwright to accept the Build.

The returned Build has labels for domain ownership tracking ("build.blanketops.dev/name") but no owner reference — that is applied by the caller via controllerutil.SetControllerReference before creation.

Timeout is intentionally omitted from the Shipwright BuildSpec — timeout policy is enforced at the BuildRun level by Shipwright's own machinery.

func (*KanikoProvider) Run

Run orchestrates the full Shipwright dispatch pipeline for the given resolved Build and spec. It upserts the Shipwright Build and creates the BuildRun, then returns immediately with Triggered=true.

Run does NOT block on BuildRun completion. The buildrun observer (internal/controller/observers/buildrun) watches for terminal state and writes the final outcome back to the Build CR asynchronously.

Idempotency: the Shipwright Build is always upserted. The BuildRun is only created if no run for the current execution hash exists — a hash collision (same spec + same trigger context) is treated as "already triggered" and the existing run is reused.

func (*KanikoProvider) Teardown

Teardown deletes the Shipwright Build and all BuildRuns this provider created for the given Build CR. Unlike Run, which creates at most one BuildRun per execution hash, Teardown removes every BuildRun labeled with this Build's name — CreateBuildRunSpec names runs by hash, so multiple runs can accumulate across generations and all must be cleared.

Idempotent — a missing Build or empty BuildRun list is not an error. Ownership is via controllerutil.SetControllerReference, so Kubernetes GC would eventually reclaim these once the parent Build CR is deleted, but teardown deletes explicitly and synchronously rather than depending on GC timing to complete before the finalizer is removed.

type Provider

type Provider interface {
	Run(ctx context.Context, resolved *buildResolution.ResolvedBuild, spec domain.BuildSpec) (domain.BuildResult, error)

	// Teardown deletes the Shipwright Build and any BuildRuns this provider
	// created for the given resolved Build. Called from the domain's
	// CmdDelete branch via BuildService.Teardown, gated by the finalizer at
	// the controller level. Idempotent — a missing Build or BuildRun is not
	// an error.
	Teardown(ctx context.Context, resolved *buildResolution.ResolvedBuild) error
}

Provider is the build execution contract implemented by all build backends.

  • resolved.Build → Kubernetes object metadata, namespace, owner refs.
  • resolved.Spec → typed contract semantics decoded from spec.contract.
  • spec → internal domain projection for Shipwright spec construction.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL