storage

package module
v0.46.1 Latest Latest
Warning

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

 Go to latest Published: Apr 8, 2023 License: Apache-2.0 Imports: 43 Imported by: 459

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 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.

Contributing Information about contributing to this project.

Documentation

Index

Constants

View Source 
const (
	// ImageDigestManifestBigDataNamePrefix is a prefix of big data item
	// names which we consider to be manifests, used for computing a
	// "digest" value for the image as a whole, by which we can locate the
	// image later.
	ImageDigestManifestBigDataNamePrefix = "manifest"
	// ImageDigestBigDataKey is provided for compatibility with older
	// versions of the image library.  It will be removed in the future.
	ImageDigestBigDataKey = "manifest"
)
View Source 
const AutoUserNsMaxSize = 65536

AutoUserNsMaxSize is the maximum size for automatically created user namespaces

View Source 
const AutoUserNsMinSize = 1024

AutoUserNsMinSize is the minimum size for automatically created user namespaces

View Source 
const RootAutoUserNsUser = "containers"

RootAutoUserNsUser is the default user used for root containers when automatically creating a user namespace.

Variables

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

Functions

func DefaultConfigFile 

func DefaultConfigFile(rootless bool) (string, error)

DefaultConfigFile returns the path to the storage config file used

func DefaultStoreOptions 

func DefaultStoreOptions(rootless bool, rootlessUID int) (types.StoreOptions, error)

DefaultStoreOptions returns the default storage options for containers

func DefaultStoreOptionsAutoDetectUID 

func DefaultStoreOptionsAutoDetectUID() (types.StoreOptions, error)

DefaultStoreOptionsAutoDetectUID returns the default storage options for containers

func GetDefaultMountOptions 

func GetDefaultMountOptions() ([]string, error)

GetDefaultMountOptions returns the default mountoptions defined in container/storage

func GetLockfile deprecated 

func GetLockfile(path string) (lockfile.Locker, error)

Deprecated: Use lockfile.GetLockFile.

func GetMountOptions 

func GetMountOptions(driver string, graphDriverOptions []string) ([]string, error)

GetMountOptions returns the mountoptions for the specified driver and graphDriverOptions

func GetROLockfile deprecated 

func GetROLockfile(path string) (lockfile.Locker, error)

Deprecated: Use lockfile.GetROLockFile.

func GetRootlessRuntimeDir 

func GetRootlessRuntimeDir(rootlessUID int) (string, error)

GetRootlessRuntimeDir returns the runtime directory when running as non root

func ParseIDMapping 

func ParseIDMapping(UIDMapSlice, GIDMapSlice []string, subUIDMap, subGIDMap string) (*types.IDMappingOptions, error)

ParseIDMapping takes idmappings and subuid and subgid maps and returns a storage mapping

func ReloadConfigurationFile 

func ReloadConfigurationFile(configFile string, storeOptions *types.StoreOptions)

ReloadConfigurationFile parses the specified configuration file and overrides the configuration in storeOptions. Deprecated: Use types.ReloadConfigurationFile, which can return an error.

func SetDefaultConfigFilePath 

func SetDefaultConfigFilePath(path string)

SetDefaultConfigFilePath sets the default configuration to the specified path, and loads the file. Deprecated: Use types.SetDefaultConfigFilePath, which can return an error.

Types

type AdditionalLayer added in v0.46.1 

type AdditionalLayer interface {
	// PutAs creates layer based on this handler, using diff contents from the additional
	// layer store.
	PutAs(id, parent string, names []string) (*Layer, error)

	// UncompressedDigest returns the uncompressed digest of this layer
	UncompressedDigest() digest.Digest

	// CompressedSize returns the compressed size of this layer
	CompressedSize() int64

	// Release tells the additional layer store that we don't use this handler.
	Release()
}

AdditionalLayer represents a layer that is contained in the additional layer store This API is experimental and can be changed without bumping the major version number.

type AutoUserNsOptions 

type AutoUserNsOptions = types.AutoUserNsOptions

type Container 

type Container struct {
	// ID is either one which was specified at create-time, or a random
	// value which was generated by the library.
	ID string `json:"id"`

	// Names is an optional set of user-defined convenience values.  The
	// container can be referred to by its ID or any of its names.  Names
	// are unique among containers.
	Names []string `json:"names,omitempty"`

	// ImageID is the ID of the image which was used to create the container.
	ImageID string `json:"image"`

	// LayerID is the ID of the read-write layer for the container itself.
	// It is assumed that the image's top layer is the parent of the container's
	// read-write layer.
	LayerID string `json:"layer"`

	// Metadata is data we keep for the convenience of the caller.  It is not
	// expected to be large, since it is kept in memory.
	Metadata string `json:"metadata,omitempty"`

	// BigDataNames is a list of names of data items that we keep for the
	// convenience of the caller.  They can be large, and are only in
	// memory when being read from or written to disk.
	BigDataNames []string `json:"big-data-names,omitempty"`

	// BigDataSizes maps the names in BigDataNames to the sizes of the data
	// that has been stored, if they're known.
	BigDataSizes map[string]int64 `json:"big-data-sizes,omitempty"`

	// BigDataDigests maps the names in BigDataNames to the digests of the
	// data that has been stored, if they're known.
	BigDataDigests map[string]digest.Digest `json:"big-data-digests,omitempty"`

	// Created is the datestamp for when this container was created.  Older
	// versions of the library did not track this information, so callers
	// will likely want to use the IsZero() method to verify that a value
	// is set before using it.
	Created time.Time `json:"created,omitempty"`

	// UIDMap and GIDMap are used for setting up a container's root
	// filesystem for use inside of a user namespace where UID mapping is
	// being used.
	UIDMap []idtools.IDMap `json:"uidmap,omitempty"`
	GIDMap []idtools.IDMap `json:"gidmap,omitempty"`

	Flags map[string]interface{} `json:"flags,omitempty"`
	// contains filtered or unexported fields
}

