wclayer

Documentation

Overview

Package wclayer provides bindings to HCS's legacy layer management API and provides a higher level interface around these calls for container layer management.

Index

• func ActivateLayer(ctx context.Context, path string) (err error)
• func CreateLayer(ctx context.Context, path, parent string) (err error)
• func CreateScratchLayer(ctx context.Context, path string, parentLayerPaths []string) (err error)
• func DeactivateLayer(ctx context.Context, path string) (err error)
• func DestroyLayer(ctx context.Context, path string) (err error)
• func ExpandScratchSize(ctx context.Context, path string, size uint64) (err error)
• func ExportLayer(ctx context.Context, path string, exportFolderPath string, ...) (err error)
• func GetLayerMountPath(ctx context.Context, path string) (_ string, err error)
• func GetSharedBaseImages(ctx context.Context) (_ string, err error)
• func GrantVmAccess(ctx context.Context, vmid string, filepath string) (err error)
• func ImportLayer(ctx context.Context, path string, importFolderPath string, ...) (err error)
• func LayerExists(ctx context.Context, path string) (_ bool, err error)
• func LayerID(ctx context.Context, path string) (_ guid.GUID, err error)
• func NameToGuid(ctx context.Context, name string) (_ guid.GUID, err error)
• func PrepareLayer(ctx context.Context, path string, parentLayerPaths []string) (err error)
• func ProcessBaseLayer(ctx context.Context, path string) (err error)
• func ProcessUtilityVMImage(ctx context.Context, path string) (err error)
• func UnprepareLayer(ctx context.Context, path string) (err error)
• type LayerReader
  • func NewLayerReader(ctx context.Context, path string, parentLayerPaths []string) (_ LayerReader, err error)
• type LayerWriter
  • func NewLayerWriter(ctx context.Context, path string, parentLayerPaths []string) (_ LayerWriter, err error)
• type WC_LAYER_DESCRIPTOR

Functions

func ActivateLayer

func ActivateLayer(ctx context.Context, path string) (err error)

ActivateLayer will find the layer with the given id and mount it's filesystem. For a read/write layer, the mounted filesystem will appear as a volume on the host, while a read-only layer is generally expected to be a no-op. An activated layer must later be deactivated via DeactivateLayer.

func CreateLayer

func CreateLayer(ctx context.Context, path, parent string) (err error)

CreateLayer creates a new, empty, read-only layer on the filesystem based on the parent layer provided.

func CreateScratchLayer

func CreateScratchLayer(ctx context.Context, path string, parentLayerPaths []string) (err error)

CreateScratchLayer creates and populates new read-write layer for use by a container. This requires the full list of paths to all parent layers up to the base

func DeactivateLayer

func DeactivateLayer(ctx context.Context, path string) (err error)

DeactivateLayer will dismount a layer that was mounted via ActivateLayer.

func DestroyLayer

func DestroyLayer(ctx context.Context, path string) (err error)

DestroyLayer will remove the on-disk files representing the layer with the given path, including that layer's containing folder, if any.

func ExpandScratchSize

func ExpandScratchSize(ctx context.Context, path string, size uint64) (err error)

ExpandScratchSize expands the size of a layer to at least size bytes.

func ExportLayer

func ExportLayer(ctx context.Context, path string, exportFolderPath string, parentLayerPaths []string) (err error)

ExportLayer will create a folder at exportFolderPath and fill that folder with the transport format version of the layer identified by layerId. This transport format includes any metadata required for later importing the layer (using ImportLayer), and requires the full list of parent layer paths in order to perform the export.

func GetLayerMountPath

func GetLayerMountPath(ctx context.Context, path string) (_ string, err error)

GetLayerMountPath will look for a mounted layer with the given path and return the path at which that layer can be accessed. This path may be a volume path if the layer is a mounted read-write layer, otherwise it is expected to be the folder path at which the layer is stored.

func GetSharedBaseImages

func GetSharedBaseImages(ctx context.Context) (_ string, err error)

GetSharedBaseImages will enumerate the images stored in the common central image store and return descriptive info about those images for the purpose of registering them with the graphdriver, graph, and tagstore.

func GrantVmAccess

