layer

README

umoci/oci/layer

This is my own implementation of the currently under development oci-create-layer functions. The reason for implementing this myself is that we use mtree specifications which are not the same method that oci-create-layer uses. While the two implementations could be combined (since this implementation is more general), in order to speed things up I just decided to implement it myself.

This also implements oci-create-runtime-bundle, since it's under layer management. The real difference is that we've split up the API (and based it on CAS) so we have more control when generating the bundle.

I'm hoping that this will be merged upstream, but since it's just a whiteout tar archive generator there isn't a huge requirement that this is kept up to date. Though, it should be noted that the whiteout format may change in the future.

Documentation

Index

• Constants
• func CleanPath(path string) string
• func GenerateInsertLayer(root string, target string, opaque bool, opt *RepackOptions) io.ReadCloser
• func GenerateLayer(path string, deltas []mtree.InodeDelta, opt *RepackOptions) (io.ReadCloser, error)
• func InnerErrno(err error) error
• func UnpackLayer(root string, layer io.Reader, opt *UnpackOptions) error
• func UnpackManifest(ctx context.Context, engine cas.Engine, bundle string, manifest ispec.Manifest, ...) (err error)
• func UnpackRootfs(ctx context.Context, engine cas.Engine, rootfsPath string, ...) (err error)
• func UnpackRuntimeJSON(ctx context.Context, engine cas.Engine, configFile io.Writer, rootfs string, ...) error
• type AfterLayerUnpackCallback
• type MapOptions
• type RepackOptions
• type TarExtractor
  • func NewTarExtractor(opt UnpackOptions) *TarExtractor
  • func (te *TarExtractor) UnpackEntry(root string, hdr *tar.Header, r io.Reader) (Err error)
• type UnpackOptions
• type WhiteoutMode

Constants

const RootfsName = "rootfs"

RootfsName is the name of the rootfs directory inside the bundle path when generated.

Functions

func CleanPath

func CleanPath(path string) string

CleanPath makes a path safe for use with filepath.Join. This is done by not only cleaning the path, but also (if the path is relative) adding a leading '/' and cleaning it (then removing the leading '/'). This ensures that a path resulting from prepending another path will always resolve to lexically be a subdirectory of the prefixed path. This is all done lexically, so paths that include symlinks won't be safe as a result of using CleanPath.

This function comes from runC (libcontainer/utils/utils.go).

func GenerateInsertLayer

func GenerateInsertLayer(root string, target string, opaque bool, opt *RepackOptions) io.ReadCloser

GenerateInsertLayer generates a completely new layer from "root"to be inserted into the image at "target". If "root" is an empty string then the "target" will be removed via a whiteout.

func GenerateLayer

func GenerateLayer(path string, deltas []mtree.InodeDelta, opt *RepackOptions) (io.ReadCloser, error)

GenerateLayer creates a new OCI diff layer based on the mtree diff provided. All of the mtree.Modified and mtree.Extra blobs are read relative to the provided path (which should be the rootfs of the layer that was diffed). The returned reader is for the *raw* tar data, it is the caller's responsibility to gzip it.

func InnerErrno

func InnerErrno(err error) error

InnerErrno returns the "real" system error from an error that originally came from the "os" package. The returned error can be compared directly with unix.* (or syscall.*) errno values. If the type could not be detected we just return

func UnpackLayer

func UnpackLayer(root string, layer io.Reader, opt *UnpackOptions) error

UnpackLayer unpacks the tar stream representing an OCI layer at the given root. It ensures that the state of the root is as close as possible to the state used to create the layer. If an error is returned, the state of root is undefined (unpacking is not guaranteed to be atomic).

func UnpackManifest

func UnpackManifest(ctx context.Context, engine cas.Engine, bundle string, manifest ispec.Manifest, opt *UnpackOptions) (err error)

UnpackManifest extracts all of the layers in the given manifest, as well as generating a runtime bundle and configuration. The rootfs is extracted to <bundle>/<layer.RootfsName>.

FIXME: This interface is ugly.

func UnpackRootfs

