Documentation
¶
Overview ¶
Package engine is mutti's narrow view of the Docker Engine API. Everything mutti reads or writes directly on the daemon goes through Engine, so tests can swap in the in-memory fake from enginetest.
Index ¶
- Constants
- Variables
- func IsUnavailable(err error) bool
- type Container
- type ContainerDetails
- type ContainerSpec
- type Engine
- type Event
- type Info
- type Moby
- func (m *Moby) Close() error
- func (m *Moby) ConnectNetwork(ctx context.Context, network, container string, aliases []string) error
- func (m *Moby) CopyToContainer(ctx context.Context, id string, files map[string][]byte) error
- func (m *Moby) CreateContainer(ctx context.Context, spec ContainerSpec) (string, error)
- func (m *Moby) CreateNetwork(ctx context.Context, name string, labels map[string]string) (Network, error)
- func (m *Moby) CreateVolume(ctx context.Context, name string, labels map[string]string) (Volume, error)
- func (m *Moby) DaemonHost() string
- func (m *Moby) DisconnectNetwork(ctx context.Context, network, container string) error
- func (m *Moby) Events(ctx context.Context, labelFilters ...string) (<-chan Event, <-chan error)
- func (m *Moby) ImageExists(ctx context.Context, ref string) (bool, error)
- func (m *Moby) Info(ctx context.Context) (Info, error)
- func (m *Moby) InspectContainer(ctx context.Context, id string) (ContainerDetails, bool, error)
- func (m *Moby) InspectVolume(ctx context.Context, name string) (Volume, bool, error)
- func (m *Moby) ListContainers(ctx context.Context, labelFilters ...string) ([]Container, error)
- func (m *Moby) ListNetworks(ctx context.Context, labelFilters ...string) ([]Network, error)
- func (m *Moby) ListVolumes(ctx context.Context, labelFilters ...string) ([]Volume, error)
- func (m *Moby) NetworkContainers(ctx context.Context, network string) ([]string, error)
- func (m *Moby) PauseContainer(ctx context.Context, id string) error
- func (m *Moby) PullImage(ctx context.Context, ref string) error
- func (m *Moby) RemoveContainer(ctx context.Context, id string) error
- func (m *Moby) RemoveNetwork(ctx context.Context, id string) error
- func (m *Moby) RemoveVolume(ctx context.Context, name string) error
- func (m *Moby) RunContainer(ctx context.Context, spec ContainerSpec) (int, error)
- func (m *Moby) StartContainer(ctx context.Context, id string) error
- func (m *Moby) UnpauseContainer(ctx context.Context, id string) error
- type Mount
- type Network
- type Port
- type Volume
Constants ¶
const ( LabelSchema = "mutti.schema" // label schema version, for later migrations LabelInstance = "mutti.instance" // instance name (= Compose project name) LabelProject = "mutti.project" // project name LabelID = "mutti.id" // identity id of the owning worktree LabelPath = "mutti.path" // worktree path when the label was written (informational) LabelGitDir = "mutti.gitdir" // per-worktree git admin dir, empty outside git LabelRole = "mutti.role" // what a mutti-made resource is for, e.g. "claim" // LabelComposeProject is set by Compose on everything it creates. LabelComposeProject = "com.docker.compose.project" // LabelComposeService is set by Compose on containers. LabelComposeService = "com.docker.compose.service" SchemaVersion = "1" )
Label keys mutti sets on resources it creates itself.
const PoolsExhaustedMessage = "all predefined address pools have been fully subnetted"
PoolsExhaustedMessage is how Docker reports ErrAddressPoolsExhausted.
Variables ¶
var ErrAddressPoolsExhausted = errors.New("docker has no address pool left for a new network")
ErrAddressPoolsExhausted means Docker has no subnet left for a new network.
var ErrConflict = errors.New("already exists")
ErrConflict means a resource with that name already exists.
ErrUnavailable means the Docker daemon cannot be reached.
Functions ¶
func IsUnavailable ¶
IsUnavailable reports whether err means the daemon could not be reached.
Types ¶
type Container ¶
type Container struct {
ID string
Name string
State string // created, running, paused, restarting, removing, exited, dead
Status string // human readable, e.g. "Up 3 minutes (healthy)"
Labels map[string]string
Ports []Port
// Networks are the names of the networks the container is attached to.
Networks []string
}
type ContainerDetails ¶
type ContainerDetails struct {
ID string
Name string
State string
Labels map[string]string
Networks map[string][]string // network name -> extra DNS aliases
IPs map[string]string // network name -> IP address
Mounts []Mount // Source is the path on the daemon's host
}
ContainerDetails are the inspected parts of a container.
type ContainerSpec ¶
type ContainerSpec struct {
Name string
Image string
Cmd []string
Labels map[string]string
Ports []Port // HostIP + HostPort published to ContainerPort
Mounts []Mount // bind mounts
Restart string // restart policy, e.g. "unless-stopped"
// Networks the container joins at creation, instead of the default bridge.
Networks []string `json:",omitempty"`
// Env are environment variables, KEY=value.
Env []string `json:",omitempty"`
// AutoRemove removes the container once it stops.
AutoRemove bool `json:",omitempty"`
}
ContainerSpec describes a container mutti creates itself (the router).
type Engine ¶
type Engine interface {
Info(ctx context.Context) (Info, error)
// CreateVolume creates a volume or returns the existing one with that name unchanged.
CreateVolume(ctx context.Context, name string, labels map[string]string) (Volume, error)
InspectVolume(ctx context.Context, name string) (vol Volume, ok bool, err error)
ListVolumes(ctx context.Context, labelFilters ...string) ([]Volume, error)
// RemoveVolume removes a volume. A missing volume is not an error; one a container uses is
// ErrConflict.
RemoveVolume(ctx context.Context, name string) error
// ListContainers lists containers in any state.
ListContainers(ctx context.Context, labelFilters ...string) ([]Container, error)
// RemoveContainer force-removes a container with its anonymous volumes. A missing container
// is not an error.
RemoveContainer(ctx context.Context, id string) error
ListNetworks(ctx context.Context, labelFilters ...string) ([]Network, error)
// RemoveNetwork removes a network. A missing network is not an error.
RemoveNetwork(ctx context.Context, id string) error
// CreateNetwork creates a bridge network or returns the existing one with that name.
CreateNetwork(ctx context.Context, name string, labels map[string]string) (Network, error)
// ConnectNetwork attaches a container to a network under extra DNS aliases.
ConnectNetwork(ctx context.Context, network, container string, aliases []string) error
// DisconnectNetwork detaches a container. Not being attached is not an error.
DisconnectNetwork(ctx context.Context, network, container string) error
// ImageExists reports whether an image is present locally.
ImageExists(ctx context.Context, ref string) (bool, error)
// PullImage pulls an image and waits until it is complete.
PullImage(ctx context.Context, ref string) error
// CreateContainer creates a container; a taken name returns ErrConflict.
CreateContainer(ctx context.Context, spec ContainerSpec) (id string, err error)
StartContainer(ctx context.Context, id string) error
// InspectContainer returns details of a container by id or name; ok is false if missing.
InspectContainer(ctx context.Context, id string) (c ContainerDetails, ok bool, err error)
// RunContainer runs a one-off container to completion, removes it and returns its exit code.
RunContainer(ctx context.Context, spec ContainerSpec) (exitCode int, err error)
// Events streams what happens to containers matching labelFilters until ctx ends. A failing
// stream sends one error and ends; the event channel closes either way, and has to be read
// until it does.
Events(ctx context.Context, labelFilters ...string) (<-chan Event, <-chan error)
PauseContainer(ctx context.Context, id string) error
UnpauseContainer(ctx context.Context, id string) error
// CopyToContainer writes files (absolute path -> content) into a container, creating parent
// directories; it works on created and running containers.
CopyToContainer(ctx context.Context, id string, files map[string][]byte) error
// NetworkContainers returns the ids of the containers attached to a network.
NetworkContainers(ctx context.Context, network string) ([]string, error)
}
Engine is the subset of the Docker Engine API mutti uses. Filters are label filters in Docker syntax: "key" or "key=value", all of which must match.
type Event ¶
type Event struct {
Time time.Time
Action string // as Docker names it: create, start, die, destroy, pause, unpause, "health_status: healthy", ...
ID string
Name string
// Attributes are the container's labels plus what Docker adds, such as exitCode on die.
Attributes map[string]string
}
Container is a container summary. Event is something that happened to a container.
type Info ¶
type Info struct {
ServerVersion string
APIVersion string
OS string // e.g. "Arch Linux", "Docker Desktop"
Rootless bool
Host string // daemon address, e.g. unix:///var/run/docker.sock
}
Info describes the daemon.
type Moby ¶
type Moby struct {
// contains filtered or unexported fields
}
Moby implements Engine with the official Docker client.
func Connect ¶
Connect opens a client for the daemon the docker CLI would talk to: $DOCKER_HOST if set, else the endpoint of the current docker context.
func (*Moby) ConnectNetwork ¶
func (*Moby) CopyToContainer ¶
func (*Moby) CreateContainer ¶
func (*Moby) CreateNetwork ¶
func (*Moby) CreateVolume ¶
func (*Moby) DaemonHost ¶
DaemonHost is the address the client talks to, e.g. unix:///var/run/docker.sock.
func (*Moby) DisconnectNetwork ¶
func (*Moby) ImageExists ¶
func (*Moby) InspectContainer ¶
func (*Moby) InspectVolume ¶
func (*Moby) ListContainers ¶
func (*Moby) ListNetworks ¶
func (*Moby) ListVolumes ¶
func (*Moby) NetworkContainers ¶
func (*Moby) RunContainer ¶
type Mount ¶
type Mount struct {
Source string // host path, or volume name with Volume
Target string // container path
ReadOnly bool
Volume bool `json:",omitempty"` // omitted when false, so it only changes a spec's hash where it is used
}
Mount is a bind mount of a host path, or a named volume.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package enginetest provides an in-memory engine.Engine and a contract suite that keeps it honest: the same suite runs against the fake and against a real daemon.
|
Package enginetest provides an in-memory engine.Engine and a contract suite that keeps it honest: the same suite runs against the fake and against a real daemon. |