dicer

package module
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Oct 11, 2026 License: MIT Imports: 28 Imported by: 0

README

Dicer

OpenSSF Scorecard test lint security Go Reference

Run virtual machines from container images, on one host.

Dicer pulls an OCI image, converts it to a read-only root filesystem and boots it as a VM under Cloud Hypervisor or Firecracker, with a writable overlay on top.

[!WARNING] Dicer has not reached version 1.0, so nothing in it is stable yet. Until then, a minor release can break the API, the Go package, the command line, its JSON output, the configuration file or the daemon's saved state. Read the release notes before you upgrade. RELEASES.md explains how versions work.

Requirements

  • Linux with KVM (/dev/kvm)
  • erofs-utils (mkfs.erofs) and e2fsprogs (mke2fs)
  • IPv4 forwarding enabled

Install

curl -fsSL https://raw.githubusercontent.com/konradasb/dicer/main/scripts/install.sh | bash

This builds dicer and dicerd from source and installs dicerd as a systemd service.

Quickstart

Run nginx in a virtual machine of its own, and look around:

$ dicer run -d --name web -p 8080:80 nginx:1.27
$ dicer ps
$ dicer exec web sh
$ dicer logs -f web
$ dicer stop web
$ dicer rm web

The instance joins the default network and boots the default kernel, Dicer's kernel. The daemon sets up both itself, and an instance uses them unless it names others.

See dicer --help for every command.

Go client

The github.com/konradasb/dicer package does from a program what the command line does:

c, err := dicer.NewClient() // the local daemon
if err != nil {
	return err
}
defer c.Close()

_, err = c.Instances.Create(ctx, dicer.InstanceSpec{
	Name:        "web",
	ImageRef:    "nginx:1.27",
	VCPUs:       1,
	MemoryBytes: 512 << 20,
	DiskBytes:   10 << 30,
}, dicer.CreateOptions{Start: true})
if err != nil {
	return err
}

out, err := c.Instances.Command("web", "nginx", "-v").Output(ctx)

For more examples, and for calling the API from other languages, see Using the API.

Configuration

dicerd reads /etc/dicerd/config.yaml. The file is optional: every key has a default, and unknown keys are rejected. The configuration reference shows every key with its default, and dicerd validate checks a file before the daemon uses it.

Licence

MIT. See LICENSE.

Documentation

Overview

Package dicer is the Go client of a Dicer daemon.

A Client connects to the local daemon's socket by default, or to a daemon's TCP listener, with TLS. Its calls are grouped by the resource they act on: 

c, err := dicer.NewClient()
if err != nil {
	return err
}
defer c.Close()

instance, err := c.Instances.Create(ctx, dicer.InstanceSpec{
	Name:        "web",
	ImageRef:    "nginx:1.27",
	VCPUs:       1,
	MemoryBytes: 512 << 20,
	DiskBytes:   10 << 30,
}, dicer.CreateOptions{Start: true})

A command runs in an instance as an exec.Cmd runs on this machine: 

out, err := c.Instances.Command("web", "cat", "/etc/os-release").Output(ctx)

A daemon on another machine is named by the address of its TCP listener, and reached with a token that `dicer token create` makes on its host: 

c, err := dicer.NewClient(dicer.WithAddress("host:7443"), dicer.WithToken(token))

The socket is protected by its file permissions. Over TCP, the connection uses TLS, and the daemon is checked by the fingerprint the token carries.

A failed call returns an error that matches the kind of failure it was, such as ErrNotFound, and whose message is the daemon's: 

if errors.Is(err, dicer.ErrNotFound) {
	...
}

The API itself is the gRPC service in proto/dicerd/v1, from which clients in other languages are generated.

Index

Constants

View Source 
const (
	// DefaultKeepaliveInterval is how long a connection may carry nothing
	// before the client pings the daemon.
	DefaultKeepaliveInterval = 30 * time.Second

	// DefaultKeepaliveTimeout is how long the client waits for the answer
	// to a ping before giving the connection up.
	DefaultKeepaliveTimeout = 10 * time.Second
)

The keepalive a client uses unless WithKeepalive says otherwise.

View Source 
const DefaultAddress = "unix://" + defaults.Socket

DefaultAddress is where a daemon serves its API unless configured otherwise: its Unix socket, as a gRPC target.

View Source 
const UnknownExitCode = 125

UnknownExitCode is the status Instances.Wait returns for a guest that ended without reporting one, as docker wait does.

Variables

View Source 
var (
	// ErrNotFound means the resource named does not exist.
	ErrNotFound = errors.New("not found")

	// ErrAlreadyExists means a resource with that name exists already.
	ErrAlreadyExists = errors.New("already exists")

	// ErrInvalidArgument means the request is malformed, whatever the host's
	// state.
	ErrInvalidArgument = errors.New("invalid argument")

	// ErrFailedPrecondition means the resource is in the wrong state for the
	// call, such as deleting a running instance.
	ErrFailedPrecondition = errors.New("failed precondition")

	// ErrResourceExhausted means the host has too little left: CPU or memory
	// for an instance, or addresses on a network.
	ErrResourceExhausted = errors.New("resource exhausted")

	// ErrUnavailable means something the call needs cannot be reached: the
	// daemon, a registry or a guest's agent. Trying again may work.
	ErrUnavailable = errors.New("unavailable")

	// ErrPermissionDenied means the call was refused: the token's scopes do
	// not allow it, or the guest refused, such as a file it protects.
	ErrPermissionDenied = errors.New("permission denied")

	// ErrUnimplemented means the daemon, or an instance's guest agent, is too
	// old for the call.
	ErrUnimplemented = errors.New("unimplemented")

	// ErrUnauthenticated means the daemon's TCP listener refused the call's
	// token: it was deleted or rotated, or was never this daemon's.
	ErrUnauthenticated = errors.New("unauthenticated")
)

The kinds of failure a call can end with. Match them with errors.Is: 

if errors.Is(err, dicer.ErrNotFound) {
	...
}

The error's message is the daemon's, written for a person to read.

Functions

This section is empty.

Types

type Architecture added in v0.4.0 

type Architecture string

Architecture is the CPU architecture a kernel is built for. 

const (
	ArchitectureX86_64  Architecture = "x86_64"
	ArchitectureAArch64 Architecture = "aarch64"
)

The architectures.

type CheckHostOptions added in v0.4.0 

type CheckHostOptions struct {
	// TestInstance makes CheckHost boot a test instance after it has checked
	// the host. This creates and deletes an instance, and pulls the
	// instance's image if the host does not have it. Over the TCP listener,
	// it needs a token with instances:write.
	TestInstance bool

	// TestInstanceImage is the test instance's image, which must have sh and
	// wget, as busybox does. If it is empty, docker.io/library/busybox:1.37
	// is used.
	TestInstanceImage string

	// TestInstanceHypervisor is the hypervisor to boot the test instance on.
	// If it is empty, Cloud Hypervisor is used.
	TestInstanceHypervisor HypervisorType

	// TestInstanceHypervisorVersion is the version of the hypervisor to boot
	// the test instance on. If it is empty, the hypervisor's default
	// version, which HostInfo lists first, is used.
	TestInstanceHypervisorVersion string

	// TestInstanceTimeout is how long the test instance may take to run its
	// command. If it is zero, the timeout is 2 minutes.
	TestInstanceTimeout time.Duration

	// KeepFailedTestInstance keeps a failed test instance for inspection,
	// instead of deleting it.
	KeepFailedTestInstance bool
}

CheckHostOptions control whether CheckHost boots a test instance, and how.

type Client 

type Client struct {
	// Instances are the calls about instances.
	Instances *Instances

	// Snapshots are the calls about snapshots.
	Snapshots *Snapshots

	// Networks are the calls about networks.
	Networks *Networks

	// Volumes are the calls about volumes.
	Volumes *Volumes

	// Images are the calls about images.
	Images *Images

	// Kernels are the calls about kernels.
	Kernels *Kernels

	// Tokens are the calls about tokens.
	Tokens *Tokens
	// contains filtered or unexported fields
}

Client is a connection to a Dicer daemon. Its calls are grouped by the resource they act on, as in c.Instances.Get(ctx, "web"), and those about the host as a whole are methods of its own, such as c.Events.

A Client is safe for concurrent use and should be closed when done.

func NewClient 

func NewClient(opts ...Option) (*Client, error)

NewClient connects to a daemon, by default the local one: 

c, err := dicer.NewClient()

A daemon's TCP listener, with a token: 

c, err := dicer.NewClient(dicer.WithAddress("host:7443"), dicer.WithToken(token))

Connecting is lazy: an unreachable daemon is reported by the first call. A local socket that is not there, a TCP address without a token, and a token that is not one are reported here.

func (*Client) CheckHost added in v0.4.0 

func (c *Client) CheckHost(
	ctx context.Context, opts CheckHostOptions, onResult func(HostCheckResult),
) ([]HostCheckResult, error)

CheckHost checks that the host can run instances and that they can be reached: KVM, IPv4 forwarding, the firewall, the tools the daemon needs, the uplink and the free disk space. These checks change nothing. With opts.TestInstance, it then boots a small test instance, checks that the instance can run a command and reach the internet, and deletes it.

If onResult is not nil, it is called with each result as soon as the result is known. CheckHost returns every result: the host's results first, then the test instance's, then whether the test instance reached the internet. If the call fails, it returns no results.

func (*Client) Close 

func (c *Client) Close() error

Close closes the connection to the daemon. Calls in flight are cancelled.

func (*Client) Events added in v0.4.0 

func (c *Client) Events(ctx context.Context, opts EventOptions) (*EventStream, error)

Events streams what has happened to the resources on the host: the history the daemon keeps, oldest first, then, if opts.Follow is set, each new event as it happens, none missed between the two. A follower that does not keep up is disconnected with ErrResourceExhausted rather than slowing the host. The stream must be closed when done.

func (*Client) HostInfo added in v0.4.0 

func (c *Client) HostInfo(ctx context.Context) (HostInfo, error)

HostInfo returns what the daemon is.

func (*Client) Resources added in v0.4.0 

func (c *Client) Resources(ctx context.Context) (Resources, error)

Resources returns how much of the host instances may be given, and how much they hold.

type Cmd added in v0.4.0 

type Cmd struct {
	// Instance is the instance to run the command in, by name or ID.
	Instance string

	// Args are the command and its arguments. Empty runs /bin/sh.
	Args []string

	// Env is added to the command's environment.
	Env map[string]string

	// Dir is the working directory inside the guest. Empty leaves the
	// guest's default.
	Dir string

	// User is who the command runs as: user, uid, user:group or uid:gid, as
	// the guest's /etc/passwd and /etc/group define them. The command gets
	// the user's groups, and its home directory as HOME unless Env sets it.
	// Empty is the user the workload runs as, which is root in the systemd
	// init mode. An unknown user fails with ErrInvalidArgument. A guest
	// whose agent is too old to switch users fails with
	// ErrFailedPrecondition until the instance is restarted.
	User string

	// Timeout kills the command if it runs for longer, and it then exits
	// with status 124. It is counted in whole seconds, rounded up. Zero is
	// no limit.
	Timeout time.Duration

	// TTY runs the command on a pseudo-terminal. Its standard error then
	// arrives on Stdout.
	TTY bool

	// Rows is the pseudo-terminal's height. Zero leaves the guest's default.
	Rows int

	// Columns is the pseudo-terminal's width. Zero leaves the guest's
	// default.
	Columns int

	// Stdin is the command's standard input. Nil gives it none: it reads
	// end of file at once. The end of Stdin, or an error reading it, ends
	// the command's input. Wait does not wait for Stdin to be read: a read
	// that blocks after the command has exited is left to finish on its
	// own.
	Stdin io.Reader

	// Stdout receives the command's standard output. Nil discards it.
	Stdout io.Writer

	// Stderr receives the command's standard error. Nil discards it, except
	// that Output collects it into the *ExitError it returns.
	Stderr io.Writer
	// contains filtered or unexported fields
}