func GrantVmAccess(ctx context.Context, vmid string, filepath string) (err error)

GrantVmAccess adds access to a file for a given VM

func ImportLayer

func ImportLayer(ctx context.Context, path string, importFolderPath string, parentLayerPaths []string) (err error)

ImportLayer will take the contents of the folder at importFolderPath and import that into a layer with the id layerId. Note that in order to correctly populate the layer and interperet the transport format, all parent layers must already be present on the system at the paths provided in parentLayerPaths.

func LayerExists

func LayerExists(ctx context.Context, path string) (_ bool, err error)

LayerExists will return true if a layer with the given id exists and is known to the system.

func LayerID

func LayerID(ctx context.Context, path string) (_ guid.GUID, err error)

LayerID returns the layer ID of a layer on disk.

func NameToGuid

func NameToGuid(ctx context.Context, name string) (_ guid.GUID, err error)

NameToGuid converts the given string into a GUID using the algorithm in the Host Compute Service, ensuring GUIDs generated with the same string are common across all clients.

func PrepareLayer

func PrepareLayer(ctx context.Context, path string, parentLayerPaths []string) (err error)

PrepareLayer finds a mounted read-write layer matching path and enables the the filesystem filter for use on that layer. This requires the paths to all parent layers, and is necessary in order to view or interact with the layer as an actual filesystem (reading and writing files, creating directories, etc). Disabling the filter must be done via UnprepareLayer.

func ProcessBaseLayer

func ProcessBaseLayer(ctx context.Context, path string) (err error)

ProcessBaseLayer post-processes a base layer that has had its files extracted. The files should have been extracted to <path>\Files.

func ProcessUtilityVMImage

func ProcessUtilityVMImage(ctx context.Context, path string) (err error)

ProcessUtilityVMImage post-processes a utility VM image that has had its files extracted. The files should have been extracted to <path>\Files.

func UnprepareLayer

func UnprepareLayer(ctx context.Context, path string) (err error)

UnprepareLayer disables the filesystem filter for the read-write layer with the given id.

Types

type LayerReader

type LayerReader interface {
	Next() (string, int64, *winio.FileBasicInfo, error)
	Read(b []byte) (int, error)
	Close() error
}

func NewLayerReader

func NewLayerReader(ctx context.Context, path string, parentLayerPaths []string) (_ LayerReader, err error)

NewLayerReader returns a new layer reader for reading the contents of an on-disk layer. The caller must have taken the SeBackupPrivilege privilege to call this and any methods on the resulting LayerReader.

type LayerWriter

type LayerWriter interface {
	// Add adds a file to the layer with given metadata.
	Add(name string, fileInfo *winio.FileBasicInfo) error
	// AddLink adds a hard link to the layer. The target must already have been added.
	AddLink(name string, target string) error
	// Remove removes a file that was present in a parent layer from the layer.
	Remove(name string) error
	// Write writes data to the current file. The data must be in the format of a Win32
	// backup stream.
	Write(b []byte) (int, error)
	// Close finishes the layer writing process and releases any resources.
	Close() error
}

LayerWriter is an interface that supports writing a new container image layer.

func NewLayerWriter

func NewLayerWriter(ctx context.Context, path string, parentLayerPaths []string) (_ LayerWriter, err error)

NewLayerWriter returns a new layer writer for creating a layer on disk. The caller must have taken the SeBackupPrivilege and SeRestorePrivilege privileges to call this and any methods on the resulting LayerWriter.

type WC_LAYER_DESCRIPTOR

type WC_LAYER_DESCRIPTOR struct {
	LayerId guid.GUID
	Flags   uint32
	Pathp   *uint16
}

To pass into syscall, we need a struct matching the following:

typedef struct _WC_LAYER_DESCRIPTOR {

//
// The ID of the layer
//

GUID LayerId;

//
// Additional flags
//

union {
    struct {
        ULONG Reserved : 31;
        ULONG Dirty : 1;    // Created from sandbox as a result of snapshot
    };
    ULONG Value;
} Flags;

//
// Path to the layer root directory, null-terminated
//

PCWSTR Path;

} WC_LAYER_DESCRIPTOR, *PWC_LAYER_DESCRIPTOR;