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
- Variables
- func ContainerAddress(ctx context.Context, containerID string) (string, error)
- func ContainerConsole(ctx context.Context, containerID string) (string, error)
- type Backend
- type ContainerBackend
- func (ContainerBackend) Adopt(ctx context.Context, id string, w Workload, sink sim.LogSink) (Handle, error)
- func (ContainerBackend) Capture(ctx context.Context, id, reference string) error
- func (ContainerBackend) Console(ctx context.Context, id string) (string, error)
- func (ContainerBackend) Find(_ context.Context, labels map[string]string) ([]Existing, error)
- func (ContainerBackend) Kind() Kind
- func (b ContainerBackend) Place(ctx context.Context, w Workload, sink sim.LogSink) (Handle, error)
- func (b ContainerBackend) PlaceForwarded(ctx context.Context, w Workload, forwards []Forward, sink sim.LogSink) (Handle, error)
- func (ContainerBackend) PlaceMember(ctx context.Context, owner string, w Workload, sink sim.LogSink) (Handle, error)
- func (ContainerBackend) Remove(ctx context.Context, id string) error
- func (ContainerBackend) Restart(ctx context.Context, id string, w Workload, sink sim.LogSink) (Handle, error)
- type ExecResult
- type Existing
- type Forward
- type Forwarding
- type Handle
- type Kind
- type MicroVMBackend
- func (b *MicroVMBackend) Adopt(ctx context.Context, id string, w Workload, sink sim.LogSink) (Handle, error)
- func (b *MicroVMBackend) Agent() *nodeagent.Agent
- func (b *MicroVMBackend) Capture(ctx context.Context, id, reference string) error
- func (b *MicroVMBackend) Console(ctx context.Context, id string) (string, error)
- func (b *MicroVMBackend) Find(ctx context.Context, labels map[string]string) ([]Existing, error)
- func (b *MicroVMBackend) Join(ctx context.Context, network string, address netip.Addr) error
- func (*MicroVMBackend) Kind() Kind
- func (b *MicroVMBackend) Leave(ctx context.Context, network string) error
- func (b *MicroVMBackend) Place(ctx context.Context, w Workload, sink sim.LogSink) (Handle, error)
- func (b *MicroVMBackend) PlaceMember(ctx context.Context, owner string, w Workload, sink sim.LogSink) (Handle, error)
- func (b *MicroVMBackend) Remove(ctx context.Context, id string) error
- func (b *MicroVMBackend) Restart(ctx context.Context, id string, w Workload, sink sim.LogSink) (Handle, error)
- type Service
- type Table
- type Workload
Constants ¶
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 ¶
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.
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.
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.
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.
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.
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 ¶
ContainerAddress is a container's IPv4 address on its network, following a member container to the owner whose namespace it joined.
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) Kind ¶
func (ContainerBackend) Kind() Kind
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.
type ExecResult ¶
ExecResult is what a command run inside a workload produced.
func ExecInContainer ¶
ExecInContainer runs a command in a running container through the engine and returns what it wrote and how it exited.
type Existing ¶
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 ¶
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 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 ¶
Console is what the guest's first process wrote across its boots, which the agent keeps while the guest exists.
func (*MicroVMBackend) Find ¶
Find lists the agent's guests carrying every label and this simulator's persistent identity.
func (*MicroVMBackend) Join ¶
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) 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.
type Service ¶
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).
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 ¶
ParseTable reads the configuration; an unknown backend name or a malformed entry is an error naming it.
func (*Table) MicroVMServices ¶
MicroVMServices lists the services configured onto microVMs.
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.