func UnpackRootfs(ctx context.Context, engine cas.Engine, rootfsPath string, manifest ispec.Manifest, opt *UnpackOptions) (err error)

UnpackRootfs extracts all of the layers in the given manifest. Some verification is done during image extraction.

func UnpackRuntimeJSON

func UnpackRuntimeJSON(ctx context.Context, engine cas.Engine, configFile io.Writer, rootfs string, manifest ispec.Manifest, opt *MapOptions) error

UnpackRuntimeJSON converts a given manifest's configuration to a runtime configuration and writes it to the given writer. If rootfs is specified, it is sourced during the configuration generation (for conversion of Config.User and other similar jobs -- which will error out if the user could not be parsed). If rootfs is not specified (is an empty string) then all conversions that require sourcing the rootfs will be set to their default values.

XXX: I don't like this API. It has way too many arguments.

Types

type AfterLayerUnpackCallback

type AfterLayerUnpackCallback func(manifest ispec.Manifest, desc ispec.Descriptor) error

AfterLayerUnpackCallback is called after each layer is unpacked.

type MapOptions

type MapOptions struct {
	// UIDMappings and GIDMappings are the UID and GID mappings to apply when
	// packing and unpacking image rootfs layers.
	UIDMappings []rspec.LinuxIDMapping `json:"uid_mappings"`
	GIDMappings []rspec.LinuxIDMapping `json:"gid_mappings"`

	// Rootless specifies whether any to error out if chown fails.
	Rootless bool `json:"rootless"`
}

MapOptions specifies the UID and GID mappings used when unpacking and repacking images.

type RepackOptions

type RepackOptions struct {
	// MapOptions are the UID and GID mappings used when unpacking an image
	MapOptions MapOptions

	// TranslateOverlayWhiteouts changes char devices of type 0,0 to
	// .wh.foo style whiteouts when generating tarballs. Without this,
	// whiteouts are untouched.
	TranslateOverlayWhiteouts bool
}

RepackOptions describes the behavior of the various GenerateLayer operations.

type TarExtractor

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

TarExtractor represents a tar file to be extracted.

func NewTarExtractor

func NewTarExtractor(opt UnpackOptions) *TarExtractor

NewTarExtractor creates a new TarExtractor.

func (*TarExtractor) UnpackEntry

func (te *TarExtractor) UnpackEntry(root string, hdr *tar.Header, r io.Reader) (Err error)

UnpackEntry extracts the given tar.Header to the provided root, ensuring that the layer state is consistent with the layer state that produced the tar archive being iterated over. This does handle whiteouts, so a tar.Header that represents a whiteout will result in the path being removed.

type UnpackOptions

type UnpackOptions struct {
	// MapOptions are the UID and GID mappings used when unpacking an image
	MapOptions MapOptions

	// KeepDirlinks is essentially the same as rsync's optio
	// --keep-dirlinks: if, on extraction, a directory would be created
	// where a symlink to a directory previously existed, KeepDirlinks
	// doesn't create that directory, but instead just uses the existing
	// symlink.
	KeepDirlinks bool

	// AfterLayerUnpack is a function that's called after every layer is
	// unpacked.
	AfterLayerUnpack AfterLayerUnpackCallback

	// StartFrom is the descriptor in the manifest to start from
	StartFrom ispec.Descriptor

	// WhiteoutMode is the type of whiteout to write to the filesystem.
	WhiteoutMode WhiteoutMode
}

UnpackOptions describes the behavior of the various unpack operations.

type WhiteoutMode

type WhiteoutMode int

WhiteoutMode indicates how this TarExtractor will create whiteouts on the filesystem when it encounters them.

const (
	// OCIStandardWhiteout does the standard OCI thing: a file named
	// .wh.foo indicates you should rm -rf foo.
	OCIStandardWhiteout WhiteoutMode = iota

	// OverlayFSWhiteout generates a rootfs suitable for use in overlayfs,
	// so it follows the overlayfs whiteout protocol:
	//     .wh.foo => mknod c 0 0 foo
	OverlayFSWhiteout
)