A Container is a reference to a read-write layer with metadata.

func (*Container) MountLabel 

func (c *Container) MountLabel() string

func (*Container) MountOpts 

func (c *Container) MountOpts() []string

func (*Container) ProcessLabel 

func (c *Container) ProcessLabel() string

type ContainerBigDataOption added in v0.46.1 

type ContainerBigDataOption struct {
	Key  string
	Data []byte
}

type ContainerBigDataStore deprecated 

type ContainerBigDataStore interface {
	ROBigDataStore
	SetBigData(id, key string, data []byte) error
}

ContainerBigDataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type ContainerOptions 

type ContainerOptions struct {
	// IDMappingOptions specifies the type of ID mapping which should be
	// used for this container's layer.  If nothing is specified, the
	// container's layer will inherit settings from the image's top layer
	// or, if it is not being created based on an image, the Store object.
	types.IDMappingOptions
	LabelOpts []string
	// Flags is a set of named flags and their values to store with the container.
	// Currently these can only be set when the container record is created, but that
	// could change in the future.
	Flags      map[string]interface{}
	MountOpts  []string
	Volatile   bool
	StorageOpt map[string]string
	// Metadata is caller-specified metadata associated with the container.
	Metadata string
	// BigData is a set of items which should be stored for the container.
	BigData []ContainerBigDataOption
}

ContainerOptions is used for passing options to a Store's CreateContainer() method.

type ContainerStore deprecated 

type ContainerStore interface {
	FileBasedStore
	MetadataStore
	ContainerBigDataStore
	FlaggableStore
	Create(id string, names []string, image, layer, metadata string, options *ContainerOptions) (*Container, error)
	SetNames(id string, names []string) error
	AddNames(id string, names []string) error
	RemoveNames(id string, names []string) error
	Get(id string) (*Container, error)
	Exists(id string) bool
	Delete(id string) error
	Wipe() error
	Lookup(name string) (string, error)
	Containers() ([]Container, error)
}

ContainerStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type DiffOptions 

type DiffOptions struct {
	// Compression, if set overrides the default compressor when generating a diff.
	Compression *archive.Compression
}

DiffOptions override the default behavior of Diff() methods.

type FileBasedStore deprecated 

type FileBasedStore interface {
	ROFileBasedStore
	RWFileBasedStore
}

FileBasedStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type FlaggableStore deprecated 

type FlaggableStore interface {
	ClearFlag(id string, flag string) error
	SetFlag(id string, flag string, value interface{}) error
}

FlaggableStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type IDMappingOptions 

type IDMappingOptions = types.IDMappingOptions

type Image 

type Image struct {
	// ID is either one which was specified at create-time, or a random
	// value which was generated by the library.
	ID string `json:"id"`

	// Digest is a digest value that we can use to locate the image, if one
	// was specified at creation-time.
	Digest digest.Digest `json:"digest,omitempty"`

	// Digests is a list of digest values of the image's manifests, and
	// possibly a manually-specified value, that we can use to locate the
	// image.  If Digest is set, its value is also in this list.
	Digests []digest.Digest `json:"-"`

	// Names is an optional set of user-defined convenience values.  The
	// image can be referred to by its ID or any of its names.  Names are
	// unique among images, and are often the text representation of tagged
	// or canonical references.
	Names []string `json:"names,omitempty"`

	// NamesHistory is an optional set of Names the image had in the past. The
	// contained names are free from any duplicates, whereas the newest entry
	// is the first one.
	NamesHistory []string `json:"names-history,omitempty"`

	// TopLayer is the ID of the topmost layer of the image itself, if the
	// image contains one or more layers.  Multiple images can refer to the
	// same top layer.
	TopLayer string `json:"layer,omitempty"`

	// MappedTopLayers are the IDs of alternate versions of the top layer
	// which have the same contents and parent, and which differ from
	// TopLayer only in which ID mappings they use.  When the image is
	// to be removed, they should be removed before the TopLayer, as the
	// graph driver may depend on that.
	MappedTopLayers []string `json:"mapped-layers,omitempty"`

	// Metadata is data we keep for the convenience of the caller.  It is not
	// expected to be large, since it is kept in memory.
	Metadata string `json:"metadata,omitempty"`

	// BigDataNames is a list of names of data items that we keep for the
	// convenience of the caller.  They can be large, and are only in
	// memory when being read from or written to disk.
	BigDataNames []string `json:"big-data-names,omitempty"`

	// BigDataSizes maps the names in BigDataNames to the sizes of the data
	// that has been stored, if they're known.
	BigDataSizes map[string]int64 `json:"big-data-sizes,omitempty"`

	// BigDataDigests maps the names in BigDataNames to the digests of the
	// data that has been stored, if they're known.
	BigDataDigests map[string]digest.Digest `json:"big-data-digests,omitempty"`

	// Created is the datestamp for when this image was created.  Older
	// versions of the library did not track this information, so callers
	// will likely want to use the IsZero() method to verify that a value
	// is set before using it.
	Created time.Time `json:"created,omitempty"`

	// ReadOnly is true if this image resides in a read-only layer store.
	ReadOnly bool `json:"-"`

	Flags map[string]interface{} `json:"flags,omitempty"`
}

