arkdocker

package module
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package arkdocker backs up Docker volumes through an ark.Repository.

Engine stops the containers that use a volume, streams the volume through the repository and starts them again. NewVolumeSource and NewVolumeSink expose the same streams for callers that compose with ark.Repository directly. Client answers volume and container queries.

Index

Constants

View Source
const DefaultHelperImage = "busybox:stable"

DefaultHelperImage is the image the helper containers run. Backup and restore move data through the daemon's archive endpoint, so the image only runs the shell that empties a volume before a restore.

View Source
const SourceTypeDockerVolume ark.SourceType = "docker-volume"

SourceTypeDockerVolume is the source type of a Docker volume snapshot. The string is stored verbatim in the snapshot manifest.

Variables

This section is empty.

Functions

func NewVolumeSink

func NewVolumeSink(client *Client, volume string) ark.Sink

NewVolumeSink returns a Sink that restores into the named volume, for callers that compose with ark.Repository directly. Engine.RestoreVolume adds the container stop and restart around it.

func NewVolumeSource

func NewVolumeSource(client *Client, volume string) ark.Source

NewVolumeSource returns a Source over the named volume, for callers that compose with ark.Repository directly. Engine.BackupVolume adds the container stop and restart around it.

Types

type Client

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

Client answers volume and container queries and runs the helper containers behind the volume source and sink. Engine.Client returns the engine's.

func NewClient

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

NewClient connects to the daemon at dockerHost. Empty means DOCKER_HOST and friends, then the default socket.

func (*Client) Close

func (c *Client) Close() error

Close closes the Docker client connection.

func (*Client) ContainerExists

func (c *Client) ContainerExists(ctx context.Context, nameOrID string) (bool, error)

ContainerExists reports whether a container with the name or ID exists.

func (*Client) FindContainersUsingVolume

func (c *Client) FindContainersUsingVolume(ctx context.Context, volume string) ([]ContainerInfo, error)

FindContainersUsingVolume lists the containers, running or not, that mount the volume. arkdocker's own helper containers are left out.

func (*Client) GetContainer

func (c *Client) GetContainer(ctx context.Context, id string) (*ContainerInfo, error)

GetContainer describes one container by name or ID.

func (*Client) GetVolume

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

GetVolume returns metadata for the named volume.

func (*Client) ListContainers

func (c *Client) ListContainers(ctx context.Context, all bool) ([]ContainerInfo, error)

ListContainers lists the containers, only the running ones unless all is set. arkdocker's own helper containers are left out.

func (*Client) ListVolumes

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

ListVolumes returns all Docker volumes.

func (*Client) Ping

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

Ping verifies connectivity to the Docker daemon.

func (*Client) ServerVersion

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

ServerVersion returns the Docker daemon server version string.

func (*Client) VolumeExists

func (c *Client) VolumeExists(ctx context.Context, name string) (bool, error)

VolumeExists returns true if a volume with the given name exists.

type Config

type Config struct {
	// DockerHost overrides the Docker daemon socket address.
	// Empty string means use DOCKER_HOST env var or the default Unix socket.
	DockerHost string

	// StopTimeout is how long to wait for containers to stop gracefully,
	// and how long the restart afterwards may take. Zero means 30 seconds.
	StopTimeout time.Duration

	// SkipStop leaves the containers that use the volume running.
	SkipStop bool

	// HelperImage runs the helper containers. Empty means DefaultHelperImage.
	HelperImage string
}

Config holds Engine configuration.

type ContainerInfo

type ContainerInfo struct {
	ID             string            // Container ID
	Name           string            // Container name without the leading slash
	State          string            // running, exited, ...
	Status         string            // Human readable status
	Image          string            // Image name
	ImageID        string            // Image ID
	Labels         map[string]string // Container labels
	ComposeProject string            // Compose project name, from the labels
	ComposeService string            // Compose service name, from the labels
	Mounts         []string          // Names of the mounted volumes
}

ContainerInfo describes a container.

type DryRunVolumeResult

type DryRunVolumeResult struct {
	TargetVolume       string
	SnapshotID         string
	SourceName         string
	ContainersAffected []string
	WillEraseData      bool
	Warnings           []string
}

DryRunVolumeResult describes what a restore would do without executing it.

type Engine

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

Engine orchestrates Docker container lifecycle and delegates actual backup/restore operations to a pkg/ark Repository.

func New

func New(repo *ark.Repository, opts ...Option) (*Engine, error)

New creates a new Engine.

func (*Engine) BackupVolume

func (e *Engine) BackupVolume(ctx context.Context, volume string, opts ...ark.BackupOption) (*ark.Snapshot, error)

BackupVolume stops the running containers that use the volume, streams its contents through the repository, then starts them again.

func (*Engine) Client

func (e *Engine) Client() *Client

Client returns the underlying Docker client.

func (*Engine) Close

func (e *Engine) Close() error

Close releases all resources held by the Engine.

func (*Engine) DryRunVolume

func (e *Engine) DryRunVolume(ctx context.Context, snapshotID, targetVolume string) (*DryRunVolumeResult, error)

DryRunVolume analyses a restore without making any changes. It checks whether the target volume exists, which containers use it, and whether any data would be erased — all without touching the CAS.

func (*Engine) GetVolume

func (e *Engine) GetVolume(ctx context.Context, name string) (*VolumeInfo, error)

GetVolume returns metadata for the named Docker volume.

func (*Engine) ListVolumes

func (e *Engine) ListVolumes(ctx context.Context) ([]VolumeInfo, error)

ListVolumes returns all Docker volumes visible to the daemon.

func (*Engine) RestoreVolume

func (e *Engine) RestoreVolume(
	ctx context.Context,
	snapshotID, volume string,
	opts ...ark.RestoreOption,
) (*ark.RestoreResult, error)

RestoreVolume restores a snapshot into the volume, creating it when it does not exist and replacing its contents when it does. The running containers that use it are stopped first and started again after. A snapshot of another source type fails with ark.ErrIncompatibleSourceType.

type Option

type Option func(*Engine)

Option configures an Engine.

func WithDockerHost

func WithDockerHost(host string) Option

WithDockerHost sets the Docker daemon address.

func WithHelperImage

func WithHelperImage(ref string) Option

WithHelperImage sets the image the helper containers run, for mirrors. It needs a POSIX sh with rm.

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger sets the logger for the engine and its client. Default is slog.Default().

func WithStopTimeout

func WithStopTimeout(d time.Duration) Option

WithStopTimeout sets the graceful container stop timeout. Zero keeps the default of 30 seconds.

func WithoutStop

func WithoutStop() Option

WithoutStop leaves the containers that use a volume running during backup and restore. The caller takes the consistency risk.

type VolumeInfo

type VolumeInfo struct {
	Name       string
	Driver     string
	Mountpoint string
	CreatedAt  time.Time
	Labels     map[string]string
	Options    map[string]string
	Scope      string
}

VolumeInfo contains metadata about a Docker volume.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL