overlay

Documentation

Overview

Package overlay implements an overlay based container store.

Index

• func Supported(cacheRoot string) bool
• type Bundle
  • func BootstrapBundle(path string, parentLayerPaths []string) (Bundle, error)
  • func (b Bundle) Cleanup() error
  • func (b Bundle) Path() string
• type BundleBootstrapper
• type BundleBootstrapperFn
  • func (fn BundleBootstrapperFn) Bootstrap(path string, parentLayerPaths []string) (Bundle, error)
• type CachingBundler
  • func NewCachingBundler(root string) (*CachingBundler, error)
  • func (c *CachingBundler) Bundle(ctx context.Context, i ociv1.Image, id string, o ...spec.Option) (store.Bundle, error)
• type CachingLayerResolver
  • func NewCachingLayerResolver(root string) (*CachingLayerResolver, error)
  • func (s *CachingLayerResolver) Resolve(ctx context.Context, l ociv1.Layer, parents ...ociv1.Layer) (string, error)
• type LayerResolver
• type LayerWorkdir
  • func NewLayerWorkdir(dir, digest string, parentLayerPaths []string, o ...NewLayerWorkdirOption) (LayerWorkdir, error)
  • func (d LayerWorkdir) ApplyPath() string
  • func (d LayerWorkdir) Cleanup() error
  • func (d LayerWorkdir) ResultPath() string
• type Mount
  • func DefaultNewOverlayMount(path string, parentLayerPaths []string) Mount
• type NewLayerWorkdirOption
  • func WithNewOverlayMountFn(fn NewOverlayMountFn) NewLayerWorkdirOption
• type NewOverlayMountFn
• type OverlayMount
  • func (m OverlayMount) Mount() error
  • func (m OverlayMount) Unmount() error
• type RuntimeSpecWriter
• type RuntimeSpecWriterFn
  • func (fn RuntimeSpecWriterFn) Write(path string, o ...spec.Option) error
• type TarballApplicator
• type TmpFSMount
  • func (m TmpFSMount) Mount() error
  • func (m TmpFSMount) Unmount() error
• type WorkDirOptions

Functions

func Supported

func Supported(cacheRoot string) bool

Supported returns true if the supplied cacheRoot supports the overlay filesystem. Notably overlayfs was not supported in unprivileged user namespaces until Linux kernel 5.11. It's also not possible to create an overlayfs where the upper dir is itself on an overlayfs (i.e. is on a container's root filesystem). https://github.com/torvalds/linux/commit/459c7c565ac36ba09ffbf

Types

type Bundle

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

An Bundle is an OCI runtime bundle. Its root filesystem is a temporary overlay atop its image's cached layers.

func BootstrapBundle

func BootstrapBundle(path string, parentLayerPaths []string) (Bundle, error)

BootstrapBundle creates and returns an OCI runtime bundle with a root filesystem backed by a temporary (tmpfs) overlay atop the supplied lower layer paths.

func (Bundle) Cleanup

func (b Bundle) Cleanup() error

Cleanup the OCI bundle.

func (Bundle) Path

func (b Bundle) Path() string

Path to the OCI bundle.

type BundleBootstrapper

type BundleBootstrapper interface {
	Bootstrap(path string, parentLayerPaths []string) (Bundle, error)
}

A BundleBootstrapper bootstraps a bundle by creating and mounting its rootfs.

type BundleBootstrapperFn

type BundleBootstrapperFn func(path string, parentLayerPaths []string) (Bundle, error)

A BundleBootstrapperFn bootstraps a bundle by creating and mounting its rootfs.

func (BundleBootstrapperFn) Bootstrap

func (fn BundleBootstrapperFn) Bootstrap(path string, parentLayerPaths []string) (Bundle, error)

Bootstrap a bundle by creating and mounting its rootfs.

type CachingBundler

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

An CachingBundler stores OCI containers, images, and layers. When asked to bundle a container for a new image the CachingBundler will extract and cache the image's layers as files on disk. The container's root filesystem is then created as an overlay atop the image's layers. The upper layer of this overlay is stored in memory on a tmpfs, and discarded once the container has finished running.

func NewCachingBundler

func NewCachingBundler(root string) (*CachingBundler, error)

NewCachingBundler returns a bundler that creates container filesystems as overlays on their image's layers, which are stored as extracted, overlay compatible directories of files.

func (*CachingBundler) Bundle

func (c *CachingBundler) Bundle(ctx context.Context, i ociv1.Image, id string, o ...spec.Option) (store.Bundle, error)

Bundle returns an OCI bundle ready for use by an OCI runtime. The supplied image will be fetched and cached in the store if it does not already exist.

type CachingLayerResolver

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

A CachingLayerResolver resolves an OCI layer to an overlay compatible directory on disk. The directory is created the first time a layer is resolved; subsequent calls return the cached directory.

func NewCachingLayerResolver

func NewCachingLayerResolver(root string) (*CachingLayerResolver, error)

NewCachingLayerResolver returns a LayerResolver that extracts layers upon first resolution, returning cached layer paths on subsequent calls.

func (*CachingLayerResolver) Resolve