An Image is a reference to a layer and an associated metadata string.

type ImageBigDataOption added in v0.46.1 

type ImageBigDataOption struct {
	Key    string
	Data   []byte
	Digest digest.Digest
}

type ImageOptions 

type ImageOptions struct {
	// CreationDate, if not zero, will override the default behavior of marking the image as having been
	// created when CreateImage() was called, recording CreationDate instead.
	CreationDate time.Time
	// Digest is a hard-coded digest value that we can use to look up the image.  It is optional.
	Digest digest.Digest
	// Digests is a list of digest values of the image's manifests, and
	// possibly a manually-specified value, that we can use to locate the
	// image.  If Digest is set, its value is also in this list.
	Digests []digest.Digest
	// Metadata is caller-specified metadata associated with the layer.
	Metadata string
	// BigData is a set of items which should be stored with the image.
	BigData []ImageBigDataOption
	// NamesHistory is used for guessing for what this image was named when a container was created based
	// on it, but it no longer has any names.
	NamesHistory []string
	// Flags is a set of named flags and their values to store with the image.  Currently these can only
	// be set when the image record is created, but that could change in the future.
	Flags map[string]interface{}
}

ImageOptions is used for passing options to a Store's CreateImage() method.

type ImageStore deprecated 

type ImageStore interface {
	ROImageStore
	RWFileBasedStore
	RWMetadataStore
	RWImageBigDataStore
	FlaggableStore
	Create(id string, names []string, layer, metadata string, created time.Time, searchableDigest digest.Digest) (*Image, error)
	SetNames(id string, names []string) error
	AddNames(id string, names []string) error
	RemoveNames(id string, names []string) error
	Delete(id string) error
	Wipe() error
}

ImageStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type Layer 

type Layer struct {
	// ID is either one which was specified at create-time, or a random
	// value which was generated by the library.
	ID string `json:"id"`

	// Names is an optional set of user-defined convenience values.  The
	// layer can be referred to by its ID or any of its names.  Names are
	// unique among layers.
	Names []string `json:"names,omitempty"`

	// Parent is the ID of a layer from which this layer inherits data.
	Parent string `json:"parent,omitempty"`

	// Metadata is data we keep for the convenience of the caller.  It is not
	// expected to be large, since it is kept in memory.
	Metadata string `json:"metadata,omitempty"`

	// MountLabel is an SELinux label which should be used when attempting to mount
	// the layer.
	MountLabel string `json:"mountlabel,omitempty"`

	// MountPoint is the path where the layer is mounted, or where it was most
	// recently mounted.
	//
	// WARNING: This field is a snapshot in time: (except for users inside c/storage that
	// hold the mount lock) the true value can change between subsequent
	// calls to c/storage API.
	//
	// Users that need to handle concurrent mount/unmount attempts should not access this
	// field at all, and should only use the path returned by .Mount() (and that’s only
	// assuming no other user will concurrently decide to unmount that mount point).
	MountPoint string `json:"-"`

	// MountCount is used as a reference count for the container's layer being
	// mounted at the mount point.
	//
	// WARNING: This field is a snapshot in time; (except for users inside c/storage that
	// hold the mount lock) the true value can change between subsequent
	// calls to c/storage API.
	//
	// In situations where concurrent mount/unmount attempts can happen, this field
	// should not be used for any decisions, maybe apart from heuristic user warnings.
	MountCount int `json:"-"`

	// Created is the datestamp for when this layer was created.  Older
	// versions of the library did not track this information, so callers
	// will likely want to use the IsZero() method to verify that a value
	// is set before using it.
	Created time.Time `json:"created,omitempty"`

	// CompressedDigest is the digest of the blob that was last passed to
	// ApplyDiff() or create(), as it was presented to us.
	CompressedDigest digest.Digest `json:"compressed-diff-digest,omitempty"`

	// CompressedSize is the length of the blob that was last passed to
	// ApplyDiff() or create(), as it was presented to us.  If
	// CompressedDigest is not set, this should be treated as if it were an
	// uninitialized value.
	CompressedSize int64 `json:"compressed-size,omitempty"`

	// UncompressedDigest is the digest of the blob that was last passed to
	// ApplyDiff() or create(), after we decompressed it.  Often referred to
	// as a DiffID.
	UncompressedDigest digest.Digest `json:"diff-digest,omitempty"`

	// UncompressedSize is the length of the blob that was last passed to
	// ApplyDiff() or create(), after we decompressed it.  If
	// UncompressedDigest is not set, this should be treated as if it were
	// an uninitialized value.
	UncompressedSize int64 `json:"diff-size,omitempty"`

	// CompressionType is the type of compression which we detected on the blob
	// that was last passed to ApplyDiff() or create().
	CompressionType archive.Compression `json:"compression,omitempty"`

	// UIDs and GIDs are lists of UIDs and GIDs used in the layer.  This
	// field is only populated (i.e., will only contain one or more
	// entries) if the layer was created using ApplyDiff() or create().
	UIDs []uint32 `json:"uidset,omitempty"`
	GIDs []uint32 `json:"gidset,omitempty"`

	// Flags is arbitrary data about the layer.
	Flags map[string]interface{} `json:"flags,omitempty"`

	// UIDMap and GIDMap are used for setting up a layer's contents
	// for use inside of a user namespace where UID mapping is being used.
	UIDMap []idtools.IDMap `json:"uidmap,omitempty"`
	GIDMap []idtools.IDMap `json:"gidmap,omitempty"`

	// ReadOnly is true if this layer resides in a read-only layer store.
	ReadOnly bool `json:"-"`

	// BigDataNames is a list of names of data items that we keep for the
	// convenience of the caller.  They can be large, and are only in
	// memory when being read from or written to disk.
	BigDataNames []string `json:"big-data-names,omitempty"`
	// contains filtered or unexported fields
}

