Documentation
¶
Overview ¶
Package docker runs jobs in containers.
ISOLATION IS MATERIALLY WEAKER THAN A MICROVM. A container shares the host kernel, so this backend is for trying billet out and for developing it on a machine with no hypervisor — it is not the production story, and it must refuse untrusted pull-request work outright rather than warn about it.
It exists because it was the only backend this project could execute at all, and it remains the only one that runs on the machine billet is running on. Firecracker needs Linux and /dev/kvm; tart needs Apple Silicon and a licence carve-out; ec2 exists now but launches somewhere else and needs an account. Writing the whole launch path with nothing able to run it is how the launch path ends up wrong in ways no test notices.
Index ¶
- type Instance
- type Option
- type Provider
- func (p *Provider) Accepts(trust provider.TrustClass) error
- func (p *Provider) Destroy(ctx context.Context, id string) (provider.Teardown, error)
- func (p *Provider) Find(ctx context.Context, name string) (*Instance, bool, error)
- func (p *Provider) Kind() config.ProviderKind
- func (p *Provider) Launch(ctx context.Context, spec provider.Spec) (*provider.Instance, error)
- func (p *Provider) List(ctx context.Context) ([]*Instance, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Instance ¶
Instance is provider.Instance, aliased so this file does not repeat the package name on every line.
type Option ¶
type Option func(*Provider)
Option configures a Provider.
func WithBinary ¶
WithBinary sets the container CLI to invoke, e.g. "podman".
func WithLogger ¶
WithLogger sets the logger. The default is slog.Default().
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider launches containers through the docker CLI.
The CLI rather than the Docker SDK on purpose: this backend is a convenience, and billet ships as one static binary. Pulling in a large client library for a trial-only path is a poor trade, and the CLI is the interface an operator can reproduce by hand when something goes wrong.
func New ¶
New builds a docker provider. owner names this billet deployment and is written onto every container it starts.
func (*Provider) Accepts ¶
func (p *Provider) Accepts(trust provider.TrustClass) error
Accepts refuses anything that is not established as trusted.
A container shares the host kernel, so this backend is for trials and development rather than for code billet cannot vouch for. UNKNOWN is refused alongside untrusted: a caller who has not classified a job has not established it is safe to run here, and treating the zero value as probably-fine is how a refusal gets bypassed by omission rather than by decision.
func (*Provider) Destroy ¶
Destroy removes a container, whether or not it is still running.
Idempotent: an id that is already gone is success. Teardown runs on paths that have already failed once, and erroring there turns recoverable state into stuck state.
CONFIRMING, which is a promise most backends cannot make and this one can: `docker rm --force` kills the container and removes it before it returns, so by the time this reports success there is nothing left running. EC2 cannot say the same, which is why the return distinguishes them at all — and why the confirmation here is worth stating rather than left to be assumed by a caller that has no way to check.
func (*Provider) Find ¶
Find reports the container with that name, and whether there was one.
Filtered by billet's own label as well as the name, so a container somebody else happened to name the same way is not adopted — and adoption is the dangerous direction here, because the caller may go on to destroy it.
The name filter is a SUBSTRING match in docker, not an exact one, so the results are compared exactly afterwards. Without that, a lookup for `billet-abc` would happily return `billet-abcdef`.
func (*Provider) Kind ¶
func (p *Provider) Kind() config.ProviderKind
Kind reports the backend this is.
Source Files