Documentation
¶
Overview ¶
Package runners maintains the live tunnels of connected build/pipeline runners. It mirrors the node-agent connection manager but is thinner: a runner uses its OWN Docker/BuildKit daemon, so the tunnel exists only to lease jobs to it and stream logs and status back.
Index ¶
- Variables
- func BuildJobSpec(in JobInputs) (proto.JobSpec, []string)
- func CacheRefs(repository, branch, trunk string, gen uint) (from []string, to string)
- type BuildInputs
- type CredentialMinter
- type Deployer
- type Dispatcher
- func (d *Dispatcher) Dispatch(ctx context.Context, in JobInputs, requiredLabels []string, subjectUserID uint) error
- func (d *Dispatcher) RunBuild(ctx context.Context, in BuildInputs, subjectUserID uint, onLog func(string)) (string, error)
- func (d *Dispatcher) RunnerWaitReason(workspaceID uint) string
- func (d *Dispatcher) SetDeployer(dep Deployer)
- func (d *Dispatcher) SetLogStore(s *logstore.Store)
- func (d *Dispatcher) SetSecrets(r SecretResolver)
- func (d *Dispatcher) SweepExpiredLeases(now time.Time) ([]models.RunnerLease, error)
- func (d *Dispatcher) WaitReason(in JobInputs) string
- type ImageRecorder
- type JobCredentials
- type JobInputs
- type Manager
- type Publisher
- type RunStore
- type SecretResolver
Constants ¶
This section is empty.
Variables ¶
var ErrRunnerOffline = errors.New("selected runner is offline")
ErrRunnerOffline is returned when the scheduler picked a runner whose tunnel dropped between selection and dispatch (the run should be requeued).
ErrSecretsUnavailable is returned when a pipeline references a secret but no vault is wired. Failing beats sending the literal reference to a runner.
Functions ¶
func BuildJobSpec ¶
BuildJobSpec assembles the wire JobSpec sent to a runner: the predefined, non-secret MIABI_* build context plus the per-job secret credentials (as env, masked from the log stream), and the run's steps. Returns the spec and the secret values to redact from live logs.
func CacheRefs ¶ added in v1.8.4
CacheRefs derives the registry refs a build reads its layer cache from and writes it to.
The export ref is always the building branch's own, and gen names the current cache generation: bumping it points every build at a ref that does not exist yet, which is a cold build now and a warm one after. A branch build additionally READS the trunk's cache but never writes to it — a pipeline is editable by anyone who can push a branch, so a shared export would let a branch build seed layers into the cache a trunk build trusts.
An empty repository (nothing to push to) disables the cache entirely.
Types ¶
type BuildInputs ¶
type BuildInputs struct {
DeploymentID uint // lease/credential id (globally unique; leased under LeaseKindBuild)
DeploymentNumber int // per-app sequential number (v1, v2, …); the image tag
WorkspaceID uint
WorkspaceName string
AppID uint
AppName string
SourceURL string // git remote the runner clones (may embed a credential)
Commit string
Ref string
Branch string
Repository string // fully-qualified push target (registry/ns/app)
Registry string // registry host
Build *proto.BuildConfig
RequiredLabels []string // runner selection constraints (arch/…); usually empty
}
BuildInputs describes a standalone image build — a git-source app deploy, not a pipeline run. The runner clones SourceURL at Commit, builds per Build, and pushes to Repository; the Dispatcher fills the per-job credentials and deadline.
type CredentialMinter ¶
type CredentialMinter struct {
// contains filtered or unexported fields
}
CredentialMinter issues (and revokes) a run's ephemeral job credentials as APIKey rows, so they ride the exact same auth/RBAC/audit path as a user token.
func NewCredentialMinter ¶
func NewCredentialMinter(keys *auth.APIKeyService, jobTokenEnabled bool) *CredentialMinter
func (*CredentialMinter) Mint ¶
func (m *CredentialMinter) Mint(subjectUserID, workspaceID uint, appID *uint, runID uint, deadline time.Time) (*JobCredentials, error)
Mint issues the per-job registry credential (registry_write, bound to the app) and, unless withheld by config, the MIABI_JOB_TOKEN callback. Both expire at the job deadline and are attributed to the run's subject user for audit. Call Revoke when the run goes terminal.
func (*CredentialMinter) Revoke ¶
func (m *CredentialMinter) Revoke(creds *JobCredentials)
Revoke kills a run's minted credentials the moment the run reaches a terminal state. They also expire at the deadline regardless (defense in depth).
type Deployer ¶
type Deployer interface {
DeployByDigest(run *models.PipelineRun, appID uint, imageRef string) error
}
Deployer performs a deploy-by-digest: it creates a deployment of the image a runner built and enqueues it to the target node, which pulls and runs it — the node never builds. Implemented by the worker's pipeline deployer; nil-safe (unset = a build-only pipeline that never deploys).
type Dispatcher ¶
type Dispatcher struct {
// contains filtered or unexported fields
}
Dispatcher runs a pipeline run on a runner: it selects and leases one, opens a stream over its tunnel, sends the JobSpec, and applies the report frames back onto the run. This is the control-plane counterpart to the runner's job loop, over the shared runner/proto contract.
func NewDispatcher ¶
func NewDispatcher(runners *runner.Service, sessions *Manager, minter *CredentialMinter, runs RunStore, images ImageRecorder, bus Publisher, timeout time.Duration) *Dispatcher
func (*Dispatcher) Dispatch ¶
func (d *Dispatcher) Dispatch(ctx context.Context, in JobInputs, requiredLabels []string, subjectUserID uint) error
Dispatch selects and leases a runner for the run, mints its per-job credentials, sends the job, and processes the report stream to completion, revoking credentials and releasing the lease on the way out. ErrNoRunner and ErrRunnerOffline are returned unchanged so the caller can requeue.
func (*Dispatcher) RunBuild ¶
func (d *Dispatcher) RunBuild(ctx context.Context, in BuildInputs, subjectUserID uint, onLog func(string)) (string, error)
RunBuild dispatches a one-step image build to an eligible runner and drives it to completion, streaming log lines to onLog and returning the pushed digest. Unlike the pipeline path it persists nothing; the build is leased under LeaseKindBuild so it never collides with a run.
func (*Dispatcher) RunnerWaitReason ¶
func (d *Dispatcher) RunnerWaitReason(workspaceID uint) string
RunnerWaitReason explains why no runner is currently available for a build in workspaceID, for the deploy's "waiting for a runner" message. "" means one is actually available.
func (*Dispatcher) SetDeployer ¶
func (d *Dispatcher) SetDeployer(dep Deployer)
SetDeployer wires the deploy-by-digest hook, so a pipeline's terminal deploy step rolls the runner-built image out to the target node (nil-safe).
func (*Dispatcher) SetLogStore ¶
func (d *Dispatcher) SetLogStore(s *logstore.Store)
SetLogStore wires the shared log store so a pipeline step's full log is externalized (with a bounded DB tail) when the run reaches a terminal state. Without it, only the bounded tail is kept in the step's DB row. nil-safe.
func (*Dispatcher) SetSecrets ¶ added in v1.8.2
func (d *Dispatcher) SetSecrets(r SecretResolver)
SetSecrets wires the workspace vault used to resolve ${{ secrets.NAME }} in a pipeline's env. Without it, a pipeline that references one fails to dispatch.
func (*Dispatcher) SweepExpiredLeases ¶
func (d *Dispatcher) SweepExpiredLeases(now time.Time) ([]models.RunnerLease, error)
SweepExpiredLeases releases every active lease whose deadline has passed and returns them. A runner that died mid-job never runs the lease's release defer, so without this the lease counts against its concurrency forever and starves it. The affected runs re-attempt on their own.
func (*Dispatcher) WaitReason ¶ added in v1.10.8
func (d *Dispatcher) WaitReason(in JobInputs) string
WaitReason explains why no runner can take the pipeline run right now, counting what its steps need, such as a runner that builds for several platforms. "" means one is actually available.
type ImageRecorder ¶
type ImageRecorder interface {
Record(in imagesvc.RecordInput) (*models.Image, error)
}
ImageRecorder stamps provenance for an image a runner built and pushed by digest. Satisfied by *image.Service.
type JobCredentials ¶
type JobCredentials struct {
RegistryUser string
RegistryToken string // MIABI_REGISTRY_TOKEN — registry read+write, this app's repo
JobToken string // MIABI_JOB_TOKEN — deploy, this app/run (empty if disabled)
// contains filtered or unexported fields
}
JobCredentials are the per-job, short-lived secrets injected into a runner job: a registry login scoped to this app's repo, and an optional callback token scoped to deploy just this app/run. Both are ephemeral APIKey rows, so a leaked value is useless once the run ends or expires.
func (*JobCredentials) Secrets ¶
func (c *JobCredentials) Secrets() []string
Secrets returns the credential values that must be redacted from the run's live log stream (a step that echoes one prints ••••).
type JobInputs ¶
type JobInputs struct {
Run *models.PipelineRun
Pipeline string // pipeline name (MIABI_PIPELINE)
Steps []models.PipelineStepRun
AppID *uint
AppName string
WorkspaceName string // workspace handle (MIABI_WORKSPACE_NAME)
Registry string // registry host (MIABI_REGISTRY)
Repository string // fully-qualified image repo (MIABI_IMAGE_REPOSITORY)
Ref string
Branch string
SourceURL string // git remote the runner clones + checks out at the commit
Workdir string // defaults to /workspace
// Env is the pipeline-level environment, applied to every step. Values may
// still carry ${{ secrets.NAME }}; the Dispatcher resolves them.
Env map[string]string
// CacheGeneration names the app's current build cache; CacheTrunk is the ref whose cache a branch
// build may read. CacheCold forces a rebuild after a bump — a runner whose cache is its local
// daemon has no ref to rotate, so it has to be told.
CacheGeneration uint
CacheTrunk string
CacheCold bool
// Filled by the Dispatcher.
Creds *JobCredentials
Deadline time.Time
}
JobInputs is the run-derived context a caller supplies to build a JobSpec. The Dispatcher fills in the per-run Deadline, Creds, and runner name.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager accepts runner tunnels and tracks each runner's live session and online/offline status.
func NewManager ¶
func NewManager(state connectionState) *Manager
NewManager creates a runner connection manager backed by the runner service (for status persistence).
func (*Manager) AddStatusListener ¶ added in v1.10.18
AddStatusListener registers a hook fired when a runner's tunnel comes up or goes down, so the console can show a newly enrolled runner without a reload. Hooks run in order on the tunnel's goroutine, keeping a quick drop and reconnect in sequence, so they must not block.
func (*Manager) Disconnect ¶
Disconnect tears down a runner's tunnel (e.g. when it is deleted or disabled).
type RunStore ¶
type RunStore interface {
UpdateRun(*models.PipelineRun) error
UpdateStep(*models.PipelineStepRun) error
SetRunImage(runID, imageID uint) error
}
RunStore persists a run and its steps as report frames arrive. Satisfied by *repositories.PipelineRepository.