Cmd is a command to run in an instance, as an exec.Cmd is one to run on this machine. Make one with Instances.Command, set its fields, and call Run, Output or Start. A Cmd cannot be reused once started.

The command needs the instance to be running. If its guest is still booting, the command waits up to 30 seconds for its agent to answer before failing with ErrUnavailable.

func (*Cmd) Output added in v0.4.0 

func (c *Cmd) Output(ctx context.Context) ([]byte, error)

Output runs the command and returns its standard output. Unless Stderr is set, the command's standard error is collected into the *ExitError returned for a command that did not exit 0.

func (*Cmd) Resize added in v0.4.0 

func (c *Cmd) Resize(rows, columns int) error

Resize tells a command on a pseudo-terminal that the terminal is now rows by columns in size.

func (*Cmd) Run added in v0.4.0 

func (c *Cmd) Run(ctx context.Context) error

Run starts the command and waits for it to exit. It returns nil if the command exited 0, an *ExitError if it exited otherwise, and the error the call failed with if it could not run the command to its end.

func (*Cmd) Start added in v0.4.0 

func (c *Cmd) Start(ctx context.Context) error

Start starts the command, without waiting for it. Wait waits for it to exit. Cancelling ctx kills the command.

func (*Cmd) Wait added in v0.4.0 

func (c *Cmd) Wait() error

Wait waits for a started command to exit, and returns what Run does.

type CreateOptions added in v0.4.0 

type CreateOptions struct {
	// Start boots the instance once it is defined, and Create returns once it
	// has booted, as Instances.Start does.
	Start bool

	// PullPolicy is when the image is pulled. Empty means
	// PullPolicyMissing.
	PullPolicy PullPolicy
}

CreateOptions are how Instances.Create creates an instance.

type DeleteOptions added in v0.4.0 

type DeleteOptions struct {
	// Force stops a running instance before deleting it, and deletes an
	// image even if an instance is defined to boot from it.
	Force bool
}

DeleteOptions are how a resource is deleted, by Instances.Delete and Images.Delete.

type DiskUsage added in v0.4.0 

type DiskUsage struct {
	// Path is the data directory.
	Path string `json:"path,omitzero"`

	// TotalBytes is the filesystem's size.
	TotalBytes int64 `json:"total_bytes,omitzero"`

	// FreeBytes is what can still be written.
	FreeBytes int64 `json:"free_bytes,omitzero"`

	// ProvisionedBytes is the sizes of every instance's overlay disk and
	// every volume, added up.
	ProvisionedBytes int64 `json:"provisioned_bytes,omitzero"`
}

DiskUsage is how full the filesystem holding the data directory is, and how much has been promised on it. Disks are sparse, so ProvisionedBytes may be far more than TotalBytes without anything being wrong, until the guests fill them.

type Event added in v0.4.0 

type Event struct {
	// Time is when it happened.
	Time time.Time `json:"time,omitzero"`

	// Kind is the kind of resource it happened to.
	Kind EventKind `json:"kind,omitzero"`

	// ID is the resource's ID, which tells apart resources that had the
	// same name at different times. It is empty for a resource known only
	// by its name, such as an image.
	ID string `json:"id,omitzero"`

	// Name is the resource's name.
	Name string `json:"name,omitzero"`

	// Action is what happened to the resource, such as EventActionStarted.
	Action EventAction `json:"action,omitzero"`

	// Message says what happened, in a line, for a person.
	Message string `json:"message,omitzero"`

	// Attributes say what happened, for a program: exit_code,
	// restart_count, digest.
	Attributes map[string]string `json:"attributes,omitzero"`
}

Event is one thing that happened to one resource on the host.

type EventAction added in v0.4.0 

type EventAction string

EventAction is what happened to the resource. 

const (
	// Any kind of resource.
	EventActionCreated EventAction = "created"
	EventActionUpdated EventAction = "updated"
	EventActionDeleted EventAction = "deleted"

	// An instance.
	EventActionStarted EventAction = "started"
	EventActionStopped EventAction = "stopped"
	EventActionPaused  EventAction = "paused"
	EventActionResumed EventAction = "resumed"

	// EventActionExited means the guest ended cleanly, of its own accord.
	EventActionExited EventAction = "exited"

	// EventActionDied means the guest ended in failure.
	EventActionDied EventAction = "died"

	// EventActionRestarting means the restart policy will start the
	// instance again.
	EventActionRestarting EventAction = "restarting"

	EventActionRenamed EventAction = "renamed"

	// EventActionHealthy and EventActionUnhealthy mean the health check
	// reached a verdict.
	EventActionHealthy   EventAction = "healthy"
	EventActionUnhealthy EventAction = "unhealthy"

	// EventActionSnapshotRestored means the instance was put back as a
	// snapshot of it holds it.
	EventActionSnapshotRestored EventAction = "snapshot_restored"

	// EventActionResized means a running instance was given other vCPUs or
	// memory.
	EventActionResized EventAction = "resized"

	// EventActionStandby means the instance was frozen to disk, and its
	// hypervisor ended.
	EventActionStandby EventAction = "standby"

	// An image.
	EventActionPulled EventAction = "pulled"

	// EventActionCollected means garbage collection removed the image.
	EventActionCollected EventAction = "collected"

	// EventActionImported means a kernel was imported, and is on the host.
	EventActionImported EventAction = "imported"
)

The event actions.

type EventBatch added in v0.4.0 

type EventBatch struct {
	// Events are the batch's events, oldest first.
	Events []Event `json:"events,omitzero"`

	// CaughtUp is set on the last batch of the history, which is sent even
	// if the history is empty: what follows, if the stream follows, is new.
	CaughtUp bool `json:"caught_up,omitzero"`
}

EventBatch is a batch of events, oldest first.

type EventKind added in v0.4.0 

type EventKind string

EventKind is the kind of resource an event is about. 

const (
	EventKindInstance EventKind = "instance"
	EventKindSnapshot EventKind = "snapshot"
	EventKindImage    EventKind = "image"
	EventKindNetwork  EventKind = "network"
	EventKindVolume   EventKind = "volume"
	EventKindKernel   EventKind = "kernel"
)

The event kinds.

type EventOptions added in v0.4.0 

type EventOptions struct {
	// Kind picks one kind of resource. Empty picks every kind.
	Kind EventKind

	// ID picks one resource, by its ID.
	ID string

	// Name picks one resource, by its name. An image's name may be given as
	// it is pulled: busybox:latest picks the events about
	// docker.io/library/busybox:latest.
	Name string

	// Since picks only the events at or after it.
	Since time.Time

	// Limit picks only the last this many events of the history. Zero
	// means all of it.
	Limit int

	// Follow keeps streaming new events after the history.
	Follow bool
}

EventOptions pick the events Client.Events streams: every one, unless narrowed.

type EventStream added in v0.4.0 

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

EventStream is a stream of events, read with Next.

func (*EventStream) Close added in v0.4.0 

func (s *EventStream) Close() error

Close ends the stream.

func (*EventStream) Next added in v0.4.0 

func (s *EventStream) Next() (EventBatch, error)

Next returns the next batch of events. It returns io.EOF once a stream that does not follow has sent the history, and the error the stream failed with otherwise, such as context.Canceled once it is closed.

type ExitError added in v0.4.0 

type ExitError struct {
	// Code is the command's exit status.
	Code int

	// Stderr is the command's standard error, if Output collected it.
	Stderr []byte
}

ExitError reports a command that exited with a status other than 0.

func (*ExitError) Error added in v0.4.0 

func (e *ExitError) Error() string

Error returns the command's exit status.

type ForkOptions added in v0.4.0 

type ForkOptions struct {
	// Name is the new instance's name. Empty means one made from the name
	// of the instance or snapshot forked, such as web-k3x9.
	Name string

	// NetworkName is the network the new instance joins. Empty means the
	// original's network.
	NetworkName string

	// StaticIP is the new instance's address on its network. Empty means one
	// is assigned.
	StaticIP string

	// Ports are the host ports the new instance publishes. The original's
	// are not copied: two instances cannot publish the same host port.
	Ports []PortMapping
}

ForkOptions are the identity a fork is given, by Instances.Fork and Snapshots.Fork.

type HTTPProbe added in v0.4.0 

type HTTPProbe struct {
	// Port is the guest port the GET is sent to.
	Port int `json:"port,omitzero"`

	// Path defaults to /.
	Path string `json:"path,omitzero"`
}

HTTPProbe checks health by asking for a path on the guest's loopback address, which is healthy if it answers 2xx or 3xx.

type Health added in v0.4.0 

type Health struct {
	// Status is whether the instance is healthy.
	Status HealthStatus `json:"status,omitzero"`

	// FailingStreak is how many probes in a row have failed.
	FailingStreak int `json:"failing_streak,omitzero"`

	// LastCheckTime is when the last probe ran.
	LastCheckTime time.Time `json:"last_check_time,omitzero"`

	// LastOutput is what the last probe said, truncated.
	LastOutput string `json:"last_output,omitzero"`

	// Check is the check being run: the instance's, or its image's, with
	// the defaults filled in.
	Check HealthCheck `json:"check,omitzero"`
}

Health is what an instance's health check has found.

type HealthCheck added in v0.4.0 

type HealthCheck struct {
	// Exec is a command run in the guest. The instance is healthy when it
	// exits 0. Exactly one of Exec, HTTP and TCP is set, unless the check is
	// Disabled.
	Exec []string `json:"exec,omitzero"`

	// HTTP is a probe that sends a GET to the guest's loopback address. The
	// instance is healthy when it answers with a 2xx or 3xx status.
	HTTP *HTTPProbe `json:"http,omitzero"`

	// TCP is a probe that connects to the guest's loopback address. The
	// instance is healthy when the connection opens.
	TCP *TCPProbe `json:"tcp,omitzero"`

	// Interval is the time between the end of one probe and the start of
	// the next.
	Interval time.Duration `json:"interval,omitzero"`

	// Timeout is how long a probe may take; one that overruns has failed.
	Timeout time.Duration `json:"timeout,omitzero"`

	// StartPeriod is how long after a start failures do not count.
	StartPeriod time.Duration `json:"start_period,omitzero"`

	// Retries is how many failures in a row make the instance unhealthy.
	Retries int `json:"retries,omitzero"`

	// Disabled switches health checking off, the image's check included.
	// Nothing else may be set with it.
	Disabled bool `json:"disabled,omitzero"`
}

HealthCheck is how an instance's health is checked: one probe, run inside the guest by its agent, and when to run it. Unset timings take the defaults: every 10s, a 5s timeout, no start period and 3 retries.

func (HealthCheck) Validate added in v0.4.0 

func (c HealthCheck) Validate() error

Validate returns an error wrapping ErrInvalidArgument if more than one probe is set, which the API cannot carry. The daemon checks the rest.

type HealthStatus added in v0.4.0 

type HealthStatus string

HealthStatus is what an instance's health check has found. 

const (
	// HealthStatusStarting means there is no verdict yet: the workload is
	// in its start period, or has not been probed.
	HealthStatusStarting HealthStatus = "starting"

	// HealthStatusHealthy means the last probe passed.
	HealthStatusHealthy HealthStatus = "healthy"

	// HealthStatusUnhealthy means the check's retries have failed in a row.
	HealthStatusUnhealthy HealthStatus = "unhealthy"
)

The health statuses.

type HostCheckGroup added in v0.4.0 

type HostCheckGroup string

HostCheckGroup says which part of CheckHost's checks a result belongs to. 

const (
	// HostCheckGroupHost holds the results of the checks of the host
	// itself.
	HostCheckGroupHost HostCheckGroup = "host"

	// HostCheckGroupInstances holds the result of the test instance's boot,
	// and whether the test instance reached the internet.
	HostCheckGroupInstances HostCheckGroup = "instances"
)

The host check groups, in the order their results arrive.

type HostCheckResult added in v0.4.0 

