Categorygithub.com/mtrmac/storage
modulepackage
0.0.0-20180604200230-88d80428f9b1
Repository: https://github.com/mtrmac/storage.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
33
Dependents
0
Files
10k SLOC

# README

storage is a Go library which aims to provide methods for storing filesystem layers, container images, and containers. A containers-storage CLI wrapper is also included for manual and scripting use.

To build the CLI wrapper, use 'make build-binary'.

Operations which use VMs expect to launch them using 'vagrant', defaulting to using its 'libvirt' provider. The boxes used are also available for the 'virtualbox' provider, and can be selected by setting $VAGRANT_PROVIDER to 'virtualbox' before kicking off the build.

The library manages three types of items: layers, images, and containers.

A layer is a copy-on-write filesystem which is notionally stored as a set of changes relative to its parent layer, if it has one. A given layer can only have one parent, but any layer can be the parent of multiple layers. Layers which are parents of other layers should be treated as read-only.

An image is a reference to a particular layer (its top layer), along with other information which the library can manage for the convenience of its caller. This information typically includes configuration templates for running a binary contained within the image's layers, and may include cryptographic signatures. Multiple images can reference the same layer, as the differences between two images may not be in their layer contents.

A container is a read-write layer which is a child of an image's top layer, along with information which the library can manage for the convenience of its caller. This information typically includes configuration information for running the specific container. Multiple containers can be derived from a single image.

Layers, images, and containers are represented primarily by 32 character hexadecimal IDs, but items of each kind can also have one or more arbitrary names attached to them, which the library will automatically resolve to IDs when they are passed in to API calls which expect IDs.

The library can store what it calls metadata for each of these types of items. This is expected to be a small piece of data, since it is cached in memory and stored along with the library's own bookkeeping information.

Additionally, the library can store one or more of what it calls big data for images and containers. This is a named chunk of larger data, which is only in memory when it is being read from or being written to its own disk file.

# Packages

No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author

# Functions

GetLockfile opens a read-write lock file, creating it if necessary.
GetROLockfile opens a read-only lock file.
GetStore attempts to find an already-created Store object matching the specified location and graph driver, and if it can't, it creates and initializes a new Store object, and the underlying storage that it controls.

# Constants

ImageDigestBigDataKey is the name of the big data item whose contents we consider useful for computing a "digest" of the image, by which we can locate the image later.

# Variables

DefaultStoreOptions is a reasonable default set of options.
ErrContainerUnknown indicates that there was no container with the specified name or ID.
ErrDigestUnknown indicates that we were unable to compute the digest of a specified item.
ErrDuplicateID indicates that an ID which is to be assigned to a new item is already being used.
ErrDuplicateImageNames indicates that the read-only store uses the same name for multiple images.
ErrDuplicateLayerNames indicates that the read-only store uses the same name for multiple layers.
ErrDuplicateName indicates that a name which is to be assigned to a new item is already being used.
ErrImageUnknown indicates that there was no image with the specified name or ID.
ErrImageUsedByContainer is returned when the caller attempts to delete an image that is a container's image.
ErrIncompleteOptions is returned when the caller attempts to initialize a Store without providing required information.
ErrInvalidBigDataName indicates that the name for a big data item is not acceptable; it may be empty.
ErrLayerHasChildren is returned when the caller attempts to delete a layer that has children.
ErrLayerNotMounted is returned when the requested information can only be computed for a mounted layer, and the layer is not mounted.
ErrLayerUnknown indicates that there was no layer with the specified name or ID.
ErrLayerUsedByContainer is returned when the caller attempts to delete a layer that is a container's layer.
ErrLayerUsedByImage is returned when the caller attempts to delete a layer that is an image's top layer.
ErrLoadError indicates that there was an initialization error.
ErrLockReadOnly indicates that the caller only took a read-only lock, and is not allowed to write.
ErrNotAContainer is returned when the caller attempts to delete a container that isn't a container.
ErrNotALayer is returned when the caller attempts to delete a layer that isn't a layer.
ErrNotAnID is returned when the caller attempts to read or write metadata from an item that doesn't exist.
ErrNotAnImage is returned when the caller attempts to delete an image that isn't an image.
ErrParentIsContainer is returned when a caller attempts to create a layer as a child of a container's layer.
ErrParentUnknown indicates that we didn't record the ID of the parent of the specified layer.
ErrSizeUnknown is returned when the caller asks for the size of a big data item, but the Store couldn't determine the answer.
ErrStoreIsReadOnly is returned when the caller makes a call to a read-only store that would require modifying its contents.

# Structs

A Container is a reference to a read-write layer with metadata.
ContainerOptions is used for passing options to a Store's CreateContainer() method.
DiffOptions override the default behavior of Diff() methods.
IDMappingOptions are used for specifying how ID mapping should be set up for a layer or container.
An Image is a reference to a layer and an associated metadata string.
ImageOptions is used for passing options to a Store's CreateImage() method.
A Layer is a record of a copy-on-write layer that's stored by the lower level graph driver.
LayerOptions is used for passing options to a Store's CreateLayer() and PutLayer() methods.
OptionsConfig represents the "storage.options" TOML config table.
StoreOptions is used for passing initialization options to GetStore(), for initializing a Store object and the underlying storage that it controls.
ThinpoolOptionsConfig represents the "storage.options.thinpool" TOML config table.

# Interfaces

A BigDataStore wraps up the most common big-data related methods of the various types of file-based lookaside stores that we implement.
ContainerStore provides bookkeeping for information about Containers.
FileBasedStore wraps up the common methods of various types of file-based data stores that we implement.
A FlaggableStore can have flags set and cleared on items which it manages.
ImageStore provides bookkeeping for information about Images.
LayerStore wraps a graph driver, adding the ability to refer to layers by name, and keeping track of parent-child relationships, along with a list of all known layers.
A Locker represents a file lock where the file is used to cache an identifier of the last party that made changes to whatever's being protected by the lock.
MetadataStore wraps up methods for getting and setting metadata associated with IDs.
An ROBigDataStore wraps up the read-only big-data related methods of the various types of file-based lookaside stores that we implement.
ROFileBasedStore wraps up the methods of the various types of file-based data stores that we implement which are needed for both read-only and read-write files.
ROImageStore provides bookkeeping for information about Images.
ROLayerStore wraps a graph driver, adding the ability to refer to layers by name, and keeping track of parent-child relationships, along with a list of all known layers.
ROMetadataStore wraps a method for reading metadata associated with an ID.
A RWBigDataStore wraps up the read-write big-data related methods of the various types of file-based lookaside stores that we implement.
RWFileBasedStore wraps up the methods of various types of file-based data stores that we implement using read-write files.
RWMetadataStore wraps a method for setting metadata associated with an ID.
Store wraps up the various types of file-based stores that we use into a singleton object that initializes and manages them all together.