placement

package
v0.0.0-...-1614f50 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: AGPL-3.0 Imports: 27 Imported by: 0

Documentation

Overview

Package placement is the one interface through which a cloud service runs a workload — a container on the engine, or a Firecracker microVM on a node agent — chosen per service in the simulator's own configuration and never by anything a workload or a cloud API client sees.

Index

Constants

View Source
const ForwardedLabel = "sockerless-sim-forwarded-by"

ForwardedLabel marks a workload placed behind a forwarder or holder that owns its network namespace; its value is that container's ID, the container the engine lists at the workload's address. A member placed beside the workload joins the same forwarder and carries no such label: the forwarder goes with the workload alone.

Variables

View Source
var ErrBindMounts = errors.New("a microVM workload's bind names nothing a guest can mount")

The backend wraps ErrBindMounts for a workload whose bind it cannot serve to a guest: one that names no source or target, or a host path that is not there. It serves a host directory or file as a file share the guest mounts and an engine volume from a share container, and refuses the rest rather than run the workload without them.

View Source
var ErrNoBackend = errors.New("no backend of that kind is registered")

For wraps ErrNoBackend when the configuration puts a service onto a backend the simulator was not given.

View Source
var ErrNoIngressFilter = errors.New("the backend does not filter what the workload receives")

A handle whose backend cannot filter what the workload receives returns ErrNoIngressFilter.

View Source
var ErrNoNetwork = errors.New("a microVM workload needs a network the agent joined and an address on it")

The backend returns ErrNoNetwork for a workload that names no engine network or no address: a guest has no engine-assigned address to fall back on.

View Source
var ErrNoRouteControl = errors.New("the backend does not route the workload")

A backend that cannot choose where a workload's default route goes returns ErrNoRouteControl: a member's route is its owner's.

View Source
var ErrOwnNetwork = errors.New("a member names its own network; it joins the owner's")

PlaceMember wraps ErrOwnNetwork when a member names a network, aliases or hosts of its own: it joins the owner's namespace and takes those from it.

Functions

func ContainerAddress

func ContainerAddress(ctx context.Context, containerID string) (string, error)

ContainerAddress is a container's IPv4 address on its network, following a member container to the owner whose namespace it joined.

func ContainerConsole

func ContainerConsole(ctx context.Context, containerID string) (string, error)

ContainerConsole is everything a container wrote, which the engine keeps across its stops and starts.

Types

type Backend

type Backend interface {
	Kind() Kind
	// Place starts the workload and streams its output into sink.
	Place(ctx context.Context, w Workload, sink sim.LogSink) (Handle, error)
	// PlaceMember starts w in the network namespace of the placed workload
	// owner, so the two reach each other on localhost: a sidecar's shape. On
	// the container backend the member is a container joined to the owner's
	// namespace; on the microVM backend it is a process tree the owner's
	// guest runs from the member's own image. The member's lifetime is its
	// own: it outlives an owner that exits until it is cancelled or exits.
	PlaceMember(ctx context.Context, owner string, w Workload, sink sim.LogSink) (Handle, error)
	// Adopt takes over a workload a previous simulator process placed, found
	// by its backend ID, and streams its output into sink.
	Adopt(ctx context.Context, id string, w Workload, sink sim.LogSink) (Handle, error)
	// Restart boots a kept workload (one placed with KeepOnExit that has
	// exited or was cancelled) again on the same filesystem.
	Restart(ctx context.Context, id string, w Workload, sink sim.LogSink) (Handle, error)
	// Remove discards a kept workload.
	Remove(ctx context.Context, id string) error
	// Console is everything the workload wrote since it was placed, across
	// the restarts of a kept one: the machine's console as a cloud reads it.
	Console(ctx context.Context, id string) (string, error)
	// Capture stores the workload's filesystem as an engine image under
	// reference: the disk image a cloud makes of a machine, which another
	// workload boots from.
	Capture(ctx context.Context, id, reference string) error
	// Find lists the workloads of this simulator's persistent identity that
	// carry every label, running or kept, for a restarted process to adopt.
	Find(ctx context.Context, labels map[string]string) ([]Existing, error)
}

Backend places workloads.

type ContainerBackend

type ContainerBackend struct{}

ContainerBackend places workloads as containers on the engine the simulator started against.

func (ContainerBackend) Adopt

func (ContainerBackend) Adopt(ctx context.Context, id string, w Workload, sink sim.LogSink) (Handle, error)

Adopt takes over a container, and the forwarder it was placed with.

func (ContainerBackend) Capture

func (ContainerBackend) Capture(ctx context.Context, id, reference string) error