type HostCheckResult struct {
	// Group says which part of the checks the result belongs to.
	Group HostCheckGroup `json:"group,omitzero"`

	// Name is what was checked. For the host, it is kvm, ip_forwarding,
	// firewall, tools, uplink or disk. For the test instance, it is the
	// hypervisor's type for the boot, or internet.
	Name string `json:"name,omitzero"`

	// Status is what the check found.
	Status HostCheckStatus `json:"status,omitzero"`

	// Detail says what was found, in one line, for a person to read.
	Detail string `json:"detail,omitzero"`

	// Hint says what to do about a problem, where there is something to do.
	// It is empty for a check that passed.
	Hint string `json:"hint,omitzero"`

	// Console holds the lines of a failed test instance's console that most
	// likely explain the failure: those leading up to a kernel panic, or else
	// the last few.
	Console []string `json:"console,omitzero"`
}

HostCheckResult is the result of one of CheckHost's checks.

type HostCheckStatus added in v0.4.0 

type HostCheckStatus string

HostCheckStatus is what a check found. 

const (
	// HostCheckStatusOK means all is well.
	HostCheckStatusOK HostCheckStatus = "ok"

	// HostCheckStatusWarning means something may cause trouble later, such
	// as little free disk space, but instances can still run.
	HostCheckStatusWarning HostCheckStatus = "warning"

	// HostCheckStatusFailed means something stops instances from booting or
	// from being reached, and must be fixed.
	HostCheckStatusFailed HostCheckStatus = "failed"
)

The host check statuses.

type HostInfo added in v0.4.0 

type HostInfo struct {
	// Version is the daemon's version.
	Version string `json:"version,omitzero"`

	// Hostname is the host's name.
	Hostname string `json:"hostname,omitzero"`

	// Hypervisors are the hypervisors the daemon can start instances with.
	Hypervisors []HypervisorInfo `json:"hypervisors,omitzero"`

	// ListenerAddresses are the addresses clients reach the daemon's TCP
	// listener at. For a listener on all of the host's addresses, they are
	// the host's own, with the default route's first. It is empty if the API
	// is not served over TCP.
	ListenerAddresses []string `json:"listener_addresses,omitzero"`

	// Fingerprint is the fingerprint of the certificate the API is served
	// with over TCP: the SHA-256 of its public key, hex-encoded. It is empty
	// if the API is not served over TCP.
	Fingerprint string `json:"fingerprint,omitzero"`

	// Token is the name of the token the call was made with. It is empty
	// over the socket.
	Token string `json:"token,omitzero"`
}

HostInfo is what a daemon is: its version, the hypervisors it carries, and how it is reached.

type HypervisorInfo added in v0.4.0 

type HypervisorInfo struct {
	// Type is the hypervisor.
	Type HypervisorType `json:"type,omitzero"`

	// Versions are the versions available, the one an instance gets by
	// default first.
	Versions []string `json:"versions,omitzero"`

	// IsDefault reports whether this is the hypervisor an instance gets when
	// it names none.
	IsDefault bool `json:"is_default,omitzero"`

	// DeprecatedVersions are the versions that are deprecated: every one but
	// the default. Each is kept only for what still uses it, and a later
	// release of Dicer removes it.
	DeprecatedVersions []string `json:"deprecated_versions,omitzero"`
}

HypervisorInfo is a hypervisor the daemon carries, and the versions of it an instance may name.

type HypervisorType added in v0.4.0 

type HypervisorType string

HypervisorType is the virtual machine monitor an instance runs on. 

const (
	HypervisorTypeCloudHypervisor HypervisorType = "cloud-hypervisor"
	HypervisorTypeFirecracker     HypervisorType = "firecracker"
)

The hypervisor types.

type Image added in v0.4.0 

type Image struct {
	// Name is the image's reference, in full, such as
	// docker.io/library/nginx:1.27.
	Name string `json:"name,omitzero"`

	// Digest is the digest of the image's manifest.
	Digest string `json:"digest,omitzero"`

	// SizeBytes is the size of the image's disk.
	SizeBytes int64 `json:"size_bytes,omitzero"`

	// CreateTime is when the image was pulled.
	CreateTime time.Time `json:"create_time,omitzero"`

	// UpdateTime is when the image was last changed.
	UpdateTime time.Time `json:"update_time,omitzero"`

	// LastUsedTime is when the image was last pulled or in use: by an
	// instance defined to boot from it, a running guest, a guest on standby
	// or a snapshot. Garbage collection judges it by this.
	LastUsedTime time.Time `json:"last_used_time,omitzero"`

	// HealthCheck is the HEALTHCHECK the image declares, which instances of
	// it run unless they set their own. It is nil if it declares none.
	HealthCheck *HealthCheck `json:"health_check,omitzero"`
}

Image is a pulled image, converted to a root filesystem a guest can boot.

type Images added in v0.4.0 

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

Images are the calls about images, reached as Client.Images. An image is named by its reference, as it is pulled: nginx:1.27 names docker.io/library/nginx:1.27.

func (*Images) Delete added in v0.4.0 

func (s *Images) Delete(ctx context.Context, ref string, opts DeleteOptions) error

Delete removes a pulled image. It refuses an image an instance is defined to boot from with ErrFailedPrecondition, unless opts.Force is set: that instance then pulls it again at its next start.

func (*Images) Get added in v0.4.0 

func (s *Images) Get(ctx context.Context, ref string) (Image, error)

Get returns one pulled image, or ErrNotFound.

func (*Images) List added in v0.4.0 

func (s *Images) List(ctx context.Context) ([]Image, error)

List returns every pulled image.

func (*Images) Prune added in v0.4.0 

func (s *Images) Prune(ctx context.Context) (PruneResult, error)

Prune removes every image no instance is defined to boot from.

func (*Images) Pull added in v0.4.0 

func (s *Images) Pull(ctx context.Context, ref string, onProgress func(PullProgress)) (Image, error)

Pull fetches an image and converts it to a root filesystem a guest can boot, and returns it once it is ready. onProgress, if not nil, is called with each report of how far the pull has got.

type InitMode added in v0.4.0 

type InitMode string

InitMode is how the guest starts an instance's command. 

const (
	// InitModeAuto runs systemd as the machine's PID 1 if the command is the
	// systemd binary, and the command as InitModeExec does otherwise.
	InitModeAuto InitMode = "auto"

	// InitModeExec runs the command as PID 1 of its own PID namespace, as a
	// container runs it.
	InitModeExec InitMode = "exec"

	// InitModeSystemd runs the command, systemd, as the machine's PID 1.
	InitModeSystemd InitMode = "systemd"
)

The init modes.

type Instance added in v0.4.0 

type Instance struct {
	// ID is the instance's ID.
	ID string `json:"id,omitzero"`

	InstanceSpec

	// ImageDigest is the digest ImageRef resolved to when the instance was
	// created. The instance always boots that image: pulling ImageRef again
	// does not change it.
	ImageDigest string `json:"image_digest,omitzero"`

	// CreateTime is when the instance was defined.
	CreateTime time.Time `json:"create_time,omitzero"`

	// UpdateTime is when the instance's definition was last changed, such as
	// by Instances.Update or Instances.Resize.
	UpdateTime time.Time `json:"update_time,omitzero"`

	// State is what the instance is doing.
	State InstanceState `json:"state,omitzero"`

	// StateError says why the last operation failed, for a Failed instance.
	StateError string `json:"state_error,omitzero"`

	// HypervisorPID is the host PID of the instance's hypervisor process, or
	// 0 while there is none.
	HypervisorPID int `json:"hypervisor_pid,omitzero"`

	// VsockCID is the guest's vsock context ID, by which the host reaches its
	// agent. It is set once the instance has started.
	VsockCID int64 `json:"vsock_cid,omitzero"`

	// IP is the instance's address on its network, held for as long as the
	// instance is defined.
	IP string `json:"ip,omitzero"`

	// MAC is the guest's MAC address on its network.
	MAC string `json:"mac,omitzero"`

	// StartTime is when the instance last started. It is zero while the
	// instance is stopped.
	StartTime time.Time `json:"start_time,omitzero"`

	// ExitCode is the exit code the guest reported when it last ended on its
	// own: its workload's, or 0 for a guest that powered itself off. It is
	// nil if the instance has not ended since it was last started, or ended
	// without saying how.
	ExitCode *int `json:"exit_code,omitzero"`

	// FinishTime is when the guest last ended on its own.
	FinishTime time.Time `json:"finish_time,omitzero"`

	// RestartCount is how many times in a row the restart policy has
	// started the instance again. A start a user asks for resets it.
	RestartCount int `json:"restart_count,omitzero"`

	// NextRestartTime is when a Restarting instance is due to start again.
	NextRestartTime time.Time `json:"next_restart_time,omitzero"`

	// Health is what the health check of the running instance has found, or
	// nil if it is not running or has no check.
	Health *Health `json:"health,omitzero"`
}

Instance is a virtual machine: its definition, and what it is doing now. The fields after UpdateTime are empty while it is not running.

type InstanceResources added in v0.4.0 

type InstanceResources struct {
	// Name is the instance's name.
	Name string `json:"name,omitzero"`

	// State is the instance's state: starting, running or paused.
	State InstanceState `json:"state,omitzero"`

	// VCPUs is how many vCPUs the instance holds.
	VCPUs int `json:"vcpus,omitzero"`

	// MemoryBytes is how much memory the instance holds.
	MemoryBytes int64 `json:"memory_bytes,omitzero"`
}

InstanceResources are what one instance holds.

type InstanceSpec added in v0.4.0 

type InstanceSpec struct {
	// Name is the instance's name: letters, digits and hyphens, in
	// dot-separated parts that each start and end with a letter or digit.
	// Empty means one made from the image's name, such as nginx-k3x9.
	Name string `json:"name,omitzero"`

	// Hostname is the guest's hostname. Empty means the instance's name.
	Hostname string `json:"hostname,omitzero"`

	// ImageRef is the image the instance boots from, such as nginx:1.27. It
	// is resolved to a digest when the instance is created, which the
	// instance boots from then on: see Instance.ImageDigest.
	ImageRef string `json:"image_ref,omitzero"`

	// HypervisorType is the hypervisor the instance runs on. Empty means
	// Cloud Hypervisor.
	HypervisorType HypervisorType `json:"hypervisor_type,omitzero"`

	// HypervisorVersion is a version that hypervisor ships. Empty is its
	// default version, which HypervisorInfo lists first.
	HypervisorVersion string `json:"hypervisor_version,omitzero"`

	// KernelName is the kernel the guest boots. Empty means "default".
	KernelName string `json:"kernel_name,omitzero"`

	// KernelArgs is the kernel's command line. Empty means the hypervisor's
	// default.
	KernelArgs string `json:"kernel_args,omitzero"`

	// VCPUs is how many virtual CPUs the guest has. It must be at least 1.
	VCPUs int `json:"vcpus,omitzero"`

	// MemoryBytes is the guest's memory. It must be more than 0.
	MemoryBytes int64 `json:"memory_bytes,omitzero"`

	// MaxVCPUs is the most vCPUs Instances.Resize can give the running
	// instance. It boots with room for them, which costs the host nothing
	// until they are used. Zero leaves no room. Only Cloud Hypervisor on
	// x86_64 can add vCPUs to a running guest, so it is refused anywhere
	// else.
	MaxVCPUs int `json:"max_vcpus,omitzero"`

	// MaxMemoryBytes is the most memory Instances.Resize can give the running
	// instance. It boots with room for it, which costs the host nothing until
	// it is used. Zero leaves no room.
	MaxMemoryBytes int64 `json:"max_memory_bytes,omitzero"`

	// DiskBytes is the size of the overlay disk, which holds what the guest
	// writes over its image. It must be more than 0.
	DiskBytes int64 `json:"disk_bytes,omitzero"`

	// DiskBytesPerSecond limits how many bytes a second each of the
	// instance's disks is read and written at. Zero is unlimited.
	DiskBytesPerSecond int64 `json:"disk_bytes_per_second,omitzero"`

	// DiskIOPS limits how many operations a second each of the instance's
	// disks is read and written at. Zero is unlimited.
	DiskIOPS int64 `json:"disk_iops,omitzero"`

	// UploadBytesPerSecond limits how many bytes a second the guest sends on
	// its network. Zero is unlimited.
	UploadBytesPerSecond int64 `json:"upload_bytes_per_second,omitzero"`

	// DownloadBytesPerSecond limits how many bytes a second the guest
	// receives on its network. Zero is unlimited.
	DownloadBytesPerSecond int64 `json:"download_bytes_per_second,omitzero"`

	// StandbyAfter is how long the instance may be idle before it is put on
	// standby: at least a minute, or zero for never.
	StandbyAfter time.Duration `json:"standby_after,omitzero"`

	// NetworkName is the network the instance joins. Empty means "default".
	NetworkName string `json:"network_name,omitzero"`

	// StaticIP is the instance's address on its network. Empty means one is
	// assigned from the subnet.
	StaticIP string `json:"static_ip,omitzero"`

	// Mounts are the volumes, files and tmpfs filesystems mounted in the
	// guest.
	Mounts []Mount `json:"mounts,omitzero"`

	// Env is added to the image's environment, replacing a variable the image
	// sets.
	Env map[string]string `json:"env,omitzero"`

	// Cmd replaces the image's entrypoint and command. Empty runs the
	// image's.
	Cmd []string `json:"cmd,omitzero"`

	// Labels are keys and values of your own, to group and find instances by.
	Labels map[string]string `json:"labels,omitzero"`

	// RestartPolicy is when the instance is started again after its guest
	// ends on its own. Empty means never.
	RestartPolicy RestartPolicy `json:"restart_policy,omitzero"`

	// HealthCheck is how the instance's health is checked, overriding its
	// image's. Nil means the image's, if it declares one.
	HealthCheck *HealthCheck `json:"health_check,omitzero"`

	// InitMode is how the guest starts the command. Empty means auto.
	InitMode InitMode `json:"init_mode,omitzero"`

	// User is who the workload runs as in the exec init mode: user, uid,
	// user:group or uid:gid, looked up in the guest's /etc/passwd and
	// /etc/group. Empty means the image's USER, or root if it has none. The
	// systemd init mode runs as root, so it cannot be given a user.
	User string `json:"user,omitzero"`

	// Ports are the guest ports published on the host.
	Ports []PortMapping `json:"ports,omitzero"`

	// RemoveOnExit deletes the instance once it stops, whether its guest
	// ended on its own or someone stopped it. The daemon does the deleting,
	// so it happens even if the client has gone. An instance that its
	// restart policy will start again is not deleted.
	RemoveOnExit bool `json:"remove_on_exit,omitzero"`
}

