docker

Documentation

Overview

Package docker provides read-only discovery of Docker volumes via the Docker daemon socket. It is used by the executor to resolve backup sources of the form "docker-volume://<volume-name>" into the actual mountpoint path on the host filesystem.

The Docker socket is mounted read-only in the agent container — this package never writes to the daemon, it only issues List and Inspect calls.

If Docker is not available on the host (socket missing or daemon not running), all methods return ErrDockerUnavailable so the executor can skip volume discovery gracefully instead of failing the entire backup job.

Index

• Variables
• type Client
  • func NewClient(socketPath string) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) InspectVolume(ctx context.Context, name string) (*VolumeInfo, error)
  • func (c *Client) ListRunningContainerVolumes(ctx context.Context) ([]RunningContainerVolumes, error)
  • func (c *Client) ListVolumes(ctx context.Context, labelFilter string) ([]VolumeInfo, error)
  • func (c *Client) Ping(ctx context.Context) error
• type RunningContainerVolumes
• type VolumeInfo

Variables

var ErrDockerUnavailable = errors.New("docker: daemon unavailable")

ErrDockerUnavailable is returned when the Docker daemon cannot be reached. Callers should treat this as a non-fatal condition when Docker support is optional for the current policy.

var ErrVolumeNotFound = errors.New("docker: volume not found")

ErrVolumeNotFound is returned when a requested volume does not exist.

Types

type Client

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

Client wraps the Docker SDK client and provides volume discovery methods. Create instances with NewClient.

func NewClient

func NewClient(socketPath string) (*Client, error)

NewClient creates a Docker Client connected to the socket at socketPath. Use the empty string to fall back to the Docker SDK default (DOCKER_HOST env var, or /var/run/docker.sock on Linux/macOS, //./pipe/docker_engine on Windows).

Returns ErrDockerUnavailable if the socket does not exist or the daemon is not responding.

func (*Client) Close

func (c *Client) Close() error

Close releases the underlying Docker client resources.

func (*Client) InspectVolume

func (c *Client) InspectVolume(ctx context.Context, name string) (*VolumeInfo, error)

InspectVolume returns the metadata of a single volume by name. Returns ErrVolumeNotFound if the volume does not exist.

func (*Client) ListRunningContainerVolumes

func (c *Client) ListRunningContainerVolumes(ctx context.Context) ([]RunningContainerVolumes, error)

ListRunningContainerVolumes returns the named-volume mountpoints used by currently running containers. It is used by the executor to determine which Docker volumes cannot be restored in-place without first stopping the container.

Only named volumes (Type == volume) are included; bind-mounts are skipped. If a volume's Source path is empty in the ContainerList response (the daemon may omit it), the path is resolved via VolumeInspect.

func (*Client) ListVolumes

func (c *Client) ListVolumes(ctx context.Context, labelFilter string) ([]VolumeInfo, error)

ListVolumes returns all Docker volumes visible to the daemon. An optional label filter can be passed to restrict results (e.g. "com.example.backup=true"). Pass an empty string for no filter.

Returns ErrDockerUnavailable if the daemon is not reachable.

func (*Client) Ping

func (c *Client) Ping(ctx context.Context) error

Ping checks that the Docker daemon is reachable. Call this at startup to detect early whether Docker is available.

type RunningContainerVolumes

type RunningContainerVolumes struct {
	// ContainerName is the human-readable name of the container (without leading slash).
	ContainerName string
	// VolumePaths are the host-side mountpoints of the named volumes used by this
	// container (e.g. /var/lib/docker/volumes/myapp_data/_data).
	VolumePaths []string
}

RunningContainerVolumes holds the volume host-paths used by a single running container.

type VolumeInfo

type VolumeInfo struct {
	// Name is the Docker volume name (e.g. "myapp_postgres_data").
	Name string
	// Mountpoint is the absolute path on the host where the volume data lives.
	// This is the path passed to restic as a backup source.
	Mountpoint string
	// Driver is the volume driver (e.g. "local", "rexray/s3").
	// Non-local drivers may not have an accessible host mountpoint.
	Driver string
	// Labels are the Docker labels attached to the volume.
	Labels map[string]string
}

VolumeInfo holds the metadata of a Docker volume relevant to backup.