Documentation
¶
Overview ¶
Package docker provides a providersdk.Driver backed by the local docker CLI.
Package docker provides a providersdk.Driver backed by the Docker Engine API.
Index ¶
- Constants
- func Registration() providersdk.Registration
- type Config
- type CreateConfig
- type Driver
- func (d *Driver) AddMeshPeer(ctx context.Context, ref providersdk.SegmentRef, ...) error
- func (d *Driver) Allocate(ctx context.Context, id string) (map[string]any, error)
- func (d *Driver) AttachToSegment(ctx context.Context, providerResourceID string, ref providersdk.SegmentRef) error
- func (d *Driver) Availability(ctx context.Context) (*providersdk.ResourceAvailability, error)
- func (d *Driver) Create(ctx context.Context, cfg any) (*providersdk.Resource, error)
- func (d *Driver) CreateSegment(ctx context.Context, sandboxID string, cidr string) (providersdk.SegmentRef, string, error)
- func (d *Driver) Delete(ctx context.Context, id string) error
- func (d *Driver) DestroySegment(ctx context.Context, ref providersdk.SegmentRef) error
- func (d *Driver) DialResource(ctx context.Context, providerResourceID string, port int) (net.Conn, error)
- func (d *Driver) List(ctx context.Context) ([]providersdk.ResourceStatus, error)
- func (d *Driver) MeshIdentity(ctx context.Context, ref providersdk.SegmentRef) (string, string, string, error)
- func (d *Driver) Read(ctx context.Context, id string) (*providersdk.ResourceStatus, error)
- func (d *Driver) RemoveMeshPeer(_ context.Context, ref providersdk.SegmentRef, peerPublicKey string) error
- func (d *Driver) Type() providersdk.Type
- func (d *Driver) Update(ctx context.Context, id string, op providersdk.Operation) (*providersdk.Result, error)
- func (d *Driver) UpdateStream(ctx context.Context, id string, op providersdk.Operation, ...) (*providersdk.Result, error)
- type ExecOp
Constants ¶
const ProviderType = "docker"
ProviderType is the registry key for Docker providers.
Variables ¶
This section is empty.
Functions ¶
func Registration ¶
func Registration() providersdk.Registration
Registration returns the providersdk.Registration for the Docker provider.
Types ¶
type Config ¶
type Config struct {
Host string `json:"host" yaml:"host"`
// MeshHost and MeshPorts declare this host's mesh listener: the address
// peers dial and the UDP port range ("51820-51919") its mesh interfaces
// listen on, one port per multi-host sandbox. See hyperv.Config.MeshHost
// for why this is explicit rather than detected. Set both or neither.
MeshHost string `json:"mesh_host,omitempty" yaml:"mesh_host,omitempty"`
MeshPorts string `json:"mesh_ports,omitempty" yaml:"mesh_ports,omitempty"`
}
Config holds connection settings for a Docker daemon. This is the provider-level config from boxy.yaml providers[].config.
type CreateConfig ¶
type CreateConfig struct {
Image string `json:"image" yaml:"image"`
// Source is intentionally unsupported: Docker consumes image references,
// not raw disk/source bytes. The field exists so JSON decoding can produce
// an explicit incompatibility error instead of silently ignoring a source.
Source *providersdk.SourceDescriptor `json:"source,omitempty" yaml:"source,omitempty"`
Command []any `json:"command" yaml:"command"`
Env map[string]string `json:"env" yaml:"env"`
Labels map[string]string `json:"labels" yaml:"labels"`
Ports []string `json:"ports" yaml:"ports"`
// Resources
CPU string `json:"cpu" yaml:"cpu"`
Memory string `json:"memory" yaml:"memory"`
}
CreateConfig holds pool-level config for creating a container. This is the pool-level config from boxy.yaml pools[].config.
type Driver ¶
type Driver struct {
// contains filtered or unexported fields
}
Driver implements providersdk.Driver using the Docker Engine API.
func (*Driver) AddMeshPeer ¶ added in v0.1.68
func (d *Driver) AddMeshPeer(ctx context.Context, ref providersdk.SegmentRef, peerPublicKey, peerEndpoint, peerCIDR string) error
AddMeshPeer satisfies providersdk.MeshPeerer. The segment's mesh interface must already exist (created by a prior MeshIdentity call).
func (*Driver) AttachToSegment ¶ added in v0.1.68
func (d *Driver) AttachToSegment(ctx context.Context, providerResourceID string, ref providersdk.SegmentRef) error
AttachToSegment moves an already-running container onto the sandbox's network: it connects the container to the segment and then disconnects it from every other network it was on. The disconnect half is what actually delivers the isolation -- Driver.Create attaches new containers to the daemon's default bridge, so connecting alone would leave the container multi-homed on both the shared bridge and the sandbox's private network, reachable from (and able to reach) every other container on that host.
Connect runs before disconnect, deliberately: the reverse order would leave the container with no network at all if the connect then failed.
No EndpointSettings are specified -- Docker assigns an address from the network's own auto-assigned subnet.
Idempotent, as the interface requires: a container already on the target network skips the connect (which the daemon would reject as a conflict) and still runs the disconnect sweep, so a retry after a partial attach converges on the same end state.
func (*Driver) Availability ¶ added in v0.1.59
func (d *Driver) Availability(ctx context.Context) (*providersdk.ResourceAvailability, error)
Availability reports Docker Engine host memory as a capacity estimate. Docker's Info endpoint exposes total host memory, not reliably free memory, so callers must not use this sample as an allocation rejection signal.
func (*Driver) CreateSegment ¶ added in v0.1.68
func (d *Driver) CreateSegment(ctx context.Context, sandboxID string, cidr string) (providersdk.SegmentRef, string, error)
CreateSegment creates a dedicated bridge network for one sandbox, on the caller-allocated cidr.
The subnet is set explicitly rather than left to the daemon's auto-IPAM. Auto-IPAM picks a non-overlapping subnet on *this* host, which is exactly wrong for cross-host mesh peering: two daemons allocating from the same default pool in the same order hand out the same range, and each host then routes traffic for the peer's segment locally instead of into the tunnel (#370). Only the caller, which sees every host, can pick a range that is unique across all of them. (WireGuard's "disallowed source address" drop came from Docker's masquerading instead; see meshFirewallRule.)
Giving up auto-IPAM means giving up its host-local collision avoidance, so the proposed range is checked against what this host already has first, and refused with a *providersdk.CIDRConflictError if it is unusable. The caller then proposes a different one.
Idempotent per sandbox ID, as the interface requires: the deterministic network name is resolved first, and an existing network's ID is returned unchanged rather than issuing a second NetworkCreate. Without that check a retry would either fail on the duplicate name or leave a second, orphaned network behind that nothing ever tears down. cidr is ignored on that path -- the existing network's own subnet is authoritative, and renumbering a live network out from under its containers would be worse than honoring a stale proposal.
func (*Driver) DestroySegment ¶ added in v0.1.68
func (d *Driver) DestroySegment(ctx context.Context, ref providersdk.SegmentRef) error
DestroySegment removes the network created by CreateSegment, along with the mesh firewall rules MeshIdentity added for it. Idempotent for an already-gone network, matching Driver.Delete's contract.
The rules are only looked for when mesh is configured, the only way MeshIdentity can have added them. They're removed by tag, so a segment whose mesh interface was lost with an earlier agent process is still cleaned up.
func (*Driver) DialResource ¶ added in v0.1.70
func (d *Driver) DialResource(ctx context.Context, providerResourceID string, port int) (net.Conn, error)
DialResource satisfies providersdk.ResourceDialer. It dials the container's address on its sandbox network, or on its first network by name when it has none. This needs the agent on the Linux Docker host itself: a Docker Desktop host can't route to container addresses.
func (*Driver) List ¶ added in v0.1.29
func (d *Driver) List(ctx context.Context) ([]providersdk.ResourceStatus, error)
List returns every container this driver created, identified by managedLabel. It satisfies providersdk.ResourceLister.
func (*Driver) MeshIdentity ¶ added in v0.1.68
func (d *Driver) MeshIdentity(ctx context.Context, ref providersdk.SegmentRef) (string, string, string, error)
MeshIdentity satisfies providersdk.MeshPeerer. Unlike Hyper-V (which tracks its own segment CIDR in a ledger, since it chose the subnet itself), this driver lets Docker auto-assign the subnet at CreateSegment time (Plan 1a) -- so discovering it means asking Docker directly via NetworkInspect.
func (*Driver) Read ¶
func (d *Driver) Read(ctx context.Context, id string) (*providersdk.ResourceStatus, error)
func (*Driver) RemoveMeshPeer ¶ added in v0.1.68
func (d *Driver) RemoveMeshPeer(_ context.Context, ref providersdk.SegmentRef, peerPublicKey string) error
RemoveMeshPeer satisfies providersdk.MeshPeerer.
Known gap, not fixed here: this does not remove the kernel route AddMeshPeer added for the departing peer's subnet -- the MeshPeerer interface passes only peerPublicKey, not the CIDR that route needs. For a two-host mesh this is harmless (DestroySegment closes the whole interface when the sandbox goes away, taking every route on it with it), but a mesh spanning three or more hosts that removes exactly one peer while keeping the interface up for the others would leave a stale route silently blackholing traffic to the removed peer instead of failing fast. Revisit if/when a mesh larger than two hosts is actually exercised.
func (*Driver) Type ¶
func (d *Driver) Type() providersdk.Type
func (*Driver) Update ¶
func (d *Driver) Update(ctx context.Context, id string, op providersdk.Operation) (*providersdk.Result, error)
func (*Driver) UpdateStream ¶ added in v0.1.34
func (d *Driver) UpdateStream(ctx context.Context, id string, op providersdk.Operation, sink eventstream.Sink) (*providersdk.Result, error)
type ExecOp ¶
type ExecOp = providersdk.ExecOperation
ExecOp is retained as a provider-specific spelling of the shared command operation for compatibility with existing callers.
Source Files