func (ContainerBackend) Console

func (ContainerBackend) Console(ctx context.Context, id string) (string, error)

func (ContainerBackend) Find

func (ContainerBackend) Find(_ context.Context, labels map[string]string) ([]Existing, error)

func (ContainerBackend) Kind

func (ContainerBackend) Kind() Kind

func (ContainerBackend) Place

func (b ContainerBackend) Place(ctx context.Context, w Workload, sink sim.LogSink) (Handle, error)

func (ContainerBackend) PlaceForwarded

func (b ContainerBackend) PlaceForwarded(ctx context.Context, w Workload, forwards []Forward, sink sim.LogSink) (Handle, error)

PlaceForwarded places a forwarder that owns the workload's network namespace, with every network setting w names, and starts w joined to it once the forwards listen. A workload that keeps its filesystem across stops or names a network mode of its own has no namespace a forwarder can own.

func (ContainerBackend) PlaceMember

func (ContainerBackend) PlaceMember(ctx context.Context, owner string, w Workload, sink sim.LogSink) (Handle, error)

PlaceMember starts w as a container in the owner container's network namespace: the namespace of the forwarder the owner joined, when it was placed with forwards.

func (ContainerBackend) Remove

func (ContainerBackend) Remove(ctx context.Context, id string) error

func (ContainerBackend) Restart

func (ContainerBackend) Restart(ctx context.Context, id string, w Workload, sink sim.LogSink) (Handle, error)

type ExecResult

type ExecResult struct {
	Stdout   string
	Stderr   string
	ExitCode int
}

ExecResult is what a command run inside a workload produced.

func ExecInContainer

func ExecInContainer(ctx context.Context, containerID string, command []string) (ExecResult, error)

ExecInContainer runs a command in a running container through the engine and returns what it wrote and how it exited.

type Existing

type Existing struct {
	ID      string
	Running bool
	Labels  map[string]string
}

Existing is a workload a backend holds from an earlier simulator process: running, or exited with its filesystem kept. A member is listed beside its owner under its own ID.

type Forward

type Forward = sidecar.Forward

Forward is a TCP listener on a workload's own loopback that relays each connection to an endpoint on the workload's network.

type Forwarding

type Forwarding interface {
	// PlaceForwarded places w as Place does, with forwards listening in its
	// network namespace; the forwards go when the workload exits.
	PlaceForwarded(ctx context.Context, w Workload, forwards []Forward, sink sim.LogSink) (Handle, error)
}

Forwarding is a backend that serves forwards on a workload's loopback from before the workload's first process runs: an endpoint of the workload's network that a client accepts over plain HTTP only on a loopback address (the AWS SDKs' container credential provider) reaches the workload there.

type Handle

type Handle interface {
	// ID identifies the workload on its backend: the container ID, or the
	// guest ID the node agent assigned.
	ID() string
	// Kind is the backend the workload runs on.
	Kind() Kind
	// Wait blocks until the workload exits and returns how it exited.
	Wait() sim.ProcessResult
	// Exited closes once the workload has exited.
	Exited() <-chan struct{}
	// StartedAt is the moment the backend asked for the workload's process
	// to start, on this process's clock: the process starts after it. A
	// workload adopted from an earlier simulator process reports the start
	// its backend recorded.
	StartedAt() time.Time
	// Cancel stops the workload, within the grace its Workload named, and
	// Wait reports the cancellation rather than an exit of the workload's
	// own.
	Cancel()
	// Stop sends the workload the stop signal and, once the grace its
	// Workload named has passed, kills it; Wait then reports how the
	// workload itself exited, as a cloud that stops an instance reads the
	// exit of its process.
	Stop()
	// Exec runs a command inside the workload and returns its output and exit
	// code.
	Exec(ctx context.Context, command []string) (ExecResult, error)
	// PublishedPort returns the 127.0.0.1 host port the backend bound for a
	// port the Workload listed in PublishPorts.
	PublishedPort(ctx context.Context, port int) (int, error)
	// Address is the workload's IPv4 address on its network, a member's
	// being its owner's.
	Address(ctx context.Context) (string, error)
	// SetIngress replaces what the workload may receive, as Workload.Ingress
	// spells it, on a backend that filters; the container backend and a
	// member, which receives through its owner, return ErrNoIngressFilter.
	SetIngress(ctx context.Context, stages [][]netrules.PacketRule) error
	// SetGateway replaces where the workload's default route goes, in the
	// terms of Workload.Gateway, or returns ErrNoRouteControl.
	SetGateway(ctx context.Context, gateway string) error
}

Handle is a placed workload.

type Kind

type Kind string