A Layer is a record of a copy-on-write layer that's stored by the lower level graph driver.

type LayerBigDataOption added in v0.46.1 

type LayerBigDataOption struct {
	Key  string
	Data io.Reader
}

type LayerBigDataStore deprecated added in v0.46.1 

type LayerBigDataStore interface {
	ROLayerBigDataStore
	RWLayerBigDataStore
}

LayerBigDataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type LayerOptions 

type LayerOptions struct {
	// IDMappingOptions specifies the type of ID mapping which should be
	// used for this layer.  If nothing is specified, the layer will
	// inherit settings from its parent layer or, if it has no parent
	// layer, the Store object.
	types.IDMappingOptions
	// TemplateLayer is the ID of a layer whose contents will be used to
	// initialize this layer.  If set, it should be a child of the layer
	// which we want to use as the parent of the new layer.
	TemplateLayer string
	// OriginalDigest specifies a digest of the tarstream (diff), if one is
	// provided along with these LayerOptions, and reliably known by the caller.
	// Use the default "" if this fields is not applicable or the value is not known.
	OriginalDigest digest.Digest
	// UncompressedDigest specifies a digest of the uncompressed version (“DiffID”)
	// of the tarstream (diff), if one is provided along with these LayerOptions,
	// and reliably known by the caller.
	// Use the default "" if this fields is not applicable or the value is not known.
	UncompressedDigest digest.Digest
	// True is the layer info can be treated as volatile
	Volatile bool
	// BigData is a set of items which should be stored with the layer.
	BigData []LayerBigDataOption
	// Flags is a set of named flags and their values to store with the layer.
	// Currently these can only be set when the layer record is created, but that
	// could change in the future.
	Flags map[string]interface{}
}

LayerOptions is used for passing options to a Store's CreateLayer() and PutLayer() methods.

type LayerStore deprecated 

type LayerStore interface {
	ROLayerStore
	RWFileBasedStore
	RWMetadataStore
	FlaggableStore
	RWLayerBigDataStore
	Create(id string, parent *Layer, names []string, mountLabel string, options map[string]string, moreOptions *LayerOptions, writeable bool) (*Layer, error)
	CreateWithFlags(id string, parent *Layer, names []string, mountLabel string, options map[string]string, moreOptions *LayerOptions, writeable bool, flags map[string]interface{}) (layer *Layer, err error)
	Put(id string, parent *Layer, names []string, mountLabel string, options map[string]string, moreOptions *LayerOptions, writeable bool, flags map[string]interface{}, diff io.Reader) (*Layer, int64, error)
	SetNames(id string, names []string) error
	AddNames(id string, names []string) error
	RemoveNames(id string, names []string) error
	Delete(id string) error
	Wipe() error
	Mount(id string, options drivers.MountOpts) (string, error)
	Unmount(id string, force bool) (bool, error)
	Mounted(id string) (int, error)
	ParentOwners(id string) (uids, gids []int, err error)
	ApplyDiff(to string, diff io.Reader) (int64, error)
	ApplyDiffWithDiffer(to string, options *drivers.ApplyDiffOpts, differ drivers.Differ) (*drivers.DriverWithDifferOutput, error)
	CleanupStagingDirectory(stagingDirectory string) error
	ApplyDiffFromStagingDirectory(id, stagingDirectory string, diffOutput *drivers.DriverWithDifferOutput, options *drivers.ApplyDiffOpts) error
	DifferTarget(id string) (string, error)
	LoadLocked() error
	PutAdditionalLayer(id string, parentLayer *Layer, names []string, aLayer drivers.AdditionalLayer) (layer *Layer, err error)
}

LayerStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type Locker deprecated 

type Locker = lockfile.Locker //lint:ignore SA1019 // lockfile.Locker is deprecated

Deprecated: Use lockfile.*LockFile.

type MetadataStore deprecated 

type MetadataStore interface {
	ROMetadataStore
	RWMetadataStore
}

MetadataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type ROBigDataStore deprecated 

type ROBigDataStore interface {
	BigData(id, key string) ([]byte, error)
	BigDataSize(id, key string) (int64, error)
	BigDataDigest(id, key string) (digest.Digest, error)
	BigDataNames(id string) ([]string, error)
}

ROBigDataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type ROFileBasedStore deprecated 

type ROFileBasedStore interface {
	Locker
	Load() error
	ReloadIfChanged() error
}

ROFileBasedStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type ROImageStore deprecated 

type ROImageStore interface {
	ROFileBasedStore
	ROMetadataStore
	ROBigDataStore
	Exists(id string) bool
	Get(id string) (*Image, error)
	Lookup(name string) (string, error)
	Images() ([]Image, error)
	ByDigest(d digest.Digest) ([]*Image, error)
}

ROImageStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type ROLayerBigDataStore deprecated added in v0.46.1 

type ROLayerBigDataStore interface {
	BigData(id, key string) (io.ReadCloser, error)
	BigDataNames(id string) ([]string, error)
}

ROLayerBigDataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type ROLayerStore deprecated 

type ROLayerStore interface {
	ROFileBasedStore
	ROMetadataStore
	ROLayerBigDataStore
	Exists(id string) bool
	Get(id string) (*Layer, error)
	Status() ([][2]string, error)
	Changes(from, to string) ([]archive.Change, error)
	Diff(from, to string, options *DiffOptions) (io.ReadCloser, error)
	DiffSize(from, to string) (int64, error)
	Size(name string) (int64, error)
	Lookup(name string) (string, error)
	LayersByCompressedDigest(d digest.Digest) ([]Layer, error)
	LayersByUncompressedDigest(d digest.Digest) ([]Layer, error)
	Layers() ([]Layer, error)
}

ROLayerStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type ROMetadataStore deprecated 

type ROMetadataStore interface {
	Metadata(id string) (string, error)
}

ROMetadataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type RWFileBasedStore deprecated 

type RWFileBasedStore interface {
	Save() error
}

RWFileBasedStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type RWImageBigDataStore deprecated 

type RWImageBigDataStore interface {
	SetBigData(id, key string, data []byte, digestManifest func([]byte) (digest.Digest, error)) error
}

RWImageBigDataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type RWLayerBigDataStore deprecated added in v0.46.1 

type RWLayerBigDataStore interface {
	SetBigData(id, key string, data io.Reader) error
}

RWLayerBigDataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type RWMetadataStore deprecated 

type RWMetadataStore interface {
	SetMetadata(id, metadata string) error
}

RWMetadataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.

Deprecated: There is no way to use this from any external user of c/storage to invoke c/storage functionality.

type Store 