InstanceSpec is the definition of an instance: what it boots, and with what. ImageRef, VCPUs, MemoryBytes and DiskBytes must be set. Other empty fields take the daemon's defaults.

type InstanceState added in v0.4.0 

type InstanceState string

InstanceState is where an instance is in its lifecycle. 

const (
	// InstanceStateStopped means the instance is defined but not running. A
	// new instance starts here.
	InstanceStateStopped InstanceState = "stopped"

	// InstanceStateStarting means a start is in progress.
	InstanceStateStarting InstanceState = "starting"

	// InstanceStateRunning means the guest is running.
	InstanceStateRunning InstanceState = "running"

	// InstanceStatePaused means the guest's vCPUs are halted, and it is kept
	// resident.
	InstanceStatePaused InstanceState = "paused"

	// InstanceStateStopping means a stop is in progress.
	InstanceStateStopping InstanceState = "stopping"

	// InstanceStateRestarting means the instance ended without being asked
	// to, and its restart policy will start it again at NextRestartTime.
	InstanceStateRestarting InstanceState = "restarting"

	// InstanceStateFailed means the last operation failed; StateError says
	// why.
	InstanceStateFailed InstanceState = "failed"

	// InstanceStateStandby means the guest is frozen to disk and its
	// hypervisor has ended. Starting it resumes it where it was.
	InstanceStateStandby InstanceState = "standby"
)

The instance states.

type InstanceStats added in v0.4.0 

type InstanceStats struct {
	// Name is the instance's name.
	Name string `json:"name,omitzero"`

	// ID is the instance's ID.
	ID string `json:"id,omitzero"`

	// CPUPercent is the CPU used over the last second, as a percentage of
	// one host CPU: 200 is two CPUs kept busy.
	CPUPercent float64 `json:"cpu_percent,omitzero"`

	// CPUTime is the CPU time used in total.
	CPUTime time.Duration `json:"cpu_time,omitzero"`

	// VCPUs is how many vCPUs the instance holds.
	VCPUs int `json:"vcpus,omitzero"`

	// MemoryBytes is how much memory the instance holds.
	MemoryBytes int64 `json:"memory_bytes,omitzero"`

	// ResidentMemoryBytes is the resident host memory of the instance's
	// hypervisor process: the guest memory backed so far, and the
	// hypervisor's own. Memory a guest frees stays resident.
	ResidentMemoryBytes int64 `json:"resident_memory_bytes,omitzero"`

	// DiskReadBytes is how many bytes the hypervisor process read from
	// storage. Reads served from the host's page cache are not counted.
	DiskReadBytes int64 `json:"disk_read_bytes,omitzero"`

	// DiskWrittenBytes is how many bytes the hypervisor process wrote to
	// storage.
	DiskWrittenBytes int64 `json:"disk_written_bytes,omitzero"`

	// NetworkReceiveBytes is how many bytes the guest received on its network
	// interface.
	NetworkReceiveBytes int64 `json:"network_receive_bytes,omitzero"`

	// NetworkTransmitBytes is how many bytes the guest transmitted on its
	// network interface.
	NetworkTransmitBytes int64 `json:"network_transmit_bytes,omitzero"`

	// NetworkReceivePackets is how many packets the guest received on its
	// network interface.
	NetworkReceivePackets int64 `json:"network_receive_packets,omitzero"`

	// NetworkTransmitPackets is how many packets the guest transmitted on its
	// network interface.
	NetworkTransmitPackets int64 `json:"network_transmit_packets,omitzero"`

	// NetworkReceiveDrops is how many packets were dropped on their way to
	// the guest. They mostly mean the guest does not take packets as fast as
	// they come.
	NetworkReceiveDrops int64 `json:"network_receive_drops,omitzero"`

	// NetworkTransmitDrops is how many packets were dropped on their way from
	// the guest.
	NetworkTransmitDrops int64 `json:"network_transmit_drops,omitzero"`

	// NetworkReceiveErrors is how many packets to the guest failed with an
	// error.
	NetworkReceiveErrors int64 `json:"network_receive_errors,omitzero"`

	// NetworkTransmitErrors is how many packets from the guest failed with an
	// error.
	NetworkTransmitErrors int64 `json:"network_transmit_errors,omitzero"`
}

InstanceStats is what an instance's hypervisor process uses of the host, read from the process rather than asked of the guest. Its vCPUs and the threads emulating its devices are counted together, and totals are since the process started: each start of the instance begins them again.

type InstanceStatsBatch added in v0.4.0 

type InstanceStatsBatch struct {
	// ReadTime is when the batch was read.
	ReadTime time.Time `json:"read_time,omitzero"`

	// Instances are the instances, in name order.
	Instances []InstanceStats `json:"instances,omitzero"`
}

InstanceStatsBatch is what the instances used over one second.

type InstanceStatsOptions added in v0.4.0 

type InstanceStatsOptions struct {
	// Names are the instances to report on, by name or ID. Empty means
	// every instance running or paused, as they come and go. A named
	// instance is left out of a batch while it is not running or paused.
	Names []string

	// Follow keeps the stream open, sending a batch a second. Otherwise a
	// single batch is sent.
	Follow bool
}

InstanceStatsOptions pick the instances Instances.Stats reports on.

type InstanceStatsStream added in v0.4.0 

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

InstanceStatsStream is a stream of instance stats, read with Next.

func (*InstanceStatsStream) Close added in v0.4.0 

func (s *InstanceStatsStream) Close() error

Close ends the stream.

func (*InstanceStatsStream) Next added in v0.4.0 

func (s *InstanceStatsStream) Next() (InstanceStatsBatch, error)

Next returns the next batch. It returns io.EOF after the last, and the error the stream failed with otherwise, such as context.Canceled once it is closed.

type InstanceUpdate added in v0.4.0 

type InstanceUpdate struct {
	// HypervisorType replaces the hypervisor the instance runs on.
	HypervisorType HypervisorType

	// HypervisorVersion replaces the hypervisor's version.
	HypervisorVersion *string

	// KernelName replaces the kernel the guest boots.
	KernelName *string

	// KernelArgs replaces the kernel's command line.
	KernelArgs *string

	// VCPUs replaces how many vCPUs the guest has.
	VCPUs *int

	// MemoryBytes replaces the guest's memory.
	MemoryBytes *int64

	// MaxVCPUs replaces the most vCPUs Instances.Resize can give the running
	// instance. Zero removes the maximum.
	MaxVCPUs *int

	// MaxMemoryBytes replaces the most memory Instances.Resize can give the
	// running instance. Zero removes the maximum.
	MaxMemoryBytes *int64

	// DiskBytes grows the overlay disk at the instance's next start. It
	// cannot shrink, so a size smaller than the overlay disk is refused.
	DiskBytes *int64

	// DiskBytesPerSecond replaces the disks' limit of bytes a second. Zero
	// removes the limit.
	DiskBytesPerSecond *int64

	// DiskIOPS replaces the disks' limit of operations a second. Zero removes
	// the limit.
	DiskIOPS *int64

	// UploadBytesPerSecond replaces the limit on the bytes a second the guest
	// sends. Zero removes the limit.
	UploadBytesPerSecond *int64

	// DownloadBytesPerSecond replaces the limit on the bytes a second the
	// guest receives. Zero removes the limit.
	DownloadBytesPerSecond *int64

	// StandbyAfter replaces how long the instance may be idle before it is
	// put on standby. Zero is never.
	StandbyAfter *time.Duration

	// NetworkName replaces the network the instance joins.
	NetworkName *string

	// StaticIP replaces the instance's address on its network.
	StaticIP *string

	// Hostname replaces the guest's hostname.
	Hostname *string

	// RestartPolicy replaces when the instance is started again.
	RestartPolicy *RestartPolicy

	// HealthCheck replaces the instance's health check.
	HealthCheck *HealthCheck

	// InitMode replaces how the guest starts the command.
	InitMode InitMode

	// User replaces who the workload runs as. Empty goes back to the
	// image's USER.
	User *string

	// RemoveOnExit replaces whether the instance is deleted once it stops.
	RemoveOnExit *bool

	// Mounts replace the instance's mounts.
	Mounts []Mount

	// Env replaces the variables added to the image's environment.
	Env map[string]string

	// Cmd replaces the command the guest runs.
	Cmd []string

	// Labels replace the instance's labels.
	Labels map[string]string

	// Ports replace the guest ports published on the host.
	Ports []PortMapping
}

InstanceUpdate is a change to the definition of a stopped or failed instance. Only the fields that are set change: a pointer that is not nil, an enumeration that is not empty, and a slice or map that is not empty, which replaces the existing value whole. The image cannot be changed: an instance always boots the image it was created with. new makes the pointers: 

update := dicer.InstanceUpdate{VCPUs: new(4), Labels: map[string]string{"tier": "web"}}

type Instances added in v0.4.0 

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

Instances are the calls about instances, reached as Client.Instances. A call that takes an instance's name takes its ID as well.

func (*Instances) Command added in v0.4.0 

func (s *Instances) Command(name string, args ...string) *Cmd

Command returns a Cmd that runs args in an instance: the command and its arguments, or /bin/sh if there are none. 

out, err := c.Instances.Command("web", "cat", "/etc/os-release").Output(ctx)

func (*Instances) CopyArchiveFrom added in v0.4.0 

func (s *Instances) CopyArchiveFrom(ctx context.Context, name, src string) (io.ReadCloser, error)

CopyArchiveFrom returns a reader of a tar archive of src in an instance, which holds it as a single file or directory at its top level. The reader must be closed when done. Reading it returns the error the call failed with, such as ErrNotFound for a path that is not there.