Kind names a backend.

const (
	// Container runs the workload as a container on the engine.
	Container Kind = "container"
	// MicroVM runs the workload as a Firecracker guest on a node agent.
	MicroVM Kind = "microvm"
)

type MicroVMBackend

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

MicroVMBackend places workloads as Firecracker guests on a node agent. A workload's image becomes the guest's root filesystem, its command the guest's first process, and its network and address its place on the engine network the agent joined for it.

func NewMicroVMBackend

func NewMicroVMBackend(agent *nodeagent.Agent, macPrefix string) *MicroVMBackend

func (*MicroVMBackend) Adopt

func (b *MicroVMBackend) Adopt(ctx context.Context, id string, w Workload, sink sim.LogSink) (Handle, error)

Adopt takes over a guest a previous simulator process placed on an agent this process adopted, running or kept after its exit, or a member of one by its owner/name ID.

func (*MicroVMBackend) Agent

func (b *MicroVMBackend) Agent() *nodeagent.Agent

func (*MicroVMBackend) Capture

func (b *MicroVMBackend) Capture(ctx context.Context, id, reference string) error

Capture imports the guest's root filesystem, as the agent exports it, as an engine image under reference.

func (*MicroVMBackend) Console

func (b *MicroVMBackend) Console(ctx context.Context, id string) (string, error)

Console is what the guest's first process wrote across its boots, which the agent keeps while the guest exists.

func (*MicroVMBackend) Find

func (b *MicroVMBackend) Find(ctx context.Context, labels map[string]string) ([]Existing, error)

Find lists the agent's guests carrying every label and this simulator's persistent identity.

func (*MicroVMBackend) Join

func (b *MicroVMBackend) Join(ctx context.Context, network string, address netip.Addr) error

Join makes the agent a member of an engine network at the address the cloud leased for it, before the first workload lands there.

func (*MicroVMBackend) Kind

func (*MicroVMBackend) Kind() Kind

func (*MicroVMBackend) Leave

func (b *MicroVMBackend) Leave(ctx context.Context, network string) error

Leave takes the agent off an engine network the cloud is removing, once nothing of the cloud's is left on it.

func (*MicroVMBackend) Place

func (b *MicroVMBackend) Place(ctx context.Context, w Workload, sink sim.LogSink) (Handle, error)

func (*MicroVMBackend) PlaceMember

func (b *MicroVMBackend) PlaceMember(ctx context.Context, owner string, w Workload, sink sim.LogSink) (Handle, error)

PlaceMember runs w as a member of the owner's guest: its image's filesystem becomes a root filesystem of its own on one of the guest's disk slots, and its command a process tree beside the guest's first process, on the guest's network.

func (*MicroVMBackend) Remove

func (b *MicroVMBackend) Remove(ctx context.Context, id string) error

Remove discards a kept guest, with the share container of its volumes.

func (*MicroVMBackend) Restart

func (b *MicroVMBackend) Restart(ctx context.Context, id string, w Workload, sink sim.LogSink) (Handle, error)

Restart boots a kept guest again on its root filesystem.

type Service

type Service struct {
	Name      string
	Qualifier string
}

Service names what asks for placement: a cloud service, and the attribute its cloud distinguishes placements by when the service has one (an Amazon ECS launch type, an Amazon RDS instance class family).

func (Service) String

func (s Service) String() string

type Table

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

Table maps services to backends from the simulator's configuration: a comma-separated list of `service[:qualifier]=container|microvm`, every service unnamed running on containers. A qualifier entry wins over the service's own.

func ParseTable

func ParseTable(spec string) (*Table, error)

ParseTable reads the configuration; an unknown backend name or a malformed entry is an error naming it.

func (*Table) For

func (t *Table) For(s Service) (Backend, error)

For is the backend the service's workloads run on.

func (*Table) KindFor

func (t *Table) KindFor(s Service) Kind

KindFor is the backend kind configured for the service.

func (*Table) MicroVMServices

func (t *Table) MicroVMServices() []string

MicroVMServices lists the services configured onto microVMs.

func (*Table) Register

func (t *Table) Register(b Backend)

Register makes a backend available to the table.

func (*Table) Services

func (t *Table) Services() []string

Services lists every service the configuration names, for a startup log.

type Workload

type Workload = sim.ContainerConfig

Workload is what a service wants to run, in the terms every backend understands. The container backend runs it as it is; the microVM backend builds a guest root filesystem from Image and runs Command and Args as the guest's first process under Env, on Network at IPv4Address. A member placed beside an owner with PlaceMember names no network of its own: it shares the owner's.

Jump to

Keyboard shortcuts

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