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
- func NewVolumeSink(client *Client, volume string) ark.Sink
- func NewVolumeSource(client *Client, volume string) ark.Source
- type Client
- func (c *Client) Close() error
- func (c *Client) ContainerExists(ctx context.Context, nameOrID string) (bool, error)
- func (c *Client) FindContainersUsingVolume(ctx context.Context, volume string) ([]ContainerInfo, error)
- func (c *Client) GetContainer(ctx context.Context, id string) (*ContainerInfo, error)
- func (c *Client) GetVolume(ctx context.Context, name string) (*VolumeInfo, error)
- func (c *Client) ListContainers(ctx context.Context, all bool) ([]ContainerInfo, error)
- func (c *Client) ListVolumes(ctx context.Context) ([]VolumeInfo, error)
- func (c *Client) Ping(ctx context.Context) error
- func (c *Client) ServerVersion(ctx context.Context) (string, error)
- func (c *Client) VolumeExists(ctx context.Context, name string) (bool, error)
- type Config
- type ContainerInfo
- type DryRunVolumeResult
- type Engine
- func (e *Engine) BackupVolume(ctx context.Context, volume string, opts ...ark.BackupOption) (*ark.Snapshot, error)
- func (e *Engine) Client() *Client
- func (e *Engine) Close() error
- func (e *Engine) DryRunVolume(ctx context.Context, snapshotID, targetVolume string) (*DryRunVolumeResult, error)
- func (e *Engine) GetVolume(ctx context.Context, name string) (*VolumeInfo, error)
- func (e *Engine) ListVolumes(ctx context.Context) ([]VolumeInfo, error)
- func (e *Engine) RestoreVolume(ctx context.Context, snapshotID, volume string, opts ...ark.RestoreOption) (*ark.RestoreResult, error)
- type Option
- type VolumeInfo
Constants ¶
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.
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 ¶
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.
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 ¶
NewClient connects to the daemon at dockerHost. Empty means DOCKER_HOST and friends, then the default socket.
func (*Client) ContainerExists ¶
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 ¶
GetContainer describes one container by name or ID.
func (*Client) ListContainers ¶
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) ServerVersion ¶
ServerVersion returns the Docker daemon server version string.
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) 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) 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 ¶
WithDockerHost sets the Docker daemon address.
func WithHelperImage ¶
WithHelperImage sets the image the helper containers run, for mirrors. It needs a POSIX sh with rm.
func WithLogger ¶
WithLogger sets the logger for the engine and its client. Default is slog.Default().
func WithStopTimeout ¶
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.