func (*Instances) CopyArchiveTo added in v0.4.0 

func (s *Instances) CopyArchiveTo(ctx context.Context, name, dest string, r io.Reader) error

CopyArchiveTo unpacks a tar archive into an instance at dest. The archive holds a single file or directory at its top level, as archive/tar writes it from fs.FileInfoHeader.

func (*Instances) CopyFrom added in v0.4.0 

func (s *Instances) CopyFrom(ctx context.Context, name, src, dest string) error

CopyFrom copies src, a file or directory in an instance, to dest on this machine.

func (*Instances) CopyTo added in v0.4.0 

func (s *Instances) CopyTo(ctx context.Context, name, src, dest string) error

CopyTo copies src, a file or directory on this machine, to dest in a running instance, waiting for a guest that is still booting.

What is copied lands as cp -r would put it: into dest if it is a directory, in its place if it is a file, and at it if nothing is there. A relative path in the guest is taken from its root directory. Modes, times and symlinks are kept. Ownership is not, so what is copied belongs to whoever receives it. CopyFrom and the other copying calls do the same.

func (*Instances) Create added in v0.4.0 

func (s *Instances) Create(ctx context.Context, spec InstanceSpec, opts CreateOptions) (Instance, error)

Create defines an instance, without starting it unless opts says to. It first pulls the image as opts.PullPolicy says, reporting no progress: to show a pull's progress, call Images.Pull first. Nothing is defined if the image cannot be had.

func (*Instances) Delete added in v0.4.0 

func (s *Instances) Delete(ctx context.Context, name string, opts DeleteOptions) error

Delete removes an instance and its overlay disk. It refuses a running instance with ErrFailedPrecondition, unless opts.Force is set.

func (*Instances) Fork added in v0.4.0 

func (s *Instances) Fork(ctx context.Context, name string, opts ForkOptions) (Instance, error)

Fork creates an instance as a copy of another, as Snapshots.Create followed by Snapshots.Fork would, but keeps no snapshot. A running or paused instance is paused while its memory is written, and its fork runs. A stopped instance's fork is stopped.

func (*Instances) Get added in v0.4.0 

func (s *Instances) Get(ctx context.Context, name string) (Instance, error)

Get returns one instance, or ErrNotFound.

func (*Instances) List added in v0.4.0 

func (s *Instances) List(ctx context.Context) ([]Instance, error)

List returns every instance.

func (*Instances) Logs added in v0.4.0 

func (s *Instances) Logs(ctx context.Context, name string, opts LogOptions) (io.ReadCloser, error)

Logs returns a reader of an instance's log. It must be closed when done. Reading it returns the error the call failed with, such as ErrNotFound, and io.EOF at the end of the log.

func (*Instances) Pause added in v0.4.0 

func (s *Instances) Pause(ctx context.Context, name string) (Instance, error)

Pause halts a running instance's vCPUs, keeping it resident.

func (*Instances) Processes added in v0.4.0 

func (s *Instances) Processes(ctx context.Context, name string) ([]Process, error)

Processes returns the processes running in a running instance, as its guest sees them, in PID order. Kernel threads are left out. It waits for a guest that is still booting.

func (*Instances) ReadFile added in v0.4.0 

func (s *Instances) ReadFile(ctx context.Context, name, file string) ([]byte, error)

ReadFile returns the contents of a regular file in an instance.

func (*Instances) Rename added in v0.4.0 

func (s *Instances) Rename(ctx context.Context, name, newName string) (Instance, error)

Rename changes a stopped instance's name. The instance keeps its ID, its disks and its address.

func (*Instances) Resize added in v0.4.0 

func (s *Instances) Resize(ctx context.Context, name string, opts ResizeOptions) (Instance, error)

Resize changes a running instance's vCPUs and memory without restarting it, within its MaxVCPUs and MaxMemoryBytes, and its definition with them. It fails with ErrResourceExhausted if the host has no room to grow it.

func (*Instances) Resume added in v0.4.0 

func (s *Instances) Resume(ctx context.Context, name string) (Instance, error)

Resume continues a paused instance.

func (*Instances) Standby added in v0.4.0 

func (s *Instances) Standby(ctx context.Context, name string) (Instance, error)

Standby freezes a running or paused instance to disk and ends its hypervisor, freeing the CPU and memory it held. Start resumes it where it was; Stop discards what was frozen.

func (*Instances) Start added in v0.4.0 

func (s *Instances) Start(ctx context.Context, name string) (Instance, error)

Start boots a defined instance, or resumes one on standby. It returns once the guest's agent answers, or once its workload has ended, however it ended. A guest that does not boot fails with ErrFailedPrecondition, and the error says why, quoting the console. ErrUnavailable means the daemon shut down before the guest booted.

func (*Instances) Stats added in v0.4.0 

func (s *Instances) Stats(ctx context.Context, opts InstanceStatsOptions) (*InstanceStatsStream, error)

Stats streams what running and paused instances use of the host. Each batch is read over a second, so the first comes a second after the call. The stream must be closed when done.

func (*Instances) Stop added in v0.4.0 

func (s *Instances) Stop(ctx context.Context, name string) (Instance, error)

Stop shuts a running instance down, keeping its definition, overlay disk and address.

func (*Instances) Update added in v0.4.0 

func (s *Instances) Update(ctx context.Context, name string, update InstanceUpdate) (Instance, error)

Update changes the definition of a stopped instance.

func (*Instances) Wait added in v0.4.0 

func (s *Instances) Wait(ctx context.Context, name string, opts WaitOptions) (int, error)

Wait waits for an instance to stop, or for what opts.Condition says, and returns the status its guest ended with, as Waiter.Wait does. Without opts.NextStop, an instance that has already stopped is not waited for: its last status is returned at once. One that has been deleted is not found, so a caller that wants the status of an instance deleted as it stops, as RemoveOnExit does, waits for it with a Waiter made before it starts.

func (*Instances) Waiter added in v0.4.0 

func (s *Instances) Waiter(ctx context.Context, name string, opts WaitOptions) (*Waiter, error)

Waiter begins waiting for an instance to stop, or for what opts.Condition says, and returns once the daemon is waiting. An instance started after it returns cannot end unheard, even if it is deleted as it stops, so a caller that starts an instance and waits for it makes its Waiter, with NextStop, first. The caller must Close it. ctx bounds the whole wait.

func (*Instances) WriteFile added in v0.4.0 

func (s *Instances) WriteFile(ctx context.Context, name, file string, data []byte, perm fs.FileMode) error

WriteFile writes data to a file in an instance, creating it with perm if it is not there, and replacing it if it is. Its directory must exist. If the path names a directory, the file is written into it, under the path's last element.

type IssuedToken added in v0.4.0 

type IssuedToken struct {
	Token

	// Value is what a client connects with, as WithToken takes it.
	Value string `json:"value"`
}

IssuedToken is a token with its value, as it is created or rotated.

type Kernel added in v0.4.0 

type Kernel struct {
	// ID is the kernel's ID.
	ID string `json:"id,omitzero"`

	KernelSpec

	// CreateTime is when the kernel was added to the host.
	CreateTime time.Time `json:"create_time,omitzero"`

	// UpdateTime is when the kernel was last changed. Only the default kernel
	// changes: it is updated to the version each release of Dicer carries.
	UpdateTime time.Time `json:"update_time,omitzero"`
}

Kernel is a guest kernel instances can boot.

type KernelSpec added in v0.4.0 

type KernelSpec struct {
	// Name is the kernel's name, which an instance gives as its KernelName.
	Name string `json:"name,omitzero"`

	// Architecture is the CPU architecture the kernel is built for.
	Architecture Architecture `json:"architecture,omitzero"`

	// SHA256 is the SHA-256 of the kernel, hex-encoded. An import verifies
	// the kernel against it when it is set, and sets it when it is not.
	SHA256 string `json:"sha256,omitzero"`
}

KernelSpec is what a kernel is.

type Kernels added in v0.4.0 

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

Kernels are the calls about guest kernels, reached as Client.Kernels.

func (*Kernels) Delete added in v0.4.0 

func (s *Kernels) Delete(ctx context.Context, name string) error

Delete removes a kernel that no instance references. The default kernel cannot be deleted.

func (*Kernels) Get added in v0.4.0 

func (s *Kernels) Get(ctx context.Context, name string) (Kernel, error)

Get returns one kernel, or ErrNotFound.

func (*Kernels) Import added in v0.4.0 

func (s *Kernels) Import(ctx context.Context, spec KernelSpec, r io.Reader) (Kernel, error)

Import puts the kernel read from r on the daemon's host, and returns once it is there. A kernel can be at most 512 MiB. It is verified against spec.SHA256 if that is set, and given the SHA-256 of what was sent if not.

func (*Kernels) List added in v0.4.0 

func (s *Kernels) List(ctx context.Context) ([]Kernel, error)

List returns every kernel, the default one among them.

type LogOptions added in v0.4.0 

type LogOptions struct {
	// Source is the log to read. Empty means the guest's console.
	Source LogSource

	// TailLines limits the output to the last lines. Zero means all of it.
	TailLines int

	// Follow keeps the log open, reading new output until the instance
	// stops.
	Follow bool
}

LogOptions pick the log Instances.Logs reads, and how much of it.

type LogSource added in v0.4.0 

type LogSource string

LogSource is one of the logs an instance produces. Both are kept with the instance, across stops and restarts, until it is deleted. 

const (
	// LogSourceGuest is the guest's console log: the kernel's boot
	// messages, dicer-init's, and whatever the workload writes to the
	// console.
	LogSourceGuest LogSource = "guest"

	// LogSourceHypervisor is the hypervisor's own log, which explains a
	// guest that crashed or never booted.
	LogSourceHypervisor LogSource = "hypervisor"
)

The log sources.

type Mount added in v0.4.0 

type Mount struct {
	// Type is what is mounted: a volume, a file or a tmpfs.
	Type MountType `json:"type,omitzero"`

	// Source is the volume's name for a volume, and the absolute path of a
	// directory on the daemon's host for a directory. A file and a tmpfs
	// have none.
	Source string `json:"source,omitzero"`

	// Target is the absolute path the mount appears at in the guest.
	Target string `json:"target,omitzero"`

	// ReadOnly mounts it read-only. A volume every instance mounts read-only
	// can be shared between them.
	ReadOnly bool `json:"read_only,omitzero"`

	// Content is a file's contents. The daemon keeps them with the instance
	// and writes them into the guest at each start. An instance's file
	// mounts can hold at most 1 MiB between them. FileMount reads them from
	// a file on this machine.
	Content []byte `json:"content,omitzero"`

	// Mode is a file's permission bits in the guest, where root owns it.
	// Zero is 0644.
	Mode fs.FileMode `json:"mode,omitzero"`
}

Mount attaches a volume, a file, a host directory or a tmpfs at Target in the guest.

func FileMount added in v0.4.0 

func FileMount(path, target string) (Mount, error)

FileMount returns a mount that puts a copy of the file at path, on this machine, at target in the guest, with the file's permission bits.

type MountType added in v0.4.0 

type MountType string

MountType is what a Mount attaches. 

const (
	// MountTypeVolume is a named volume: persistent storage, as a disk of
	// its own.
	MountTypeVolume MountType = "volume"

	// MountTypeFile is a file whose contents the client gives, written
	// into the guest at each start.
	MountTypeFile MountType = "file"

	// MountTypeTmpfs is an empty in-memory filesystem, lost when the guest
	// stops.
	MountTypeTmpfs MountType = "tmpfs"

	// MountTypeDirectory is a directory on the daemon's host, shared with
	// the guest while it runs: a change on either side is seen on the
	// other. The daemon allows only the directories its configuration
	// lists, and only on Cloud Hypervisor.
	MountTypeDirectory MountType = "directory"
)

The mount types.

type Network added in v0.4.0 

