overmount

README

overmount - mount tars in an overlay filesystem

overmount is intended to mount docker images, or work with similar functionality to achieve a series of layered filesystems which can be composed into an image.

See the examples directory for examples of how to use the API.

installation

It is strongly recommended to use a vendoring tool to pin at a specific commit. We will tag releases on an as-needed basis, but there is no notion of backwards compat between versions.

author

Erik Hollensbe github@hollensbe.org

Documentation

Overview

Package overmount - mount tars in an overlay filesystem

overmount is intended to mount docker images, or work with similar functionality to achieve a series of layered filesystems which can be composed into an image.

See the examples/ directory for examples of how to use the API.

github.com/pkg/errors.Wrap is in use with many of our errors; look at the errors.Cause API in that package for more information on how to extract the static error constants.

Index

• Variables
• type Asset
  • func NewAsset(path string, digest digest.Digester) (*Asset, error)
  • func (a *Asset) Digest() digest.Digest
  • func (a *Asset) LoadDigest() (digest.Digest, error)
  • func (a *Asset) Pack(writer io.Writer) error
  • func (a *Asset) Path() string
  • func (a *Asset) Unpack(reader io.Reader) error
• type Exporter
• type Image
  • func (i *Image) Commit() error
  • func (i *Image) Mount() error
  • func (i *Image) Unmount() error
• type Importer
• type Layer
  • func (l *Layer) Config() (*v1.Image, error)
  • func (l *Layer) Create() error
  • func (l *Layer) Digest() (digest.Digest, error)
  • func (l *Layer) Exists() bool
  • func (l *Layer) ID() string
  • func (l *Layer) LoadParent() error
  • func (l *Layer) MountPath() string
  • func (l *Layer) Pack(writer io.Writer) (digest.Digest, error)
  • func (l *Layer) Path() string
  • func (l *Layer) Remove() error
  • func (l *Layer) RestoreParent() error
  • func (l *Layer) SaveConfig(config *v1.Image) error
  • func (l *Layer) SaveParent() error
  • func (l *Layer) Unpack(reader io.Reader) (digest.Digest, error)
• type Mount
  • func (m *Mount) Close() error
  • func (m *Mount) Equals(m2 *Mount) bool
  • func (m *Mount) Mounted() bool
  • func (m *Mount) Open() error
• type Repository
  • func NewRepository(baseDir string) (*Repository, error)
  • func (r *Repository) AddLayer(layer *Layer) error
  • func (r *Repository) AddMount(mount *Mount) error
  • func (r *Repository) CreateLayer(id string, parent *Layer) (*Layer, error)
  • func (r *Repository) Export(e Exporter, layer *Layer) (io.ReadCloser, error)
  • func (r *Repository) Import(i Importer, reader io.ReadCloser) ([]*Layer, error)
  • func (r *Repository) NewImage(topLayer *Layer) *Image
  • func (r *Repository) NewLayer(id string, parent *Layer) (*Layer, error)
  • func (r *Repository) NewMount(target, lower, upper string) (*Mount, error)
  • func (r *Repository) RemoveLayer(layer *Layer)
  • func (r *Repository) RemoveMount(mount *Mount)
  • func (r *Repository) TempDir() (string, error)

Variables

var (
	// ErrParentNotMounted is returned when the parent layer is not mounted (but exists)
	ErrParentNotMounted = errors.New("parent not mounted, cannot continue")

	// ErrMountFailed returns an underlying error when the mount has failed.
	ErrMountFailed = errors.New("mount failed")

	// ErrUnmountFailed returns an underlying error when the unmount has failed.
	ErrUnmountFailed = errors.New("unmount failed")

	// ErrMountCannotProceed returns an underlying error when the mount cannot be processed.
	ErrMountCannotProceed = errors.New("mount cannot proceed")

	// ErrImageCannotBeComposed is returned when an image (a set of layers) fails validation.
	ErrImageCannotBeComposed = errors.New("image cannot be composed")

	// ErrInvalidAsset is returned when the asset cannot be used.
	ErrInvalidAsset = errors.New("invalid asset")

	// ErrInvalidLayer is returned when the layer cannot be used.
	ErrInvalidLayer = errors.New("invalid layer")

	// ErrLayerExists is called when a layer id already exists in the repository.
	ErrLayerExists = errors.New("layer already exists")

	// ErrMountExists is called when a mount already exists in the repository.
	ErrMountExists = errors.New("mount already exists")
)

