builder

Documentation

Overview

Package builder builds container images from source using a managed buildkitd (spec §3.4). T-33 covers Dockerfile builds — including multi-arch image indexes via BuildKit's multi-platform solve — pushed straight to the embedded registry. Nixpacks source resolution is layered on in T-34, and the build queue/dispatch/RPC in T-35.

Index

• type BuildEvent
• type BuildKind
  • func ResolveBuildType(dir string) BuildKind
• type BuildResult
• type Builder
  • func New(rt runtime.ContainerRuntime, clk clock.Clock, dataDir, caPath string, ...) *Builder
  • func (b *Builder) Build(ctx context.Context, req RunBuildRequest, events chan<- BuildEvent) (*BuildResult, error)
  • func (b *Builder) BuildFromSource(ctx context.Context, req RunBuildRequest, src io.Reader, ...) (*BuildResult, error)
  • func (b *Builder) BuildNixpacks(ctx context.Context, req RunBuildRequest, events chan<- BuildEvent) (*BuildResult, error)
  • func (b *Builder) EnsureBuildkitd(ctx context.Context, onLog func(string)) (*bkclient.Client, error)
  • func (b *Builder) EnsureEmulators(ctx context.Context, platforms []string) error
• type RegistryAuth
• type RunBuildRequest

Types

type BuildEvent

type BuildEvent struct {
	Phase       string
	Log         string
	Done        bool
	Success     bool
	ImageRef    string
	ImageDigest string
	Platforms   []string
	Err         string
}

BuildEvent is one item of build progress. Log events carry a line (and a Phase: "plan" for the nixpacks planner, "build" for the BuildKit solve); the final event has Done set with the outcome and (on success) the pushed image ref, its digest (the INDEX digest for multi-arch), and the built platforms.

type BuildKind

type BuildKind int

BuildKind is the resolved build strategy for a source tree.

const (
	// BuildDockerfile builds a Dockerfile already present in the source.
	BuildDockerfile BuildKind = iota
	// BuildNixpacks generates a Dockerfile with nixpacks first.
	BuildNixpacks
)

func ResolveBuildType

func ResolveBuildType(dir string) BuildKind

ResolveBuildType decides how to build a source tree when the app's build type is unspecified: a Dockerfile in the context root means a Dockerfile build, otherwise nixpacks generates one. (T-35 maps the proto BuildType; this owns the BUILD_TYPE_UNSPECIFIED auto-detect.)

type BuildResult

type BuildResult struct {
	ImageRef    string
	ImageDigest string
	Platforms   []string
}

BuildResult is the terminal outcome of a successful build.

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

Builder ensures a managed buildkitd and runs Dockerfile builds against it.

func New

func New(rt runtime.ContainerRuntime, clk clock.Clock, dataDir, caPath string, log *slog.Logger) *Builder

New constructs a Builder. dataDir is the node data dir (the buildkitd socket lives under it); caPath is the host path to the cluster CA bundle mounted into buildkitd so registry pushes verify TLS.

func (*Builder) Build

func (b *Builder) Build(ctx context.Context, req RunBuildRequest, events chan<- BuildEvent) (*BuildResult, error)

Build runs a Dockerfile build for req and pushes the result to the registry. Progress (log lines and the terminal outcome) is streamed on events; the terminal BuildResult is also returned. For more than one platform the exporter emits an OCI image index and ImageDigest is the index digest.

func (*Builder) BuildFromSource

func (b *Builder) BuildFromSource(ctx context.Context, req RunBuildRequest, src io.Reader, events chan<- BuildEvent) (*BuildResult, error)

BuildFromSource unpacks a source tarball into a scratch dir, resolves the build strategy (Dockerfile vs nixpacks), and builds it. This is the entry point the agent's build server calls after fetching the tarball from control.

func (*Builder) BuildNixpacks

func (b *Builder) BuildNixpacks(ctx context.Context, req RunBuildRequest, events chan<- BuildEvent) (*BuildResult, error)

BuildNixpacks generates a Dockerfile from req's context with the nixpacks planner, then builds it through the T-33 Dockerfile pipeline. The planner is architecture-independent, so a multi-arch request plans exactly once and lets BuildKit fan out per platform. The build context stays the source tree; only the Dockerfile path changes to the generated one under .nixpacks/.

func (*Builder) EnsureBuildkitd

func (b *Builder) EnsureBuildkitd(ctx context.Context, onLog func(string)) (*bkclient.Client, error)

EnsureBuildkitd makes sure the managed buildkitd container is running and its API answers, then returns a connected client. Safe to call before every build (idempotent).

func (*Builder) EnsureEmulators

func (b *Builder) EnsureEmulators(ctx context.Context, platforms []string) error

EnsureEmulators installs QEMU binfmt handlers for any target platform the builder cannot execute natively. It is a no-op when every target is native.

type RegistryAuth

type RegistryAuth struct {
	Registry string
	Username string
	Password string
}

RegistryAuth carries push credentials for the target registry.

type RunBuildRequest

type RunBuildRequest struct {
	BuildID    string
	Project    string
	App        string
	Registry   string // "host:port" of the target registry
	Dockerfile string // path within the context; default "Dockerfile"
	ContextDir string // subdir within the source; default "."
	BuildArgs  map[string]string
	Platforms  []string     // target OCI platforms; empty → builder's native
	SourceDir  string       // unpacked source root
	Auth       RegistryAuth // creds for pushing to the registry
	// ImageRef, when set, is the exact push reference; otherwise it is derived
	// from Registry/Project/App/BuildID.
	ImageRef string
	// RegistryInsecure pushes over plain HTTP (integration tests only).
	RegistryInsecure bool
	// LoadLocally loads the built image straight into the local Docker image
	// store instead of pushing it to a registry (single-node/dev, T-54): the
	// host Docker daemon cannot pull from the insecure loopback registry.
	LoadLocally bool
}

RunBuildRequest describes one image build. T-35 maps the AgentLocalService RunBuild proto onto this struct; keeping it a plain type keeps the builder package free of proto/agent imports.