type Network struct {
	// ID is the network's ID.
	ID string `json:"id,omitzero"`

	NetworkSpec

	// Bridge is the name of the network's bridge device on the host.
	Bridge string `json:"bridge,omitzero"`

	// TotalIPs is how many addresses the subnet has for instances: all but
	// its network, gateway and broadcast addresses.
	TotalIPs int64 `json:"total_ips,omitzero"`

	// FreeIPs is how many of those addresses are not assigned to an instance.
	FreeIPs int64 `json:"free_ips,omitzero"`

	// CreateTime is when the network was created.
	CreateTime time.Time `json:"create_time,omitzero"`

	// UpdateTime is when the network was last changed.
	UpdateTime time.Time `json:"update_time,omitzero"`
}

Network is a host-local bridge with NAT to the uplink.

type NetworkAllocation added in v0.4.0 

type NetworkAllocation struct {
	// InstanceID is the ID of the instance the address is assigned to.
	InstanceID string `json:"instance_id,omitzero"`

	// InstanceName is that instance's name.
	InstanceName string `json:"instance_name,omitzero"`

	// IP is the address.
	IP string `json:"ip,omitzero"`

	// MAC is the guest's MAC address on the network.
	MAC string `json:"mac,omitzero"`

	// TapDevice is the name of the TAP device that connects the guest to the
	// network's bridge.
	TapDevice string `json:"tap_device,omitzero"`
}

NetworkAllocation is an address assigned to an instance.

type NetworkSpec added in v0.4.0 

type NetworkSpec struct {
	// Name is the network's name, which an instance gives as its NetworkName.
	Name string `json:"name,omitzero"`

	// Subnet is the network's IPv4 subnet, such as 172.20.0.0/16. It is
	// required.
	Subnet string `json:"subnet,omitzero"`

	// Gateway is the host's address on the network. Empty means the subnet's
	// first address.
	Gateway string `json:"gateway,omitzero"`

	// MTU is the largest packet the network carries, in bytes. Zero means
	// 1500.
	MTU int `json:"mtu,omitzero"`

	// Nameservers are the upstream nameservers the network's instances are
	// given. An internal network takes none.
	Nameservers []string `json:"nameservers,omitzero"`

	// Isolated stops instances on the network reaching each other. Each can
	// still reach the gateway and, through NAT, the outside.
	Isolated bool `json:"isolated,omitzero"`

	// Internal stops instances on the network reaching anything beyond it:
	// the outside, other networks, the host's services and upstream
	// nameservers. They can still be reached through published ports.
	Internal bool `json:"internal,omitzero"`
}

NetworkSpec is the definition of a network. Empty fields take the daemon's defaults.

type Networks added in v0.4.0 

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

Networks are the calls about networks, reached as Client.Networks.

func (*Networks) Allocations added in v0.4.0 

func (s *Networks) Allocations(ctx context.Context, name string) ([]NetworkAllocation, error)

Allocations returns the addresses assigned on a network.

func (*Networks) Create added in v0.4.0 

func (s *Networks) Create(ctx context.Context, spec NetworkSpec) (Network, error)

Create defines a network and sets up its bridge.

func (*Networks) Delete added in v0.4.0 

func (s *Networks) Delete(ctx context.Context, name string) error

Delete removes a network that no instance references, with its bridge. The default network cannot be deleted.

func (*Networks) Get added in v0.4.0 

func (s *Networks) Get(ctx context.Context, name string) (Network, error)

Get returns one network, or ErrNotFound.

func (*Networks) List added in v0.4.0 

func (s *Networks) List(ctx context.Context) ([]Network, error)

List returns every network.

type Option 

type Option func(*options)

An Option configures a Client.

func WithAddress 

func WithAddress(target string) Option

WithAddress sets the daemon's address, as a gRPC target: "unix:///path/to/socket", or "host:port" for its TCP listener. The default is DefaultAddress. An empty target means the default too, so that an address that may be unset can be passed as it is.

func WithDialOptions 

func WithDialOptions(opts ...grpc.DialOption) Option

WithDialOptions adds gRPC dial options, such as interceptors. They are applied after WithKeepalive's, so a keepalive given here replaces it.

func WithKeepalive added in v0.3.0 

func WithKeepalive(interval, timeout time.Duration) Option

WithKeepalive sets how long a connection may carry nothing before the client pings the daemon, and how long it waits for the answer before giving the connection up, failing the calls in flight on it with codes.Unavailable. That is how a daemon that has gone without closing the connection, because its host lost power or the network between dropped, is noticed; without it, a call waits for as long as its context lets it.

The defaults are DefaultKeepaliveInterval and DefaultKeepaliveTimeout. An interval of zero turns the pings off, and a timeout of zero is the default. gRPC raises an interval below 10s to 10s, and a daemon closes the connection of a client that pings more often than its server.keepalive.min_client_interval.

A connection over a Unix socket is never pinged: the kernel closes it if the daemon goes.

func WithTLS 

func WithTLS(cfg *tls.Config) Option

WithTLS secures the connection to a daemon's TCP listener with cfg, in place of the check the token implies. It is for a daemon served with a certificate from an authority the host does not trust, such as a company's own: cfg.RootCAs names it.

func WithToken added in v0.4.0 

func WithToken(value string) Option

WithToken makes every call with a token, which a daemon's TCP listener requires. `dicer token create`, on the daemon's host, makes one. The client checks the daemon by the fingerprint the token carries. A token without a fingerprint is for a daemon whose certificate the host's root CAs verify, unless WithTLS says otherwise.

type PortMapping added in v0.4.0 

type PortMapping struct {
	// HostIP is the host address to publish on. Empty means every address
	// the host has.
	HostIP string `json:"host_ip,omitzero"`

	// HostPort is the host port to publish on.
	HostPort int `json:"host_port,omitzero"`

	// GuestPort is the guest port that HostPort reaches.
	GuestPort int `json:"guest_port,omitzero"`

	// Protocol is the transport published. Empty means TCP.
	Protocol Protocol `json:"protocol,omitzero"`
}

PortMapping publishes a guest port on the host, so that the guest can be reached from outside it. Traffic to the host's loopback addresses is not relayed.

type Process added in v0.4.0 

type Process struct {
	// PID is the process's ID in the guest.
	PID int `json:"pid,omitzero"`

	// PPID is the ID of the process's parent.
	PPID int `json:"ppid,omitzero"`

	// User is the user the process runs as, by name, or by UID if the guest
	// has no name for it.
	User string `json:"user,omitzero"`

	// State is the state code: R running, S sleeping, D waiting on I/O, Z
	// zombie, T stopped, and so on.
	State string `json:"state,omitzero"`

	// Name is the command's name, which the kernel keeps even when the
	// command line is gone, as it is for a zombie.
	Name string `json:"name,omitzero"`

	// Command is the command line. It is empty for a zombie.
	Command []string `json:"command,omitzero"`

	// StartTime is when the process started, by the guest's clock.
	StartTime time.Time `json:"start_time,omitzero"`

	// CPUTime is the CPU time used in total, in user and kernel mode.
	CPUTime time.Duration `json:"cpu_time,omitzero"`

	// ResidentMemoryBytes is the process's resident memory in the guest.
	ResidentMemoryBytes int64 `json:"resident_memory_bytes,omitzero"`
}

Process is a process running in an instance's guest.

type Protocol added in v0.4.0 

type Protocol string

Protocol is the transport a port mapping publishes. 

const (
	ProtocolTCP Protocol = "tcp"
	ProtocolUDP Protocol = "udp"
)

The protocols.

type PruneResult added in v0.4.0 

type PruneResult struct {
	// Images are the images deleted.
	Images []Image `json:"images,omitzero"`

	// ReclaimedBytes is the disk space their disks and cached layers gave
	// back.
	ReclaimedBytes int64 `json:"reclaimed_bytes,omitzero"`
}

PruneResult is what Images.Prune removed.

type PullPolicy added in v0.4.0 

type PullPolicy string

PullPolicy is when creating an instance pulls its image, as docker run --pull says. 

const (
	// PullPolicyMissing pulls the image only if the host does not hold it.
	PullPolicyMissing PullPolicy = "missing"

	// PullPolicyAlways pulls the image even if the host holds it, so that a
	// tag that has moved is followed. Nothing is downloaded if the host
	// already has what the tag points at.
	PullPolicyAlways PullPolicy = "always"

	// PullPolicyNever uses the image the host holds, and fails with
	// ErrNotFound if it holds none.
	PullPolicyNever PullPolicy = "never"
)

The pull policies.

type PullProgress added in v0.4.0 

type PullProgress struct {
	// Stage is the step the pull is at.
	Stage PullStage `json:"stage,omitzero"`

	// DownloadedBytes is how many compressed layer bytes have been fetched.
	// It is zero outside the downloading stage.
	DownloadedBytes int64 `json:"downloaded_bytes,omitzero"`

	// TotalBytes is how many compressed layer bytes are to be fetched. It
	// counts only what is actually fetched: a layer already held is not
	// downloaded again. It is zero outside the downloading stage.
	TotalBytes int64 `json:"total_bytes,omitzero"`
}

PullProgress is how far a pull has got.

type PullStage added in v0.4.0 

type PullStage string

PullStage is the part of a pull that is working. 

const (
	// PullStageResolving is asking the registry what the reference points
	// at.
	PullStageResolving PullStage = "resolving"

	// PullStageDownloading is fetching the layers, the only stage with a
	// byte count.
	PullStageDownloading PullStage = "downloading"

	// PullStageUnpacking is writing those layers out as a root filesystem.
	PullStageUnpacking PullStage = "unpacking"

	// PullStageConverting is packing that filesystem into the disk a guest
	// boots from.
	PullStageConverting PullStage = "converting"
)

The pull stages.

type ResizeOptions added in v0.4.0 

type ResizeOptions struct {
	// VCPUs is how many vCPUs to give the instance.
	VCPUs int

	// MemoryBytes is how much memory to give the instance.
	MemoryBytes int64
}

ResizeOptions are what Instances.Resize gives a running instance. A field left zero stays as it is, and at least one must be set.

type ResourceCapacity added in v0.4.0 

type ResourceCapacity struct {
	// Host is what the host has: its logical CPUs, or its memory.
	Host int64 `json:"host,omitzero"`

	// Reserved is what is kept back from instances for the host itself.
	Reserved int64 `json:"reserved,omitzero"`

	// Overcommit is how far what remains is stretched: 4 lets four vCPUs
	// share each CPU.
	Overcommit float64 `json:"overcommit,omitzero"`

	// Allocatable is what instances may be given in total:
	// (Host - Reserved) * Overcommit.
	Allocatable int64 `json:"allocatable,omitzero"`

	// Allocated is what instances hold.
	Allocated int64 `json:"allocated,omitzero"`

	// Available is what is left for further instances: Allocatable -
	// Allocated, or 0.
	Available int64 `json:"available,omitzero"`
}

ResourceCapacity is how much of one resource instances may be given, and how much they hold. A start that would take Allocated past Allocatable is refused.

type Resources added in v0.4.0 

type Resources struct {
	// CPU is how the host's CPUs are shared out, counted in vCPUs.
	CPU ResourceCapacity `json:"cpu,omitzero"`

	// Memory is how the host's memory is shared out, in bytes.
	Memory ResourceCapacity `json:"memory,omitzero"`

	// Disk is the filesystem holding the data directory. Its use is
	// reported, not enforced.
	Disk DiskUsage `json:"disk,omitzero"`

	// Instances are the instances that hold CPU and memory: those starting,
	// running or paused, in name order.
	Instances []InstanceResources `json:"instances,omitzero"`
}

Resources are how much CPU and memory instances may be given, how much they hold, and how full the data directory's disk is.

type RestartMode added in v0.4.0 

type RestartMode string

RestartMode is when an instance that ended without being asked to is started again. 

const (
	// RestartModeNo leaves the instance as it ended.
	RestartModeNo RestartMode = "no"

	// RestartModeOnFailure restarts it unless it ended cleanly, by its
	// workload exiting 0 or its guest powering off.
	RestartModeOnFailure RestartMode = "on-failure"

	// RestartModeUnlessStopped restarts it however it ended, and starts it
	// when the daemon starts, unless a user stopped it.
	RestartModeUnlessStopped RestartMode = "unless-stopped"

	// RestartModeAlways restarts it however it ended, and starts it when the
	// daemon starts, even if a user stopped it.
	RestartModeAlways RestartMode = "always"
)

The restart modes.

type RestartPolicy added in v0.4.0 

type RestartPolicy struct {
	// Mode is when the instance is started again. Empty means no.
	Mode RestartMode `json:"mode,omitzero"`

	// MaxRetries is, for on-failure, how many restarts in a row are made
	// before the instance is left Failed. Zero means no limit.
	MaxRetries int `json:"max_retries,omitzero"`
}

RestartPolicy is what the daemon does when an instance ends without being asked to: when its workload exits, its guest resets or its hypervisor dies. Restarts back off exponentially, from a second up to five minutes; an instance that stays up for ten minutes starts the count again.

type Scope added in v0.4.0 

type Scope string

Scope is what a token allows: ScopeAll, or an action on a kind of resource, written RESOURCE:ACTION. A read scope allows the calls that only look at its resource. A write scope also allows those that change it. A token may make, rotate and delete only tokens whose scopes its own allow. 

const (
	ScopeInstancesRead  Scope = "instances:read"
	ScopeInstancesWrite Scope = "instances:write"
	ScopeSnapshotsRead  Scope = "snapshots:read"
	ScopeSnapshotsWrite Scope = "snapshots:write"
	ScopeNetworksRead   Scope = "networks:read"
	ScopeNetworksWrite  Scope = "networks:write"
	ScopeVolumesRead    Scope = "volumes:read"
	ScopeVolumesWrite   Scope = "volumes:write"
	ScopeImagesRead     Scope = "images:read"
	ScopeImagesWrite    Scope = "images:write"
	ScopeKernelsRead    Scope = "kernels:read"
	ScopeKernelsWrite   Scope = "kernels:write"
	ScopeTokensRead     Scope = "tokens:read"
	ScopeTokensWrite    Scope = "tokens:write"
	ScopeEventsRead     Scope = "events:read"
)

The scopes of each kind of resource. Events, the log of what happens to every other resource, can only be read. 

const ScopeAll Scope = "*"

ScopeAll allows everything, now and as the API grows.

type Snapshot added in v0.4.0 

type Snapshot struct {
	// ID is the snapshot's ID.
	ID string `json:"id,omitzero"`

	// Name is the snapshot's name.
	Name string `json:"name,omitzero"`

	// Kind is what the snapshot holds: the guest's memory and disks, or its
	// disks alone.
	Kind SnapshotKind `json:"kind,omitzero"`

	// InstanceID is the ID of the instance the snapshot was taken of.
	InstanceID string `json:"instance_id,omitzero"`

	// InstanceName is that instance's name now, or, if it has been deleted,
	// its name then.
	InstanceName string `json:"instance_name,omitzero"`

	// HypervisorType is the hypervisor that took a memory snapshot. It is
	// empty for a disk snapshot.
	HypervisorType HypervisorType `json:"hypervisor_type,omitzero"`

	// HypervisorVersion is the version of the hypervisor that took a memory
	// snapshot. Only the same version can restore it. It is empty for a disk
	// snapshot.
	HypervisorVersion string `json:"hypervisor_version,omitzero"`

	// VCPUs is how many vCPUs a memory snapshot's guest had. It is zero for a
	// disk snapshot.
	VCPUs int `json:"vcpus,omitzero"`

	// MemoryBytes is how much memory a memory snapshot's guest had. It is
	// zero for a disk snapshot.
	MemoryBytes int64 `json:"memory_bytes,omitzero"`

	// SizeBytes is what the snapshot occupies on disk, which on a
	// copy-on-write filesystem may be far less than the guest's memory and
	// disk together.
	SizeBytes int64 `json:"size_bytes,omitzero"`

	// CreateTime is when the snapshot was taken.
	CreateTime time.Time `json:"create_time,omitzero"`
}

Snapshot is an instance frozen to disk. It outlives the instance it was taken of, and never holds the instance's volumes.

type SnapshotKind added in v0.4.0 

type SnapshotKind string

SnapshotKind is what a snapshot holds. 

const (
	// SnapshotKindMemory is a running or paused guest's memory and device
	// state, with its overlay disk as it was at the same moment. Restoring
	// it resumes the guest.
	SnapshotKindMemory SnapshotKind = "memory"

	// SnapshotKindDisk is a stopped instance's overlay disk alone. Restoring
	// it rolls the disk back, and the guest boots from it afresh.
	SnapshotKindDisk SnapshotKind = "disk"
)

The snapshot kinds.

type Snapshots added in v0.4.0 

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

Snapshots are the calls about snapshots, reached as Client.Snapshots. A call that takes a snapshot's name takes its ID as well.

func (*Snapshots) Create added in v0.4.0 

func (s *Snapshots) Create(ctx context.Context, instance, name string) (Snapshot, error)

Create freezes an instance to disk. Of a running or paused instance it takes a memory snapshot, pausing a running one for as long as it takes. Of a stopped one it takes a disk snapshot. An empty name is the instance's and the time's, as in web-20260102t150405z.

func (*Snapshots) Delete added in v0.4.0 

func (s *Snapshots) Delete(ctx context.Context, name string) error

Delete removes a snapshot.

func (*Snapshots) Fork added in v0.4.0 

func (s *Snapshots) Fork(ctx context.Context, name string, opts ForkOptions) (Instance, error)

Fork creates an instance as a copy of the one a snapshot was taken of, with its definition but the identity opts gives it. A memory snapshot's fork runs, resumed where the snapshot's guest was; a disk snapshot's fork is stopped. A fork that fails leaves no instance behind.

func (*Snapshots) Get added in v0.4.0 

func (s *Snapshots) Get(ctx context.Context, name string) (Snapshot, error)

Get returns one snapshot, or ErrNotFound.

func (*Snapshots) List added in v0.4.0 

func (s *Snapshots) List(ctx context.Context, instance string) ([]Snapshot, error)

List returns the snapshots taken of an instance, oldest first, or every snapshot if instance is empty.

func (*Snapshots) Restore added in v0.4.0 

func (s *Snapshots) Restore(ctx context.Context, name string) (Instance, error)

Restore puts the instance a snapshot was taken of, which must be stopped, back as it was then, discarding what it has written to its disk since. A memory snapshot resumes the guest where it was; a disk snapshot leaves the instance stopped.

type TCPProbe added in v0.4.0 

type TCPProbe struct {
	// Port is the guest port connected to.
	Port int `json:"port,omitzero"`
}

TCPProbe checks health by opening a connection to the guest's loopback address, which is healthy if it is accepted.

type Token added in v0.4.0 

type Token struct {
	// ID is the token's ID.
	ID string `json:"id,omitzero"`

	TokenSpec

	// CreateTime is when the token was made.
	CreateTime time.Time `json:"create_time,omitzero"`

	// UpdateTime is when the token was last rotated, or made if it has not
	// been.
	UpdateTime time.Time `json:"update_time,omitzero"`

	// LastUseTime is when the token last made a call, to the minute. It is
	// zero if the token never has.
	LastUseTime time.Time `json:"last_use_time,omitzero"`
}

Token is a credential a client presents to a daemon's TCP listener, as WithToken takes it. Its value is returned only when the token is created or rotated: the daemon keeps only the SHA-256 of its secret.

type TokenSpec added in v0.4.0 

type TokenSpec struct {
	// Name is the token's name.
	Name string `json:"name,omitzero"`

	// Scopes are what the token allows. Empty is ScopeAll. A call the
	// token's scopes do not allow fails with ErrPermissionDenied.
	Scopes []Scope `json:"scopes,omitzero"`

	// Secret is the token's secret: at least 32 letters and digits. Empty has
	// the daemon make one, which is what you want unless a tool must know the
	// secret before the token exists. It is never returned.
	Secret string `json:"-"`
}

TokenSpec is what a token is.

type Tokens added in v0.4.0 

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

Tokens are the calls about the tokens a daemon's TCP listener accepts, reached as Client.Tokens.

func (*Tokens) Create added in v0.4.0 

func (s *Tokens) Create(ctx context.Context, spec TokenSpec) (IssuedToken, error)

Create makes a token, and returns it with its value, which is never returned again. It fails with ErrFailedPrecondition if the daemon is not served over TCP.

func (*Tokens) Delete added in v0.4.0 

func (s *Tokens) Delete(ctx context.Context, name string) error

Delete removes a token. A client using it is refused from its next call.

func (*Tokens) Get added in v0.4.0 

func (s *Tokens) Get(ctx context.Context, name string) (Token, error)

Get returns one token, without its value, or ErrNotFound.

func (*Tokens) List added in v0.4.0 

func (s *Tokens) List(ctx context.Context) ([]Token, error)

List returns every token, without their values.

func (*Tokens) Rotate added in v0.4.0 

func (s *Tokens) Rotate(ctx context.Context, name, secret string) (IssuedToken, error)

Rotate gives a token a new secret, which the daemon makes if secret is empty, and returns its new value. The old value stops working at once.

type Volume added in v0.4.0 

type Volume struct {
	// ID is the volume's ID.
	ID string `json:"id,omitzero"`

	// Name is the volume's name, which a mount gives as its Source.
	Name string `json:"name,omitzero"`

	// SizeBytes is the volume's size.
	SizeBytes int64 `json:"size_bytes,omitzero"`

	// CreateTime is when the volume was created.
	CreateTime time.Time `json:"create_time,omitzero"`

	// UpdateTime is when the volume was last changed.
	UpdateTime time.Time `json:"update_time,omitzero"`
}

Volume is a persistent block device that outlives the instances using it.

type Volumes added in v0.4.0 

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

Volumes are the calls about volumes, reached as Client.Volumes.

func (*Volumes) Create added in v0.4.0 

func (s *Volumes) Create(ctx context.Context, name string, sizeBytes int64) (Volume, error)

Create provisions a volume of sizeBytes.

func (*Volumes) Delete added in v0.4.0 

func (s *Volumes) Delete(ctx context.Context, name string) error

Delete removes a volume that no instance references.

func (*Volumes) Get added in v0.4.0 

func (s *Volumes) Get(ctx context.Context, name string) (Volume, error)

Get returns one volume, or ErrNotFound.

func (*Volumes) List added in v0.4.0 

func (s *Volumes) List(ctx context.Context) ([]Volume, error)

List returns every volume.

type WaitCondition added in v0.4.0 

type WaitCondition string

WaitCondition is what a wait waits for an instance to do. 

const (
	// WaitConditionStopped waits for the instance to stop.
	WaitConditionStopped WaitCondition = "stopped"

	// WaitConditionHealthy waits for the running instance's health check to
	// pass. The wait ends at once if the check has passed already. It goes on
	// while the instance is unhealthy, because a later probe or a restart can
	// make it healthy. It fails with ErrFailedPrecondition if the instance has
	// no health check, is not running, or stops first.
	WaitConditionHealthy WaitCondition = "healthy"
)

The wait conditions.

type WaitOptions added in v0.4.0 

type WaitOptions struct {
	// ID, if set, is the instance to wait for, which tells it apart from a
	// later one given the same name. Empty means whichever instance has the
	// name.
	ID string

	// Condition is what to wait for. Empty means WaitConditionStopped.
	Condition WaitCondition

	// NextStop waits for the instance's next stop, even if it is stopped
	// now: for a caller about to start it, with Instances.Waiter.
	NextStop bool
}

WaitOptions say which instance a wait is for, and what it waits for.

type Waiter added in v0.4.0 

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

Waiter is a wait for an instance that the daemon has begun. See Instances.Waiter.

func (*Waiter) Close added in v0.4.0 

func (w *Waiter) Close() error

Close ends the wait.

func (*Waiter) Wait added in v0.4.0 

func (w *Waiter) Wait() (int, error)