type Store interface {
	// RunRoot, GraphRoot, GraphDriverName, and GraphOptions retrieve
	// settings that were passed to GetStore() when the object was created.
	RunRoot() string
	GraphRoot() string
	TransientStore() bool
	GraphDriverName() string
	GraphOptions() []string
	PullOptions() map[string]string
	UIDMap() []idtools.IDMap
	GIDMap() []idtools.IDMap

	// GraphDriver obtains and returns a handle to the graph Driver object used
	// by the Store.
	GraphDriver() (drivers.Driver, error)

	// CreateLayer creates a new layer in the underlying storage driver,
	// optionally having the specified ID (one will be assigned if none is
	// specified), with the specified layer (or no layer) as its parent,
	// and with optional names.  (The writeable flag is ignored.)
	CreateLayer(id, parent string, names []string, mountLabel string, writeable bool, options *LayerOptions) (*Layer, error)

	// PutLayer combines the functions of CreateLayer and ApplyDiff,
	// marking the layer for automatic removal if applying the diff fails
	// for any reason.
	//
	// Note that we do some of this work in a child process.  The calling
	// process's main() function needs to import our pkg/reexec package and
	// should begin with something like this in order to allow us to
	// properly start that child process:
	//   if reexec.Init() {
	//       return
	//   }
	PutLayer(id, parent string, names []string, mountLabel string, writeable bool, options *LayerOptions, diff io.Reader) (*Layer, int64, error)

	// CreateImage creates a new image, optionally with the specified ID
	// (one will be assigned if none is specified), with optional names,
	// referring to a specified image, and with optional metadata.  An
	// image is a record which associates the ID of a layer with a
	// additional bookkeeping information which the library stores for the
	// convenience of its caller.
	CreateImage(id string, names []string, layer, metadata string, options *ImageOptions) (*Image, error)

	// CreateContainer creates a new container, optionally with the
	// specified ID (one will be assigned if none is specified), with
	// optional names, using the specified image's top layer as the basis
	// for the container's layer, and assigning the specified ID to that
	// layer (one will be created if none is specified).  A container is a
	// layer which is associated with additional bookkeeping information
	// which the library stores for the convenience of its caller.
	CreateContainer(id string, names []string, image, layer, metadata string, options *ContainerOptions) (*Container, error)

	// Metadata retrieves the metadata which is associated with a layer,
	// image, or container (whichever the passed-in ID refers to).
	Metadata(id string) (string, error)

	// SetMetadata updates the metadata which is associated with a layer,
	// image, or container (whichever the passed-in ID refers to) to match
	// the specified value.  The metadata value can be retrieved at any
	// time using Metadata, or using Layer, Image, or Container and reading
	// the object directly.
	SetMetadata(id, metadata string) error

	// Exists checks if there is a layer, image, or container which has the
	// passed-in ID or name.
	Exists(id string) bool

	// Status asks for a status report, in the form of key-value pairs,
	// from the underlying storage driver.  The contents vary from driver
	// to driver.
	Status() ([][2]string, error)

	// Delete removes the layer, image, or container which has the
	// passed-in ID or name.  Note that no safety checks are performed, so
	// this can leave images with references to layers which do not exist,
	// and layers with references to parents which no longer exist.
	Delete(id string) error

	// DeleteLayer attempts to remove the specified layer.  If the layer is the
	// parent of any other layer, or is referred to by any images, it will return
	// an error.
	DeleteLayer(id string) error

	// DeleteImage removes the specified image if it is not referred to by
	// any containers.  If its top layer is then no longer referred to by
	// any other images and is not the parent of any other layers, its top
	// layer will be removed.  If that layer's parent is no longer referred
	// to by any other images and is not the parent of any other layers,
	// then it, too, will be removed.  This procedure will be repeated
	// until a layer which should not be removed, or the base layer, is
	// reached, at which point the list of removed layers is returned.  If
	// the commit argument is false, the image and layers are not removed,
	// but the list of layers which would be removed is still returned.
	DeleteImage(id string, commit bool) (layers []string, err error)

	// DeleteContainer removes the specified container and its layer.  If
	// there is no matching container, or if the container exists but its
	// layer does not, an error will be returned.
	DeleteContainer(id string) error

	// Wipe removes all known layers, images, and containers.
	Wipe() error

	// MountImage mounts an image to temp directory and returns the mount point.
	// MountImage allows caller to mount an image. Images will always
	// be mounted read/only
	MountImage(id string, mountOptions []string, mountLabel string) (string, error)

	// Unmount attempts to unmount an image, given an ID.
	// Returns whether or not the layer is still mounted.
	// WARNING: The return value may already be obsolete by the time it is available
	// to the caller, so it can be used for heuristic sanity checks at best. It should almost always be ignored.
	UnmountImage(id string, force bool) (bool, error)

	// Mount attempts to mount a layer, image, or container for access, and
	// returns the pathname if it succeeds.
	// Note if the mountLabel == "", the default label for the container
	// will be used.
	//
	// Note that we do some of this work in a child process.  The calling
	// process's main() function needs to import our pkg/reexec package and
	// should begin with something like this in order to allow us to
	// properly start that child process:
	//   if reexec.Init() {
	//       return
	//   }
	Mount(id, mountLabel string) (string, error)

	// Unmount attempts to unmount a layer, image, or container, given an ID, a
	// name, or a mount path. Returns whether or not the layer is still mounted.
	// WARNING: The return value may already be obsolete by the time it is available
	// to the caller, so it can be used for heuristic sanity checks at best. It should almost always be ignored.
	Unmount(id string, force bool) (bool, error)

	// Mounted returns number of times the layer has been mounted.
	//
	// WARNING: This value might already be obsolete by the time it is returned;
	// In situations where concurrent mount/unmount attempts can happen, this field
	// should not be used for any decisions, maybe apart from heuristic user warnings.
	Mounted(id string) (int, error)

	// Changes returns a summary of the changes which would need to be made
	// to one layer to make its contents the same as a second layer.  If
	// the first layer is not specified, the second layer's parent is
	// assumed.  Each Change structure contains a Path relative to the
	// layer's root directory, and a Kind which is either ChangeAdd,
	// ChangeModify, or ChangeDelete.
	Changes(from, to string) ([]archive.Change, error)

	// DiffSize returns a count of the size of the tarstream which would
	// specify the changes returned by Changes.
	DiffSize(from, to string) (int64, error)

	// Diff returns the tarstream which would specify the changes returned
	// by Changes.  If options are passed in, they can override default
	// behaviors.
	Diff(from, to string, options *DiffOptions) (io.ReadCloser, error)

	// ApplyDiff applies a tarstream to a layer.  Information about the
	// tarstream is cached with the layer.  Typically, a layer which is
	// populated using a tarstream will be expected to not be modified in
	// any other way, either before or after the diff is applied.
	//
	// Note that we do some of this work in a child process.  The calling
	// process's main() function needs to import our pkg/reexec package and
	// should begin with something like this in order to allow us to
	// properly start that child process:
	//   if reexec.Init() {
	//       return
	//   }
	ApplyDiff(to string, diff io.Reader) (int64, error)

	// ApplyDiffer applies a diff to a layer.
	// It is the caller responsibility to clean the staging directory if it is not
	// successfully applied with ApplyDiffFromStagingDirectory.
	ApplyDiffWithDiffer(to string, options *drivers.ApplyDiffOpts, differ drivers.Differ) (*drivers.DriverWithDifferOutput, error)

	// ApplyDiffFromStagingDirectory uses stagingDirectory to create the diff.
	ApplyDiffFromStagingDirectory(to, stagingDirectory string, diffOutput *drivers.DriverWithDifferOutput, options *drivers.ApplyDiffOpts) error

	// CleanupStagingDirectory cleanups the staging directory.  It can be used to cleanup the staging directory on errors
	CleanupStagingDirectory(stagingDirectory string) error

	// DifferTarget gets the path to the differ target.
	DifferTarget(id string) (string, error)

	// LayersByCompressedDigest returns a slice of the layers with the
	// specified compressed digest value recorded for them.
	LayersByCompressedDigest(d digest.Digest) ([]Layer, error)

	// LayersByUncompressedDigest returns a slice of the layers with the
	// specified uncompressed digest value recorded for them.
	LayersByUncompressedDigest(d digest.Digest) ([]Layer, error)

	// LayerSize returns a cached approximation of the layer's size, or -1
	// if we don't have a value on hand.
	LayerSize(id string) (int64, error)

	// LayerParentOwners returns the UIDs and GIDs of owners of parents of
	// the layer's mountpoint for which the layer's UID and GID maps (if
	// any are defined) don't contain corresponding IDs.
	LayerParentOwners(id string) ([]int, []int, error)

	// Layers returns a list of the currently known layers.
	Layers() ([]Layer, error)

	// Images returns a list of the currently known images.
	Images() ([]Image, error)

	// Containers returns a list of the currently known containers.
	Containers() ([]Container, error)

	// Names returns the list of names for a layer, image, or container.
	Names(id string) ([]string, error)

	// Free removes the store from the list of stores
	Free()

	// SetNames changes the list of names for a layer, image, or container.
	// Duplicate names are removed from the list automatically.
	// Deprecated: Prone to race conditions, suggested alternatives are `AddNames` and `RemoveNames`.
	SetNames(id string, names []string) error

	// AddNames adds the list of names for a layer, image, or container.
	// Duplicate names are removed from the list automatically.
	AddNames(id string, names []string) error

	// RemoveNames removes the list of names for a layer, image, or container.
	// Duplicate names are removed from the list automatically.
	RemoveNames(id string, names []string) error

	// ListImageBigData retrieves a list of the (possibly large) chunks of
	// named data associated with an image.
	ListImageBigData(id string) ([]string, error)

	// ImageBigData retrieves a (possibly large) chunk of named data
	// associated with an image.
	ImageBigData(id, key string) ([]byte, error)

	// ImageBigDataSize retrieves the size of a (possibly large) chunk
	// of named data associated with an image.
	ImageBigDataSize(id, key string) (int64, error)

	// ImageBigDataDigest retrieves the digest of a (possibly large) chunk
	// of named data associated with an image.
	ImageBigDataDigest(id, key string) (digest.Digest, error)

	// SetImageBigData stores a (possibly large) chunk of named data
	// associated with an image.  Pass
	// github.com/containers/image/manifest.Digest as digestManifest to
	// allow ImagesByDigest to find images by their correct digests.
	SetImageBigData(id, key string, data []byte, digestManifest func([]byte) (digest.Digest, error)) error

	// ListLayerBigData retrieves a list of the (possibly large) chunks of
	// named data associated with a layer.
	ListLayerBigData(id string) ([]string, error)

	// LayerBigData retrieves a (possibly large) chunk of named data
	// associated with a layer.
	LayerBigData(id, key string) (io.ReadCloser, error)

	// SetLayerBigData stores a (possibly large) chunk of named data
	// associated with a layer.
	SetLayerBigData(id, key string, data io.Reader) error

	// ImageSize computes the size of the image's layers and ancillary data.
	ImageSize(id string) (int64, error)

	// ListContainerBigData retrieves a list of the (possibly large) chunks of
	// named data associated with a container.
	ListContainerBigData(id string) ([]string, error)

	// ContainerBigData retrieves a (possibly large) chunk of named data
	// associated with a container.
	ContainerBigData(id, key string) ([]byte, error)

	// ContainerBigDataSize retrieves the size of a (possibly large)
	// chunk of named data associated with a container.
	ContainerBigDataSize(id, key string) (int64, error)

	// ContainerBigDataDigest retrieves the digest of a (possibly large)
	// chunk of named data associated with a container.
	ContainerBigDataDigest(id, key string) (digest.Digest, error)

	// SetContainerBigData stores a (possibly large) chunk of named data
	// associated with a container.
	SetContainerBigData(id, key string, data []byte) error

	// ContainerSize computes the size of the container's layer and ancillary
	// data.  Warning:  this is a potentially expensive operation.
	ContainerSize(id string) (int64, error)

	// Layer returns a specific layer.
	Layer(id string) (*Layer, error)

	// Image returns a specific image.
	Image(id string) (*Image, error)

	// ImagesByTopLayer returns a list of images which reference the specified
	// layer as their top layer.  They will have different IDs and names
	// and may have different metadata, big data items, and flags.
	ImagesByTopLayer(id string) ([]*Image, error)

	// ImagesByDigest returns a list of images which contain a big data item
	// named ImageDigestBigDataKey whose contents have the specified digest.
	ImagesByDigest(d digest.Digest) ([]*Image, error)

	// Container returns a specific container.
	Container(id string) (*Container, error)

	// ContainerByLayer returns a specific container based on its layer ID or
	// name.
	ContainerByLayer(id string) (*Container, error)

	// ContainerDirectory returns a path of a directory which the caller
	// can use to store data, specific to the container, which the library
	// does not directly manage.  The directory will be deleted when the
	// container is deleted.
	ContainerDirectory(id string) (string, error)

	// SetContainerDirectoryFile is a convenience function which stores
	// a piece of data in the specified file relative to the container's
	// directory.
	SetContainerDirectoryFile(id, file string, data []byte) error

	// FromContainerDirectory is a convenience function which reads
	// the contents of the specified file relative to the container's
	// directory.
	FromContainerDirectory(id, file string) ([]byte, error)

	// ContainerRunDirectory returns a path of a directory which the
	// caller can use to store data, specific to the container, which the
	// library does not directly manage.  The directory will be deleted
	// when the host system is restarted.
	ContainerRunDirectory(id string) (string, error)

	// SetContainerRunDirectoryFile is a convenience function which stores
	// a piece of data in the specified file relative to the container's
	// run directory.
	SetContainerRunDirectoryFile(id, file string, data []byte) error

	// FromContainerRunDirectory is a convenience function which reads
	// the contents of the specified file relative to the container's run
	// directory.
	FromContainerRunDirectory(id, file string) ([]byte, error)

	// ContainerParentOwners returns the UIDs and GIDs of owners of parents
	// of the container's layer's mountpoint for which the layer's UID and
	// GID maps (if any are defined) don't contain corresponding IDs.
	ContainerParentOwners(id string) ([]int, []int, error)

	// Lookup returns the ID of a layer, image, or container with the specified
	// name or ID.
	Lookup(name string) (string, error)

	// Shutdown attempts to free any kernel resources which are being used
	// by the underlying driver.  If "force" is true, any mounted (i.e., in
	// use) layers are unmounted beforehand.  If "force" is not true, then
	// layers being in use is considered to be an error condition.  A list
	// of still-mounted layers is returned along with possible errors.
	Shutdown(force bool) (layers []string, err error)

	// Version returns version information, in the form of key-value pairs, from
	// the storage package.
	Version() ([][2]string, error)

	// GetDigestLock returns digest-specific Locker.
	GetDigestLock(digest.Digest) (Locker, error)

	// LayerFromAdditionalLayerStore searches the additional layer store and returns an object
	// which can create a layer with the specified digest associated with the specified image
	// reference. Note that this hasn't been stored to this store yet: the actual creation of
	// a usable layer is done by calling the returned object's PutAs() method.  After creating
	// a layer, the caller must then call the object's Release() method to free any temporary
	// resources which were allocated for the object by this method or the object's PutAs()
	// method.
	// This API is experimental and can be changed without bumping the major version number.
	LookupAdditionalLayer(d digest.Digest, imageref string) (AdditionalLayer, error)

	// Tries to clean up remainders of previous containers or layers that are not
	// references in the json files. These can happen in the case of unclean
	// shutdowns or regular restarts in transient store mode.
	GarbageCollect() error
}

