volume

Documentation

Index

• Variables
• type Info
• type Provider
• type ProviderSpec
• type PullCoordinate
• type Volume

Variables

var UnknownProviderKind error = fmt.Errorf("volume provider kind is not known")

Types

type Info

type Info struct {
	// Volumes have a unique identifier.
	// These are guid formatted (v4, random); selected by the server;
	// and though not globally sync'd, entropy should be high enough to be unique.
	ID string `json:"id"`
}

`volume.Info` names and describes info about a volume. It is a serializable structure intended for API use.

type Provider

type Provider interface {
	Kind() string

	NewVolume() (Volume, error)
	DestroyVolume(Volume) error
	CreateSnapshot(Volume) (Volume, error)
	ForkVolume(Volume) (Volume, error)

	ListHaves(Volume) ([]json.RawMessage, error) // Report known data addresses; this can be given to `SendSnapshot` to attempt deduplicated/incrememntal transport.
	SendSnapshot(vol Volume, haves []json.RawMessage, stream io.Writer) error
	ReceiveSnapshot(Volume, io.Reader) (Volume, error) // Reads a filesystem state from the stream and applies it to the volume, replacing the current content.

	MarshalGlobalState() (json.RawMessage, error)
	MarshalVolumeState(volumeID string) (json.RawMessage, error)
	RestoreVolumeState(volumeInfo *Info, data json.RawMessage) (Volume, error)
}

Provider defines the interface of system that can produce and manage volumes. Providers may have different backing implementations (i.e zfs vs btrfs vs etc). Provider instances may also vary in their parameters, so for example the volume.Manager on a host could be configured with two different Providers that both use zfs, but have different zpools configured for their final storage location.

type ProviderSpec

type ProviderSpec struct {
	// ID used by the API to specify this provider
	ID string `json:"id"`

	// names the kind of provider (roughly matches an enum of known names)
	Kind string `json:"kind"`

	// parameters to pass to the provider during its creation/configuration.
	// values vary per implementation kind;
	// see the ProviderConfig struct in implementation packages for known values.
	Config json.RawMessage `json:"metadata,omitempty"`
}

type PullCoordinate

type PullCoordinate struct {
	HostID     string `json:"host_id"`
	SnapshotID string `json:"snapshot_id"`
}

type Volume

type Volume interface {
	Info() *Info

	Provider() Provider

	// Location returns the path to this volume's mount.  To use the volume in a job, bind mount this into the container's filesystem.
	Location() string

	IsSnapshot() bool
}

A Volume is a persistent and sharable filesystem. Unlike most of the filesystem in a job's container, which is ephemeral and is discarded after job termination, Volumes can be used to store data and may be reconnected to a later job (or to multiple jobs).

Volumes may also support additional features for their section of the filesystem, such storage quotas, read-only mounts, snapshotting operation, etc.

The Flynn host service maintains a locally persistent knowledge of mounts, and supplies this passively to the orchestration API. The host service does *not* perform services such as garbage collection of unmounted volumes (how is it to know whether you still want that data preserved for a future job?) or transport and persistence of volumes between hosts (that should be orchestrated via the API from a higher level service).