Wait returns the status the instance's guest ended with: its workload's exit code, 0 for a guest that powered itself off or was stopped, or UnknownExitCode for one that failed without saying how. An instance its restart policy starts again has not stopped, so the wait goes on. A wait for WaitConditionHealthy returns 0 once the instance is healthy.

Source Files

View all Source files

Directories

Path Synopsis
cmd
dicer command
Command dicer is the command-line client for dicerd.
 Command dicer is the command-line client for dicerd.
dicer-agent command
Command dicer-agent serves the host's exec, copy, probe, process listing and shutdown requests inside a Dicer guest.
 Command dicer-agent serves the host's exec, copy, probe, process listing and shutdown requests inside a Dicer guest.
dicer-init command
Command dicer-init runs as PID 1 inside a Dicer guest.
 Command dicer-init runs as PID 1 inside a Dicer guest.
dicerd command
Command dicerd is the Dicer host daemon.
 Command dicerd is the Dicer host daemon.
internal
archive
Package archive packs one file or directory as a tar stream and unpacks it with cp's placement rules:
 Package archive packs one file or directory as a tar stream and unpacks it with cp's placement rules:
atomicfile
Package atomicfile writes files so that a crash cannot leave a partial one in place of a good one.
 Package atomicfile writes files so that a crash cannot leave a partial one in place of a good one.
cli
Package cli implements the dicer command-line client.
 Package cli implements the dicer command-line client.
cli/printer
Package printer renders a Printable as a table, JSON, YAML or a Go template.
 Package printer renders a Printable as a table, JSON, YAML or a Go template.
cli/remote
Package remote is the daemons the CLI knows, kept with the current one in ~/.config/dicer/remotes.yaml, and how each is reached.
 Package remote is the daemons the CLI knows, kept with the current one in ~/.config/dicer/remotes.yaml, and how each is reached.
compose
Package compose reads compose files: a project's instances, networks and volumes, described together in YAML as Docker Compose describes containers, and turned into the definitions the client creates them from.
 Package compose reads compose files: a project's instances, networks and volumes, described together in YAML as Docker Compose describes containers, and turned into the definitions the client creates them from.
daemon
Package daemon assembles and runs dicerd: it loads the configuration, wires the services together and manages the process lifecycle.
 Package daemon assembles and runs dicerd: it loads the configuration, wires the services together and manages the process lifecycle.
defaults
Package defaults is where Dicer lives on a host unless configured otherwise: the locations more than one of its packages or programs must agree on, such as the socket the daemon serves on and a client looks at.
 Package defaults is where Dicer lives on a host unless configured otherwise: the locations more than one of its packages or programs must agree on, such as the socket the daemon serves on and a client looks at.
diskfile
Package diskfile makes, grows, copies and measures disk files: the sparse files that hold a guest's disks on the host.
 Package diskfile makes, grows, copies and measures disk files: the sparse files that hold a guest's disks on the host.
dns
Package dns answers the DNS queries of a network's guests, so that an instance can reach another by name.
 Package dns answers the DNS queries of a network's guests, so that an instance can reach another by name.
doctor
Package doctor checks that a host can run Dicer's instances and that they can be reached.
 Package doctor checks that a host can run Dicer's instances and that they can be reached.
errdefs
Package errdefs defines the classes of error the daemon's code returns, matched with errors.Is.
 Package errdefs defines the classes of error the daemon's code returns, matched with errors.Is.
event
Package event defines the events recorded about what happens on this host, keeps their log, and delivers new ones to subscribers.
 Package event defines the events recorded about what happens on this host, keeps their log, and delivers new ones to subscribers.
filestore
Package filestore stores the instance, snapshot, network, volume, kernel and token definitions as YAML files, cached in memory and written through:
 Package filestore stores the instance, snapshot, network, volume, kernel and token definitions as YAML files, cached in memory and written through:
grpcserver
Package grpcserver implements the DaemonService gRPC service and the interceptors in front of it: those that authenticate a call's token, authorize it by the token's scopes, and audit it.
 Package grpcserver implements the DaemonService gRPC service and the interceptors in front of it: those that authenticate a call's token, authorize it by the token's scopes, and audit it.
guest
Package guest defines the contract between the host and a guest: the Config written to the config disk, the Status read from the status disk, the agent's port, how a guest's workload and probes are reported, and who a process in the guest runs as.
 Package guest defines the contract between the host and a guest: the Config written to the config disk, the Status read from the status disk, the agent's port, how a guest's workload and probes are reported, and who a process in the guest runs as.
guest/agent
Package agent runs inside the guest and serves the host's exec, copy, probe, process listing, shutdown, clock, identity and info requests over vsock.
 Package agent runs inside the guest and serves the host's exec, copy, probe, process listing, shutdown, clock, identity and info requests over vsock.
guest/agentclient
Package agentclient is the host's end of the guest agent: it reaches dicer-agent through the vsock socket of the guest's VMM and makes its requests.
 Package agentclient is the host's end of the guest agent: it reaches dicer-agent through the vsock socket of the guest's VMM and makes its requests.
guest/boot
Package boot is the guest's PID 1.
 Package boot is the guest's PID 1.
health
Package health checks an instance's health.
 Package health checks an instance's health.
hostfs
Package hostfs finds the host's files from the daemon, whose view of the filesystem may not be the host's: systemd's PrivateTmp gives it a /tmp of its own, in a mount namespace of its own.
 Package hostfs finds the host's files from the daemon, whose view of the filesystem may not be the host's: systemd's PrivateTmp gives it a /tmp of its own, in a mount namespace of its own.
hostinfo
Package hostinfo reports the physical resources of the machine the daemon runs on, read from /proc.
 Package hostinfo reports the physical resources of the machine the daemon runs on, read from /proc.
hostnet
Package hostnet configures the host networking a VM needs: bridges, TAP devices, iptables rules for NAT, isolation and published ports, the bridges' places in firewalld, and bandwidth limits.
 Package hostnet configures the host networking a VM needs: bridges, TAP devices, iptables rules for NAT, isolation and published ports, the bridges' places in firewalld, and bandwidth limits.
humanize
Package humanize writes sizes, numbers, durations and counts for people, so that every one Dicer prints reads the same: in a table, a message or an event.
 Package humanize writes sizes, numbers, durations and counts for people, so that every one Dicer prints reads the same: in a table, a message or an event.
hypervisor
Package hypervisor defines the VM specification and the operations a virtual machine monitor must support.
 Package hypervisor defines the VM specification and the operations a virtual machine monitor must support.
hypervisor/cloudhypervisor
Package cloudhypervisor provides primitives to interact with the openapi HTTP API.
 Package cloudhypervisor provides primitives to interact with the openapi HTTP API.
hypervisor/firecracker
Package firecracker implements the hypervisor interfaces with Firecracker.
 Package firecracker implements the hypervisor interfaces with Firecracker.
image
Package image pulls container images and converts them into read-only EROFS disks a guest boots from.
 Package image pulls container images and converts them into read-only EROFS disks a guest boots from.
image/reference
Package reference parses OCI image references and resolves tags to digests.
 Package reference parses OCI image references and resolves tags to digests.
initrd
Package initrd builds the initramfs a guest boots from, carrying dicer-init and dicer-agent.
 Package initrd builds the initramfs a guest boots from, carrying dicer-init and dicer-agent.
instance
Package instance runs instances as virtual machines and manages their lifecycle: it starts, stops, pauses and deletes them, puts them on standby, and snapshots and forks them.
 Package instance runs instances as virtual machines and manages their lifecycle: it starts, stops, pauses and deletes them, puts them on standby, and snapshots and forks them.
kernel
Package kernel manages guest kernels: their definitions, and their binaries on the host.
 Package kernel manages guest kernels: their definitions, and their binaries on the host.
metric
Package metric serves the daemon's Prometheus metrics, and is how the rest of the daemon defines its own.
 Package metric serves the daemon's Prometheus metrics, and is how the rest of the daemon defines its own.
metric/metrictest
Package metrictest tests the collectors packages serve their metrics with.
 Package metrictest tests the collectors packages serve their metrics with.
naming
Package naming is the rule every name Dicer gives a resource follows: an instance's, a network's, a snapshot's, a remote's; and a guest's hostname, which follows the same rule.
 Package naming is the rule every name Dicer gives a resource follows: an instance's, a network's, a snapshot's, a remote's; and a guest's hostname, which follows the same rule.
network
Package network defines host-local networks and attaches instances to them, assigning their addresses and naming their interfaces.
 Package network defines host-local networks and attaches instances to them, assigning their addresses and naming their interfaces.
process
Package process provides handles on long-lived processes such as VMMs, started or adopted, that report when the process exits.
 Package process provides handles on long-lived processes such as VMMs, started or adopted, that report when the process exits.
registry
Package registry talks to OCI registries: resolving references, pulling manifests and layers, and exporting an unpacked root filesystem.
 Package registry talks to OCI registries: resolving references, pulling manifests and layers, and exporting an unpacked root filesystem.
token
Package token makes and reads the tokens a client presents to a daemon's TCP listener, and manages the daemon's record of them.
 Package token makes and reads the tokens a client presents to a daemon's TCP listener, and manages the daemon's record of them.
version
Package version holds the build's identity, set at link time with -X.
 Package version holds the build's identity, set at link time with -X.
virtiofs
Package virtiofs shares host directories with guests: it runs virtiofsd, the virtio-fs daemon, for each, on a socket the VMM connects to.
 Package virtiofs shares host directories with guests: it runs virtiofsd, the virtio-fs daemon, for each, on a socket the VMM connects to.
volume
Package volume manages the persistent disks instances mount: their definitions, and the sparse files with a filesystem that back them, independent of any instance.
 Package volume manages the persistent disks instances mount: their definitions, and the sparse files with a filesystem that back them, independent of any instance.
proto
diceragent/v1
dicerd/v1
tools
bench command
Command bench measures Dicer on the host it runs on, for the numbers the documentation publishes and to see what a change does to them.
 Command bench measures Dicer on the host it runs on, for the numbers the documentation publishes and to see what a change does to them.
bench/harness
Package harness is what every scenario of the benchmarks shares: the daemon's client, the instances, networks and snapshots a scenario makes, which it always removes, reading the host's memory, CPU and disk, and recording what was measured.
 Package harness is what every scenario of the benchmarks shares: the daemon's client, the instances, networks and snapshots a scenario makes, which it always removes, reading the host's memory, CPU and disk, and recording what was measured.
bench/probe
Package probe is work whose speed says what a machine can do: hashing and compressing for its CPU, and reading and writing a file for its disk.
 Package probe is work whose speed says what a machine can do: hashing and compressing for its CPU, and reading and writing a file for its disk.
bench/result
Package result is what a run of the benchmarks found, as the JSON it is kept in, and the tables and comparisons made from it.
 Package result is what a run of the benchmarks found, as the JSON it is kept in, and the tables and comparisons made from it.
bench/scenario
Package scenario is the benchmarks' scenarios: each one thing to measure, such as how fast an instance boots or how many fit on the host, run with parameters a suite or the command line gives it.
 Package scenario is the benchmarks' scenarios: each one thing to measure, such as how fast an instance boots or how many fit on the host, run with parameters a suite or the command line gives it.
bench/suite
Package suite reads suites: YAML files that say which scenarios a run of the benchmarks makes, and with which parameters.
 Package suite reads suites: YAML files that say which scenarios a run of the benchmarks makes, and with which parameters.
bench/workload
Package workload is what the benchmarks' guests do: the programs they run, how to tell they are ready, and the requests sent to them.
 Package workload is what the benchmarks' guests do: the programs they run, how to tell they are ready, and the requests sent to them.
docgen command
Command docgen generates the documentation site's reference pages from the code: the command line from the commands, the configuration and the compose file from the doc comments on the types they are read into, the Go client from the doc comments of the package at the module's root, and the metrics from those the daemon registers.
 Command docgen generates the documentation site's reference pages from the code: the command line from the commands, the configuration and the compose file from the doc comments on the types they are read into, the Go client from the doc comments of the package at the module's root, and the metrics from those the daemon registers.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.