Documentation
¶
Index ¶
- Constants
- Variables
- func AcquireTartInspectionLock(ctx context.Context, home string) (func(), error)
- func CleanupWorkspaceRoot(root string, remaining []container.Summary) error
- func CleanupWorkspaceVolumes(ctx context.Context, client RunnerCleanupAPI) error
- func EnsureTartImage(ctx context.Context, runner CommandRunner, image string, logger *slog.Logger) error
- func KeepVMName() string
- func NewRunnerName() string
- func OwnsContainer(labels map[string]string, names []string) bool
- func OwnsTartVM(vm TartVM) bool
- func RemoveRunnerContainer(ctx context.Context, client RunnerCleanupAPI, instanceID string, ...) error
- func TartHomeDir(home string) (string, error)
- func TartImagePresent(ctx context.Context, runner CommandRunner, image string) (bool, error)
- type CommandRunner
- type DockerAPI
- type DockerImagePullCoordinator
- type DockerProvider
- func (p *DockerProvider) CollectDiagnostics(ctx context.Context, id string) (ExitDiagnostics, error)
- func (p *DockerProvider) EnableDiagnosticLogs(enabled bool)
- func (p *DockerProvider) RemoveInstance(ctx context.Context, instanceID string) error
- func (p *DockerProvider) Shutdown(_ context.Context)
- func (p *DockerProvider) StartInstance(ctx context.Context, name string, jitConfig string) (string, error)
- func (p *DockerProvider) WaitInstance(ctx context.Context, instanceID string) error
- func (p *DockerProvider) WaitReady(parent context.Context, id string) error
- type ExitDiagnostics
- type InstanceDiagnostics
- type InstanceProvider
- type InstanceReadiness
- type InstanceWatcher
- type RunnerCleanupAPI
- type TartGuest
- type TartHostCoordinator
- type TartProvider
- func (p *TartProvider) EnsureImage(ctx context.Context) error
- func (p *TartProvider) RemoveInstance(ctx context.Context, instanceID string) error
- func (p *TartProvider) Shutdown(ctx context.Context)
- func (p *TartProvider) StartInstance(ctx context.Context, name string, jitConfig string) (string, error)
- func (p *TartProvider) StartPool(ctx context.Context)
- func (p *TartProvider) WaitInstance(ctx context.Context, instanceID string) error
- type TartVM
Constants ¶
const ( // ManagedByLabel and ManagedByValue tag every container runner creates; // the label is the primary ownership signal for containers. ManagedByLabel = "managed-by" ManagedByValue = "runner" )
Variables ¶
Functions ¶
func AcquireTartInspectionLock ¶ added in v0.22.1
AcquireTartInspectionLock serializes temporary guest inspection and orphan cleanup in one Tart home. It is separate from the manager's lifetime lock, so validate can inspect images while a manager runs. The persistent lock file must not be unlinked: all processes must contend on the same inode.
func CleanupWorkspaceRoot ¶ added in v0.18.1
CleanupWorkspaceRoot reclaims private directories left when the previous manager exited before it could finish runner cleanup. Call only after the machine-wide lock is held and orphan containers were removed successfully.
func CleanupWorkspaceVolumes ¶ added in v0.20.1
func CleanupWorkspaceVolumes(ctx context.Context, client RunnerCleanupAPI) error
CleanupWorkspaceVolumes reclaims local volumes left by a crashed manager after runner reconciliation. A surviving bind or named-volume reference keeps the volume; no unrelated volume is touched.
func EnsureTartImage ¶ added in v0.22.0
func EnsureTartImage(ctx context.Context, runner CommandRunner, image string, logger *slog.Logger) error
EnsureTartImage checks if image exists locally through runner, and pulls it if not. It needs no TartProvider, so a preflight can check an image without building one.
func KeepVMName ¶ added in v0.14.0
func KeepVMName() string
KeepVMName names the throwaway clone a cache prune makes to mark a runner image as recently used (see cachestore's Tart store).
func NewRunnerName ¶ added in v0.14.0
func NewRunnerName() string
NewRunnerName names one ephemeral runner container or VM.
func OwnsContainer ¶ added in v0.14.0
OwnsContainer reports whether a listed container is runner's: labelled by the current release, or named by one whose label value differed. Docker lists names with a leading slash.
func OwnsTartVM ¶ added in v0.14.0
OwnsTartVM reports whether a listed Tart VM is runner's: a local VM named as an ephemeral runner, a warm-pool VM or a cache-prune marker clone. OCI cache entries are never owned, whatever they are called.
func RemoveRunnerContainer ¶ added in v0.17.0
func RemoveRunnerContainer(ctx context.Context, client RunnerCleanupAPI, instanceID string, logger *slog.Logger) error
RemoveRunnerContainer stops a runner, removes containers explicitly tied to it, then removes the runner itself. Keep the stopped runner's metadata until child cleanup succeeds so name-based ownership survives a retry. Anonymous volumes and explicitly owned temporary named volumes are reclaimed; shared/cache volumes, images, and daemon build caches are preserved.
func TartHomeDir ¶ added in v0.22.0
TartHomeDir resolves the directory tart keeps VMs under: home, then $TART_HOME, then ~/.tart.
func TartImagePresent ¶ added in v0.22.0
TartImagePresent reports whether Tart already has image locally.
Types ¶
type CommandRunner ¶
type CommandRunner interface {
Run(ctx context.Context, name string, args ...string) ([]byte, error)
// RunStreaming executes a command with stdout/stderr piped to the terminal.
// Used for long-running commands where progress output is important (e.g. tart pull).
RunStreaming(ctx context.Context, name string, args ...string) error
}
CommandRunner abstracts shell command execution for testability.
func TartCommandRunner ¶ added in v0.14.0
func TartCommandRunner(home string) CommandRunner
TartCommandRunner runs tart against home, or against tart's default ($HOME/.tart) when home is empty.
type DockerAPI ¶
type DockerAPI interface {
RunnerCleanupAPI
ImageInspect(ctx context.Context, image string, options ...dockerclient.ImageInspectOption) (dockerclient.ImageInspectResult, error)
ImagePull(ctx context.Context, ref string, options dockerclient.ImagePullOptions) (dockerclient.ImagePullResponse, error)
VolumeCreate(ctx context.Context, options dockerclient.VolumeCreateOptions) (dockerclient.VolumeCreateResult, error)
ContainerCreate(ctx context.Context, options dockerclient.ContainerCreateOptions) (dockerclient.ContainerCreateResult, error)
ContainerStart(ctx context.Context, containerID string, options dockerclient.ContainerStartOptions) (dockerclient.ContainerStartResult, error)
ContainerWait(ctx context.Context, containerID string, options dockerclient.ContainerWaitOptions) dockerclient.ContainerWaitResult
// ContainerLogs feeds readiness detection and failure diagnostics.
ContainerLogs(ctx context.Context, containerID string, options dockerclient.ContainerLogsOptions) (dockerclient.ContainerLogsResult, error)
// ContainerInspect reports whether a runner is still running and how it
// exited.
ContainerInspect(ctx context.Context, containerID string, options dockerclient.ContainerInspectOptions) (dockerclient.ContainerInspectResult, error)
}
DockerAPI is the slice of the Docker client DockerProvider itself uses to run, watch and diagnose runner containers. internal/cachestore declares its own interface for the daemon-maintenance calls it needs.
type DockerImagePullCoordinator ¶ added in v0.21.0
type DockerImagePullCoordinator struct {
// contains filtered or unexported fields
}
DockerImagePullCoordinator shares in-flight pulls for the same Docker daemon, image, and platform.
func NewDockerImagePullCoordinator ¶ added in v0.21.0
func NewDockerImagePullCoordinator() *DockerImagePullCoordinator
type DockerProvider ¶
type DockerProvider struct {
// contains filtered or unexported fields
}
DockerProvider runs GitHub Actions runners as Docker containers.
func NewDockerProvider ¶
func NewDockerProvider(ss config.ScaleSetConfig, client DockerAPI, logger *slog.Logger) *DockerProvider
NewDockerProvider creates a DockerProvider from scale set config.
func NewDockerProviderWithCoordinator ¶ added in v0.21.0
func NewDockerProviderWithCoordinator(ss config.ScaleSetConfig, client DockerAPI, logger *slog.Logger, coordinator *DockerImagePullCoordinator) *DockerProvider
NewDockerProviderWithCoordinator shares missing-image pulls across Docker scale sets. A nil coordinator gives the provider a private coordinator.
func (*DockerProvider) CollectDiagnostics ¶ added in v0.13.0
func (p *DockerProvider) CollectDiagnostics(ctx context.Context, id string) (ExitDiagnostics, error)
func (*DockerProvider) EnableDiagnosticLogs ¶ added in v0.13.0
func (p *DockerProvider) EnableDiagnosticLogs(enabled bool)
EnableDiagnosticLogs opts into collecting a bounded raw excerpt. Call before starting workers. Redaction and private persistence remain the caller's job.
func (*DockerProvider) RemoveInstance ¶
func (p *DockerProvider) RemoveInstance(ctx context.Context, instanceID string) error
RemoveInstance removes a runner and its explicitly owned child resources.
func (*DockerProvider) Shutdown ¶
func (p *DockerProvider) Shutdown(_ context.Context)
Shutdown is a no-op for DockerProvider. Nothing shared is reclaimed at exit: the shared volume carries handoff data for runs still in flight across a restart, and images and build cache belong to the daemon, not to this process. Every one of them is reclaimed on its own schedule instead, through internal/cachestore — the periodic sweepers in cmd/runner and the disk guard. A per-provider Shutdown that touched any of it would also race the other scale sets sharing this Docker client.
func (*DockerProvider) StartInstance ¶
func (p *DockerProvider) StartInstance(ctx context.Context, name string, jitConfig string) (string, error)
StartInstance creates and starts a new ephemeral Docker container runner.
func (*DockerProvider) WaitInstance ¶
func (p *DockerProvider) WaitInstance(ctx context.Context, instanceID string) error
WaitInstance returns when a runner container is no longer running. The controller uses this to evict containers that crash before GitHub can send JobCompleted.
type ExitDiagnostics ¶ added in v0.13.0
type InstanceDiagnostics ¶ added in v0.13.0
type InstanceDiagnostics interface {
CollectDiagnostics(context.Context, string) (ExitDiagnostics, error)
}
type InstanceProvider ¶
type InstanceProvider interface {
// StartInstance creates and starts a new ephemeral runner with the given
// name and JIT configuration. Returns an instance ID used for cleanup.
StartInstance(ctx context.Context, name string, jitConfig string) (instanceID string, err error)
// RemoveInstance stops and removes a runner by its instance ID. It must be
// idempotent (an already-absent instance is success) and must honor ctx so
// controller drain and shutdown deadlines remain bounded.
RemoveInstance(ctx context.Context, instanceID string) error
// Shutdown performs provider-specific cleanup.
Shutdown(ctx context.Context)
}
InstanceProvider provisions and removes the isolated instance that hosts one ephemeral GitHub Actions runner (a Docker container or Tart VM).
type InstanceReadiness ¶ added in v0.13.0
InstanceReadiness is optional. Resource creation and readiness are distinct: a returned ID stays tracked until readiness, work evidence or safe cleanup.
type InstanceWatcher ¶
InstanceWatcher is optionally implemented by providers that can observe an instance exiting independently of GitHub job messages. A nil return means the instance stopped; a non-nil error means observation failed or the context ended.
type RunnerCleanupAPI ¶ added in v0.17.0
type RunnerCleanupAPI interface {
ContainerStop(context.Context, string, dockerclient.ContainerStopOptions) (dockerclient.ContainerStopResult, error)
ContainerList(context.Context, dockerclient.ContainerListOptions) (dockerclient.ContainerListResult, error)
ContainerRemove(context.Context, string, dockerclient.ContainerRemoveOptions) (dockerclient.ContainerRemoveResult, error)
VolumeList(context.Context, dockerclient.VolumeListOptions) (dockerclient.VolumeListResult, error)
VolumeRemove(context.Context, string, dockerclient.VolumeRemoveOptions) (dockerclient.VolumeRemoveResult, error)
}
RunnerCleanupAPI is the lifecycle-only surface needed to remove a runner and its explicitly owned resources. Daemon pruning remains in cachestore.
type TartGuest ¶ added in v0.22.0
type TartGuest int
TartGuest is the guest operating system of a Tart image. The zero value is macOS, so an unknown guest is always held to Apple's limit.
func DetectTartGuest ¶ added in v0.22.0
func DetectTartGuest(ctx context.Context, runner CommandRunner, home, image string) (TartGuest, error)
DetectTartGuest reads the guest OS from a temporary clone of image. OCI image references have no local config.json until Tart clones them.
type TartHostCoordinator ¶
type TartHostCoordinator struct {
// contains filtered or unexported fields
}
TartHostCoordinator limits macOS guests and gives every Tart VM a unique MAC slot across all scale sets in this process.
func NewTartHostCoordinator ¶
func NewTartHostCoordinator(macOSLimit int) *TartHostCoordinator
type TartProvider ¶
type TartProvider struct {
// contains filtered or unexported fields
}
TartProvider runs GitHub Actions runners as ephemeral Tart macOS VMs.
Lifecycle per runner:
- tart clone <baseImage> <name> — APFS CoW clone (< 1 sec)
- tart set <name> --cpu/--memory — configure VM resources (if specified)
- Set deterministic MAC address — prevent DHCP lease exhaustion
- tart run <name> --no-graphics — boot VM in background goroutine (--net-bridged=<interface> when configured)
- tart exec <name> true — poll until Guest Agent is ready
- tart exec <name> ... run.sh — start runner with JIT config
- tart stop + tart delete on removal
When poolSize > 0, VMs are pre-booted and kept ready in a pool. StartInstance picks a warm VM from the pool (near-instant) instead of cold-starting one (~30s). The pool is refilled in the background.
func NewTartProviderWithCoordinator ¶
func NewTartProviderWithCoordinator(ss config.ScaleSetConfig, logger *slog.Logger, coordinator *TartHostCoordinator, guest TartGuest) *TartProvider
NewTartProviderWithCoordinator creates a TartProvider from scale set config. coordinator is shared by every Tart scale set on the host so MAC slots and the two-VM limit are host-wide; nil gets a private one.
func (*TartProvider) EnsureImage ¶
func (p *TartProvider) EnsureImage(ctx context.Context) error
EnsureImage checks if the base image exists locally, and pulls it if not.
func (*TartProvider) RemoveInstance ¶
func (p *TartProvider) RemoveInstance(ctx context.Context, instanceID string) error
RemoveInstance stops and deletes a Tart VM, releasing its VM slot.
func (*TartProvider) Shutdown ¶
func (p *TartProvider) Shutdown(ctx context.Context)
Shutdown stops the warm pool and cleans up any idle VMs.
func (*TartProvider) StartInstance ¶
func (p *TartProvider) StartInstance(ctx context.Context, name string, jitConfig string) (string, error)
StartInstance starts a GitHub Actions runner in a Tart VM. If a warm pool is available, picks a pre-booted VM (near-instant). Otherwise, cold-starts a new VM (~30s).
func (*TartProvider) StartPool ¶
func (p *TartProvider) StartPool(ctx context.Context)
StartPool begins pre-warming VMs in the background. Call this after EnsureImage and before the listener starts.
func (*TartProvider) WaitInstance ¶
func (p *TartProvider) WaitInstance(ctx context.Context, instanceID string) error
type TartVM ¶ added in v0.14.0
type TartVM struct {
Name string `json:"Name"`
Source string `json:"Source"` // "local" for VMs, "OCI" for cached images
State string `json:"State"`
}
TartVM is one entry of `tart list --format json`.
func ListTartVMs ¶ added in v0.14.0
ListTartVMs lists every VM and cached image visible through runner. extra narrows the listing with further `tart list` flags, such as "--source", "oci".