Types

type Asset

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

Asset is the representation of an on-disk asset. Assets usually are a pair of (path, tar) where one direction is applied; f.e., you can copy from the tar to the dir, or the dir to the tar using the Read and Write calls.

func NewAsset

func NewAsset(path string, digest digest.Digester) (*Asset, error)

NewAsset constructs a new *Asset that operates on path `path`. A digester must be provided. Typically this is a `digest.SHA256.Digester()` but can be any algorithm that opencontainers/go-digest supports.

func (*Asset) Digest

func (a *Asset) Digest() digest.Digest

Digest returns the digest of the last pack or unpack.

func (*Asset) LoadDigest

func (a *Asset) LoadDigest() (digest.Digest, error)

LoadDigest processes the digest from the existing contents of the filesystem.

func (*Asset) Pack

func (a *Asset) Pack(writer io.Writer) error

Pack a tarball from the filesystem. Accepts an io.Writer, not a *tar.Writer!

func (*Asset) Path

func (a *Asset) Path() string

Path gets the filesystem path we will be working with.

func (*Asset) Unpack

func (a *Asset) Unpack(reader io.Reader) error

Unpack from the io.Reader (must be a tar file!) and unpack to the filesystem. Accepts io.Reader, not *tar.Reader!

type Exporter

type Exporter interface {
	// Export produces a tar represented as an io.ReadCloser from the Layer provided.
	Export(*Layer) (io.ReadCloser, error)
}

Exporter is an interface to image exporters; ways to get images out of overmount repositories.

type Image

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

Image is the representation of a set of sequential layers to be mounted.

func (*Image) Commit

func (i *Image) Commit() error

Commit saves all the parents

func (*Image) Mount

func (i *Image) Mount() error

Mount mounts an image with the specified layer as its highest element. Images must have at least two layers to be mounted. If you need to work with the first layer, operate on the layer directly with the Asset interface.

Call unmount to undo this operation.

func (*Image) Unmount

func (i *Image) Unmount() error

Unmount unmounts the image. This does not affect layer storage.

type Importer

type Importer interface {
	// Import takes a tar represented as an io.ReadCloser, and converts and unpacks
	// it into the overmount repository.  Returns the top-most layer and any
	// error.
	Import(*Repository, io.ReadCloser) ([]*Layer, error)
}

Importer is an interface to image importers; ways to get images into overmount repositories.

type Layer

type Layer struct {
	Parent *Layer
	// contains filtered or unexported fields
}

Layer is the representation of a filesystem layer. Layers are organized in a reverse linked-list from topmost layer to the root layer. In an (*Image).Mount() scenario, the layers are mounted from the bottom up to culminate in a mount path that represents the top-most layer merged with all the lower layers.

See https://www.kernel.org/doc/Documentation/filesystems/overlayfs.txt for more information on mount flags.

func (*Layer) Config

func (l *Layer) Config() (*v1.Image, error)

Config returns a reference to the image configuration for this layer.

func (*Layer) Create

func (l *Layer) Create() error

Create creates the layer and makes it available for use, if possible. Otherwise, it returns an error.

func (*Layer) Digest

func (l *Layer) Digest() (digest.Digest, error)

Digest returns the digest.Digest for the layer and any error.

func (*Layer) Exists

func (l *Layer) Exists() bool

Exists indicates whether or not a layer already exists.

func (*Layer) ID

func (l *Layer) ID() string

ID returns the ID of the layer.

func (*Layer) LoadParent

func (l *Layer) LoadParent() error

LoadParent loads only the parent for this specific instance. See RestoreParent for restoring the whole chain.

func (*Layer) MountPath

func (l *Layer) MountPath() string

MountPath gets the mount path for a given subpath.