Store wraps up the various types of file-based stores that we use into a singleton object that initializes and manages them all together.

func GetStore 

func GetStore(options types.StoreOptions) (Store, error)

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.

If StoreOptions `options` haven't been fully populated, then DefaultStoreOptions are used.

These defaults observe environment variables:

  • `STORAGE_DRIVER` for the name of the storage driver to attempt to use
  • `STORAGE_OPTS` for the string of options to pass to the driver

Note that we do some of this work in a child process. The calling process's main() function needs to import our pkg/reexec package and should begin with something like this in order to allow us to properly start that child process: 

if reexec.Init() {
    return
}

type StoreOptions 

type StoreOptions = types.StoreOptions

Source Files

View all Source files

Directories

Path Synopsis
cmd
containers-storage
aufs
btrfs
copy
devmapper
graphtest
overlay
overlayutils
quota
register
vfs
windows
zfs
internal
opts
pkg
archive
chrootarchive
chunked
chunked/compressor
Package rollsum implements rolling checksums similar to apenwarr's bup, which is similar to librsync.
 Package rollsum implements rolling checksums similar to apenwarr's bup, which is similar to librsync.
chunked/internal
config
devicemapper
directory
dmesg
fileutils
fsutils
homedir
idmap
idtools
ioutils
locker
Package locker provides a mechanism for creating finer-grained locking to help free up more global locks to handle other tasks.
 Package locker provides a mechanism for creating finer-grained locking to help free up more global locks to handle other tasks.
lockfile
longpath
loopback
mflag
mflag/example
mount
parsers
Package parsers provides helper functions to parse and validate different type of string.
 Package parsers provides helper functions to parse and validate different type of string.
parsers/kernel
Package kernel provides helper function to get, parse and compare kernel versions for different platforms.
 Package kernel provides helper function to get, parse and compare kernel versions for different platforms.
parsers/operatingsystem
Package operatingsystem provides helper function to get the operating system name for different platforms.
 Package operatingsystem provides helper function to get the operating system name for different platforms.
pools
Package pools provides a collection of pools which provide various data types with buffers.
 Package pools provides a collection of pools which provide various data types with buffers.
promise
reexec
regexp
stringid
Package stringid provides helper functions for dealing with string identifiers
 Package stringid provides helper functions for dealing with string identifiers
stringutils
Package stringutils provides helper functions for dealing with strings.
 Package stringutils provides helper functions for dealing with strings.
system
tarlog
truncindex
Package truncindex provides a general 'index tree', used by Docker in order to be able to reference containers by only a few unambiguous characters of their id.
 Package truncindex provides a general 'index tree', used by Docker in order to be able to reference containers by only a few unambiguous characters of their id.
unshare

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.