overmount

package module
v0.0.0-...-3a5da77 Latest Latest
Warning

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

 Go to latest Published: Aug 16, 2017 License: Apache-2.0 Imports: 14 Imported by: 5

README

overmount - mount tars in an overlay filesystem

GoDoc Build Status

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

Constants

This section is empty.

Variables

View Source 
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")
)
View Source 
var (
	// ErrTagDoesNotExist is reported when the tag retrieved or removed does not exist
	ErrTagDoesNotExist = errors.New("tag does not exist")
)

Functions

This section is empty.

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, virtual bool) (*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(*Repository, *Layer, []string) (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 ImageConfig 

type ImageConfig struct {
	// ID is a unique 64 character identifier of the image
	ID string `json:"id,omitempty"`

	// Parent is the ID of the parent image
	Parent string `json:"parent,omitempty"`

	// Comment is the commit message that was set when committing the image
	Comment string `json:"comment,omitempty"`

	// Created is the timestamp at which the image was created
	Created time.Time `json:"created"`

	// Container is the id of the container used to commit
	Container string `json:"container,omitempty"`

	// ContainerConfig is the configuration of the container that is committed into the image
	ContainerConfig interface{} `json:"container_config,omitempty"`

	// DockerVersion specifies the version of Docker that was used to build the image
	DockerVersion string `json:"docker_version,omitempty"`

	// Author is the name of the author that was specified when committing the image
	Author string `json:"author,omitempty"`

	// Architecture is the hardware that the image is built and runs on
	Architecture string `json:"architecture,omitempty"`

	// OS is the operating system used to build and run the image
	OS string `json:"os,omitempty"`

	// User defines the username or UID which the process in the container should run as.
	User string `json:"user,omitempty"`

	// ExposedPorts a set of ports to expose from a container running this image.
	ExposedPorts map[string]struct{} `json:"exposed_ports,omitempty"`

	// Env is a list of environment variables to be used in a container.
	Env []string `json:"env,omitempty"`

	// Entrypoint defines a list of arguments to use as the command to execute when the container starts.
	Entrypoint []string `json:"entrypoint,omitempty"`

	// Cmd defines the default arguments to the entrypoint of the container.
	Cmd []string `json:"cmd,omitempty"`

	// Volumes is a set of directories which should be created as data volumes in a container running this image.
	Volumes map[string]struct{} `json:"volumes,omitempty"`

	// WorkingDir sets the current working directory of the entrypoint process in the container.
	WorkingDir string `json:"working_dir,omitempty"`

	// Labels contains arbitrary metadata for the container.
	Labels map[string]string `json:"labels,omitempty"`

	// StopSignal contains the system call signal that will be sent to the container to exit.
	StopSignal string `json:"stopsignal,omitempty"`
}

ImageConfig is a portable, non-standard format used by overmount for the generation of other configuration formats used in images. It is an attempt to be abstract from the formats themselves. It is intentionally flat to avoid merging problems with newer editions of overmount.

NOTE: some portions of this code are taken from docker/docker and opencontainers/image-spec.

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() (*ImageConfig, 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

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) LoadDigest 

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

LoadDigest recalculates the digest for the asset, and returns it (and any error)

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 *ImageConfig) 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, virtual bool) (*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, overwrite bool) 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) AddTag 

func (r *Repository) AddTag(name string, layer *Layer) error

AddTag tags a layer with the name

func (*Repository) CreateLayer 

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

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

func (*Repository) CreateLayerFromAsset 

func (r *Repository) CreateLayerFromAsset(reader io.Reader, parent *Layer, overwrite bool) (retLayer *Layer, retErr error)

CreateLayerFromAsset prepares a new layer for work and creates it in the repository. The ID is calculated from the digest.

func (*Repository) Export 

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

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

func (*Repository) GetTag 

func (r *Repository) GetTag(name string) (*Layer, error)

GetTag retrieves the layer by the tag name. Returns an error if the tag or layer cannot be found. NOTE: the layer is *not* restored.

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) IsVirtual 

func (r *Repository) IsVirtual() bool

IsVirtual reports if the repository is virtual. Virtual repositories hold tars and cannot accept mounts.

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. If the layer is already in the repository and known, it will be returned and no file operations or checks will be performed. The layer may not actually exist at this point.

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) RemoveTag 

func (r *Repository) RemoveTag(name string) error

RemoveTag removes a tag by name.

func (*Repository) TempDir 

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

TempDir returns a temporary path within the repository

func (*Repository) TempFile 

func (r *Repository) TempFile() (*os.File, error)

TempFile returns a temporary file within the repository

Source Files

View all Source files

Directories

Path Synopsis
examples
pull

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.