func (*Layer) Pack

func (l *Layer) Pack(writer io.Writer) (digest.Digest, error)

Pack archives the layer to the writer as a tar file.

func (*Layer) Path

func (l *Layer) Path() string

Path gets the layer store path for a given subpath.

func (*Layer) Remove

func (l *Layer) Remove() error

Remove a layer from the filesystem and the repository.

func (*Layer) RestoreParent

func (l *Layer) RestoreParent() error

RestoreParent reads any parent file and sets the layer accordingly. It does this recursively.

func (*Layer) SaveConfig

func (l *Layer) SaveConfig(config *v1.Image) error

SaveConfig writes a *v1.Image configuration to the repository for the layer.

func (*Layer) SaveParent

func (l *Layer) SaveParent() error

SaveParent will silently only save the

func (*Layer) Unpack

func (l *Layer) Unpack(reader io.Reader) (digest.Digest, error)

Unpack unpacks the asset into the layer Path(). It returns the computed digest.

type Mount

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

Mount represents a single overlay mount. The lower value is computed from the parent layer of the layer provided to the NewMount call. The target and upper dirs are computed from the passed layer.

func (*Mount) Close

func (m *Mount) Close() error

Close a mount and remove the work directory. The target directory is left untouched.

func (*Mount) Equals

func (m *Mount) Equals(m2 *Mount) bool

Equals compares two mounts to see if they're equivalent

func (*Mount) Mounted

func (m *Mount) Mounted() bool

Mounted returns true if the volume is currently mounted.

func (*Mount) Open

func (m *Mount) Open() error

Open an overlay mount at (*Mount).Target; returns any errors.

type Repository

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

Repository is a collection of mounts/layers. Repositories have a base path and a collection of layers and mounts. Overlay work directories are stored in `tmp`.

In summary:

basedir/
   layers/
     layer-id/
     top-layer/
   tmp/
     some-random-workdir/
   mount/
     another-layer-id/
     top-layer/

Repositories can hold any number of mounts and layers. They do not necessarily need to be related.

func NewRepository

func NewRepository(baseDir string) (*Repository, error)

NewRepository constructs a *Repository and creates the dir in which the repository lives. A repository is used to hold images and mounts.

func (*Repository) AddLayer

func (r *Repository) AddLayer(layer *Layer) error

AddLayer adds a layer to the repository.

func (*Repository) AddMount

func (r *Repository) AddMount(mount *Mount) error

AddMount adds a layer to the repository.

func (*Repository) CreateLayer

func (r *Repository) CreateLayer(id string, parent *Layer) (*Layer, error)

CreateLayer prepares a new layer for work and creates it in the repository.

func (*Repository) Export

func (r *Repository) Export(e Exporter, layer *Layer) (io.ReadCloser, error)

Export an image (provided via writer) from the repository.

func (*Repository) Import

func (r *Repository) Import(i Importer, reader io.ReadCloser) ([]*Layer, error)

Import an image (provided over reader) to the repository.

func (*Repository) NewImage

func (r *Repository) NewImage(topLayer *Layer) *Image

NewImage preps a set of layers to be a part of an image. There must be at least two layers

func (*Repository) NewLayer

func (r *Repository) NewLayer(id string, parent *Layer) (*Layer, error)

NewLayer prepares a new layer for work but DOES NOT add it to the repository. The ID is the directory that will be created in the repository; see NewRepository for more info.

func (*Repository) NewMount

func (r *Repository) NewMount(target, lower, upper string) (*Mount, error)

NewMount creates a new mount for use. Target, lower, and upper correspond to specific fields in the mount stanza; read https://www.kernel.org/doc/Documentation/filesystems/overlayfs.txt for more information.

func (*Repository) RemoveLayer

func (r *Repository) RemoveLayer(layer *Layer)

RemoveLayer removes a layer from the repository

func (*Repository) RemoveMount

func (r *Repository) RemoveMount(mount *Mount)

RemoveMount removes a layer from the repository

func (*Repository) TempDir

func (r *Repository) TempDir() (string, error)

TempDir returns a temporary path within the repository