Documentation
¶
Overview ¶
Package gvisor is the gVisor backend: every fiber is its own runsc sandbox, restored from a checkpoint of the warm template sandbox, so a fiber has a sandbox kernel between it and the host and the tier is FIBER_SNAPSHOT. It needs no KVM (the systrap platform), which is why it is the first snapshot backend.
How it maps onto the seam (see hack/dev/gvisor-check.sh for the probes these choices rest on):
- Warm: `runsc run` the template rootfs with the workload as init. The workload initialises, opens /proc/gvisor/checkpoint, drops a ready marker on the bind-mounted run directory and blocks reading the file; the backend then takes the template image with `runsc checkpoint --leave-running`. That blocking read is gVisor's sync point: it is where every restored sandbox resumes, and it answers "restore" there (and "resume" in the original). The read answers for the first checkpoint after its open, which is why the open comes before the marker.
- Clone: `runsc restore` the template image into a new sandbox whose spec carries a one-shot token. The workload claims it on the pool socket at /fiberd/channel and gets its fence, endpoint, payload, session and a seed. It reseeds, serves its endpoint and acks. A template that never dials gets its identity in the spec environment instead.
- Pool: the same restore, with the identity held back until Bind.
- Park: SIGUSR1 makes the workload close its endpoint (a listening host socket cannot be checkpointed), then `runsc checkpoint`, which ends the sandbox; the images are written with O_DIRECT so they are not charged to the fiber's leaf.
- Resume: `runsc restore` the park image under a new fence and endpoint, handed over on the warm instance's channel like a clone's, so a resume needs the instance; the workload's blocking read returns "restore" and it re-binds.
No delta codec: a park is gVisor's full state file (the memory image is sparse and can skip committed zero pages). Every sandbox pays for the template's pages itself, since nothing is shared copy-on-write between sandboxes; that footprint is reported as the fiber overhead so the W budget still means the working set the fiber dirtied.
Index ¶
- func New(o Options) backend.Backend
- type Backend
- func (b *Backend) Bind(ctx context.Context, pooledID string, sp backend.FiberSpec) (backend.Fiber, error)
- func (b *Backend) Clone(ctx context.Context, warmID string, sp backend.FiberSpec) (backend.Fiber, error)
- func (b *Backend) Close()
- func (b *Backend) DefaultDeadlines(warmID string) (create, resume time.Duration)
- func (b *Backend) Discard(pooledID string)
- func (b *Backend) EndpointSchemes() []string
- func (b *Backend) Exits() <-chan backend.Exit
- func (b *Backend) FiberOverheadBytes() uint64
- func (b *Backend) IsolatesTenants() bool
- func (b *Backend) Kill(fiberID string) error
- func (b *Backend) Name() string
- func (b *Backend) Park(ctx context.Context, fiberID string, sp backend.ParkSpec) error
- func (b *Backend) Platform() artifact.Platform
- func (b *Backend) Pool(ctx context.Context, warmID string, sp backend.PoolSpec) (backend.Pooled, error)
- func (b *Backend) ProbeErr() error
- func (b *Backend) Resume(ctx context.Context, sp backend.ResumeSpec) (backend.Fiber, error)
- func (b *Backend) Tier() core.Tier
- func (b *Backend) Unwarm(id string)
- func (b *Backend) WCounter() string
- func (b *Backend) Warm(ctx context.Context, sp backend.WarmSpec) (backend.Warm, error)
- type Options
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Backend ¶
type Backend struct {
// contains filtered or unexported fields
}
Backend implements backend.Backend, Platformer, DeadlineAdvisor, Overheader and Prober.
func (*Backend) Bind ¶
func (b *Backend) Bind(ctx context.Context, pooledID string, sp backend.FiberSpec) (backend.Fiber, error)
Bind hands a pooled sandbox the fiber's identity and waits for it to serve. The sandbox keeps its pooled id until then, so a failed hand-out never reports an end under a fence.
func (*Backend) Clone ¶
func (b *Backend) Clone(ctx context.Context, warmID string, sp backend.FiberSpec) (backend.Fiber, error)
Clone restores the template image as a new sandbox.
func (*Backend) Close ¶
func (b *Backend) Close()
Close refuses further warms, ends those in flight, kills every sandbox, pooled ones included, waits (bounded) for their reapers, so the state directory can go once it returns, and unmounts the templates tmpfs New mounted.
func (*Backend) DefaultDeadlines ¶
DefaultDeadlines sizes the deadlines of a clone or resume without one of its own from what the footprint probe measured for the warm instance. They are the floors, raised to deadlineFactor times the probe's restore and capped at deadlineCap. An instance whose probe measured nothing, or one this backend does not have, gets the floors.
func (*Backend) EndpointSchemes ¶
EndpointSchemes: unix only. The sandbox has no network (--network=none), so a tcp endpoint policy is served by the host's relay in front of the unix socket, and the sandbox stays network-free.
func (*Backend) FiberOverheadBytes ¶
FiberOverheadBytes is 0, so the host measures the warm template sandbox's resident size. One restored sandbox costs the Sentry plus the template's pages.
func (*Backend) IsolatesTenants ¶
IsolatesTenants is true because a fiber's syscalls are served by its sandbox's Sentry, not by the host kernel.
func (*Backend) Park ¶
Park asks the workload to close its endpoint, then checkpoints. The wait for the endpoint to go is the spec's deadline, the grant's resume deadline, or without one what this backend advises for the grant's warm instance (DefaultDeadlines).
func (*Backend) Platform ¶
Platform: a gVisor image depends on the runsc release and the rootfs, not on the host kernel or libc.
func (*Backend) Pool ¶
func (b *Backend) Pool(ctx context.Context, warmID string, sp backend.PoolSpec) (backend.Pooled, error)
Pool restores a sandbox with no identity, which waits for Bind. A failed Pool leaves no sandbox, and one it restored reports its end under the pooled id.
func (*Backend) ProbeErr ¶
ProbeErr is why New found no tier: runsc does not answer, or the rootfs is not a directory.
type Options ¶
type Options struct {
// Runsc names the runsc binary (default "runsc").
Runsc string
// Rootfs is the directory every sandbox uses as its root filesystem;
// template commands are paths inside it. Required.
Rootfs string
// StateDir holds runsc's container state and the template images
// (default /var/lib/fiberd/gvisor). Park images are written elsewhere,
// into the host's delta store.
StateDir string
// TemplatesOnDisk keeps <StateDir>/templates on StateDir's own file
// system. By default New mounts a tmpfs there, so a template image,
// the warm template's memory at READY, never reaches a disk. The
// tmpfs costs RAM, about one image per warm grant, charged to the
// grant's zygote cgroup, since the warm sandbox writes it. A home
// with large templates and little memory keeps them on disk.
TemplatesOnDisk bool
// MaxRestores bounds the `runsc restore` processes that run at once
// (default, the CPUs this process may use). Restores are CPU-bound,
// so unbounded ones all finish together at the end of a burst.
MaxRestores int
}
Options configure the gVisor backend.
Source Files