func (s *CachingLayerResolver) Resolve(ctx context.Context, l ociv1.Layer, parents ...ociv1.Layer) (string, error)

Resolve the supplied layer to a path suitable for use as an overlayfs lower layer directory. The first time a layer is resolved it will be extracted and cached as an overlayfs compatible directory of files, with any OCI whiteouts converted to overlayfs whiteouts.

type LayerResolver

type LayerResolver interface {
	// Resolve the supplied layer to a path suitable for use as a lower dir.
	Resolve(ctx context.Context, l ociv1.Layer, parents ...ociv1.Layer) (string, error)
}

An LayerResolver resolves the supplied layer to a path suitable for use as an overlayfs lower directory.

type LayerWorkdir

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

A LayerWorkdir is a temporary directory used to produce an overlayfs layer from an OCI layer by applying the OCI layer to a temporary overlay mount. It's not possible to _directly_ create overlay whiteout files in an unprivileged user namespace because doing so requires CAP_MKNOD in the 'root' or 'initial' user namespace - whiteout files are actually character devices per "whiteouts and opaque directories" at https://www.kernel.org/doc/Documentation/filesystems/overlayfs.txt

We can however create overlay whiteout files indirectly by creating an overlay where the parent OCI layers are the lower overlayfs layers, and applying the layer to be cached to said fs. Doing so will produce an upper overlayfs layer that we can cache. This layer will be a valid lower layer (complete with overlay whiteout files) for either subsequent layers from the OCI image, or the final container root filesystem layer.

func NewLayerWorkdir

func NewLayerWorkdir(dir, digest string, parentLayerPaths []string, o ...NewLayerWorkdirOption) (LayerWorkdir, error)

NewLayerWorkdir returns a temporary directory used to produce an overlayfs layer from an OCI layer.

func (LayerWorkdir) ApplyPath

func (d LayerWorkdir) ApplyPath() string

ApplyPath returns the path an OCI layer should be applied (i.e. extracted) to in order to create an overlayfs layer.

func (LayerWorkdir) Cleanup

func (d LayerWorkdir) Cleanup() error

Cleanup the temporary directory.

func (LayerWorkdir) ResultPath

func (d LayerWorkdir) ResultPath() string

ResultPath returns the path of the resulting overlayfs layer.

type Mount

type Mount interface {
	Mount() error
	Unmount() error
}

A Mount of a filesystem.

func DefaultNewOverlayMount

func DefaultNewOverlayMount(path string, parentLayerPaths []string) Mount

DefaultNewOverlayMount is the default OverlayMount created by NewLayerWorkdir.

type NewLayerWorkdirOption

type NewLayerWorkdirOption func(*WorkDirOptions)

NewLayerWorkdirOption configures how a new layer workdir is created.

func WithNewOverlayMountFn

func WithNewOverlayMountFn(fn NewOverlayMountFn) NewLayerWorkdirOption

WithNewOverlayMountFn configures how a new layer workdir creates an overlay mount.

type NewOverlayMountFn

type NewOverlayMountFn func(path string, parentLayerPaths []string) Mount

NewOverlayMountFn creates an overlay mount.

type OverlayMount

type OverlayMount struct {
	Mountpoint string
	Lower      []string
	Upper      string
	Work       string
}

An OverlayMount represents a mount of type overlay.

func (OverlayMount) Mount

func (m OverlayMount) Mount() error

Mount the overlay mount.

func (OverlayMount) Unmount

func (m OverlayMount) Unmount() error

Unmount the overlay mount.

type RuntimeSpecWriter

type RuntimeSpecWriter interface {
	// Write and write an OCI runtime spec to the supplied path.
	Write(path string, o ...spec.Option) error
}

A RuntimeSpecWriter writes an OCI runtime spec to the supplied path.

type RuntimeSpecWriterFn

type RuntimeSpecWriterFn func(path string, o ...spec.Option) error

A RuntimeSpecWriterFn allows a function to satisfy RuntimeSpecCreator.

func (RuntimeSpecWriterFn) Write

func (fn RuntimeSpecWriterFn) Write(path string, o ...spec.Option) error

Write an OCI runtime spec to the supplied path.

type TarballApplicator

type TarballApplicator interface {
	// Apply the supplied tarball - an OCI filesystem layer - to the supplied
	// root directory. Applying all of an image's layers, in the correct order,
	// should produce the image's "flattened" filesystem.
	Apply(ctx context.Context, tb io.Reader, root string) error
}

A TarballApplicator applies (i.e. extracts) an OCI layer tarball. https://github.com/opencontainers/image-spec/blob/v1.0/layer.md

type TmpFSMount

type TmpFSMount struct {
	Mountpoint string
}

A TmpFSMount represents a mount of type tmpfs.

func (TmpFSMount) Mount

func (m TmpFSMount) Mount() error

Mount the tmpfs mount.

func (TmpFSMount) Unmount

func (m TmpFSMount) Unmount() error

Unmount the tmpfs mount.

type WorkDirOptions

type WorkDirOptions struct {
	NewOverlayMount NewOverlayMountFn
}

WorkDirOptions configure how a new layer workdir is created.