package hcsoci

import "github.com/Microsoft/hcsshim/internal/hcsoci"

Index

Constants 

const (
	UnmountOperationSCSI  UnmountOperation = 0x01
	UnmountOperationVSMB                   = 0x02
	UnmountOperationVPMEM                  = 0x04
	UnmountOperationAll                    = UnmountOperationSCSI | UnmountOperationVSMB | UnmountOperationVPMEM
)

Functions

func ExecInUvm 

func ExecInUvm(ctx context.Context, vm *uvm.UtilityVM, req *shimdiag.ExecProcessRequest) (int, error)

func GetNamespaceEndpoints 

func GetNamespaceEndpoints(ctx context.Context, netNS string) ([]*hns.HNSEndpoint, error)

GetNamespaceEndpoints gets all endpoints in `netNS`

func MountContainerLayers 

func MountContainerLayers(ctx context.Context, layerFolders []string, guestRoot string, uvm *uvmpkg.UtilityVM) (_ string, err error)

MountContainerLayers is a helper for clients to hide all the complexity of layer mounting Layer folder are in order: base, [rolayer1..rolayern,] scratch

v1/v2: Argon WCOW: Returns the mount path on the host as a volume GUID. v1: Xenon WCOW: Done internally in HCS, so no point calling doing anything here. v2: Xenon WCOW: Returns a CombinedLayersV2 structure where ContainerRootPath is a folder 

inside the utility VM which is a GUID mapping of the scratch folder. Each
of the layers are the VSMB locations where the read-only layers are mounted.

TODO dcantah: Keep better track of the layers that are added, don't simply discard the SCSI, VSMB, etc. resource types gotten inside.

func ReleaseResources 

func ReleaseResources(ctx context.Context, r *Resources, vm *uvm.UtilityVM, all bool) error

ReleaseResources releases/frees all of the resources associated with a container. This includes Plan9 shares, vsmb mounts, pipe mounts, network endpoints, scsi mounts, vpci devices and layers. TODO: make method on Resources struct.

func UnmountContainerLayers 

func UnmountContainerLayers(ctx context.Context, layerFolders []string, containerRootPath string, uvm *uvmpkg.UtilityVM, op UnmountOperation) error

UnmountContainerLayers is a helper for clients to hide all the complexity of layer unmounting

Types

type AutoManagedVHD 

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

AutoManagedVHD struct representing a VHD that will be cleaned up automatically.

func (*AutoManagedVHD) Release 

func (vhd *AutoManagedVHD) Release(ctx context.Context) error

Release removes the vhd.

type Cmd 

type Cmd struct {
	// Host is the process host in which to launch the process.
	Host cow.ProcessHost

	// The OCI spec for the process.
	Spec *specs.Process

	// Standard IO streams to relay to/from the process.
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer

	// Log provides a logrus entry to use in logging IO copying status.
	Log *logrus.Entry

	// Context provides a context that terminates the process when it is done.
	Context context.Context

	// CopyAfterExitTimeout is the amount of time after process exit we allow the
	// stdout, stderr relays to continue before forcibly closing them if not
	// already completed. This is primarily a safety step against the HCS when
	// it fails to send a close on the stdout, stderr pipes when the process
	// exits and blocks the relay wait groups forever.
	CopyAfterExitTimeout time.Duration

	// Process is filled out after Start() returns.
	Process cow.Process

	// ExitState is filled out after Wait() (or Run() or Output()) completes.
	ExitState *ExitState
	// contains filtered or unexported fields
}

Cmd represents a command being prepared or run in a process host.

func Command 

func Command(host cow.ProcessHost, name string, arg ...string) *Cmd

Command makes a Cmd for a given command and arguments.

func CommandContext 

func CommandContext(ctx context.Context, host cow.ProcessHost, name string, arg ...string) *Cmd

CommandContext makes a Cmd for a given command and arguments. After it is launched, the process is killed when the context becomes done.

func (*Cmd) Output 

func (c *Cmd) Output() ([]byte, error)

Output runs a command via Run and collects its stdout into a buffer, which it returns.

func (*Cmd) Run 

func (c *Cmd) Run() error

Run is equivalent to Start followed by Wait.

func (*Cmd) Start 

func (c *Cmd) Start() error

Start starts a command. The caller must ensure that if Start succeeds, Wait is eventually called to clean up resources.

func (*Cmd) Wait 

func (c *Cmd) Wait() error

Wait waits for a command and its IO to complete and closes the underlying process. It can only be called once. It returns an ExitError if the command runs and returns a non-zero exit code.

type CreateOptions 

type CreateOptions struct {

	// Common parameters
	ID               string             // Identifier for the container
	Owner            string             // Specifies the owner. Defaults to executable name.
	Spec             *specs.Spec        // Definition of the container or utility VM being created
	SchemaVersion    *hcsschema.Version // Requested Schema Version. Defaults to v2 for RS5, v1 for RS1..RS4
	HostingSystem    *uvm.UtilityVM     // Utility or service VM in which the container is to be created.
	NetworkNamespace string             // Host network namespace to use (overrides anything in the spec)

	// This is an advanced debugging parameter. It allows for diagnosibility by leaving a containers
	// resources allocated in case of a failure. Thus you would be able to use tools such as hcsdiag
	// to look at the state of a utility VM to see what resources were allocated. Obviously the caller
	// must a) not tear down the utility VM on failure (or pause in some way) and b) is responsible for
	// performing the ReleaseResources() call themselves.
	DoNotReleaseResourcesOnFailure bool
}

CreateOptions are the set of fields used to call CreateContainer(). Note: In the spec, the LayerFolders must be arranged in the same way in which moby configures them: layern, layern-1,...,layer2,layer1,scratch where layer1 is the base read-only layer, layern is the top-most read-only layer, and scratch is the RW layer. This is for historical reasons only.

type ExitError 

type ExitError struct {
	*ExitState
}

ExitError is used when a process exits with a non-zero exit code.

func (*ExitError) Error 

func (err *ExitError) Error() string

type ExitState 

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

ExitState contains whether a process has exited and with which exit code.

func (*ExitState) ExitCode 

func (s *ExitState) ExitCode() int

ExitCode returns the exit code of the process, or -1 if the exit code is not known.

type ImageLayers 

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

ImageLayers contains all the layers for an image.

func (*ImageLayers) Release 

func (layers *ImageLayers) Release(ctx context.Context, all bool) error

Release unmounts all of the layers located in the layers array.

type ResourceCloser 

type ResourceCloser interface {
	Release(context.Context) error
}

ResourceCloser is a generic interface for the releasing of a resource. If a resource implements this interface(which they all should), freeing of that resource should entail one call to <resourceName>.Release(ctx)

type Resources 

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

Resources is the structure returned as part of creating a container. It holds nothing useful to clients, hence everything is lowercased. A client would use it in a call to ReleaseResources to ensure everything is cleaned up when a container exits.

func CreateContainer 

func CreateContainer(ctx context.Context, createOptions *CreateOptions) (_ cow.Container, _ *Resources, err error)

CreateContainer creates a container. It can cope with a wide variety of scenarios, including v1 HCS schema calls, as well as more complex v2 HCS schema calls. Note we always return the resources that have been allocated, even in the case of an error. This provides support for the debugging option not to release the resources on failure, so that the client can make the necessary call to release resources that have been allocated as part of calling this function.

func (*Resources) NetNS 

func (r *Resources) NetNS() string

NetNS returns the network namespace for the container

type UnmountOperation 

type UnmountOperation uint

UnmountOperation is used when calling Unmount() to determine what type of unmount is required. In V1 schema, this must be unmountOperationAll. In V2, client can be more optimal and only unmount what they need which can be a minor performance improvement (eg if you know only one container is running in a utility VM, and the UVM is about to be torn down, there's no need to unmount the VSMB shares, just SCSI to have a consistent file system).

type UpstreamIO 

type UpstreamIO interface {
	// Close closes all open io.
	//
	// This call is idempotent and safe to call multiple times.
	Close(ctx context.Context)
	// CloseStdin closes just `Stdin()` if open.
	//
	// This call is idempotent and safe to call multiple times.
	CloseStdin(ctx context.Context)
	// Stdin returns the open `stdin` reader. If `stdin` was never opened this
	// will return `nil`.
	Stdin() io.Reader
	// StdinPath returns the original path used to open the `Stdin()` reader.
	StdinPath() string
	// Stdout returns the open `stdout` writer. If `stdout` was never opened
	// this will return `nil`.
	Stdout() io.Writer
	// StdoutPath returns the original path used to open the `Stdout()` writer.
	StdoutPath() string
	// Stderr returns the open `stderr` writer. If `stderr` was never opened
	// this will return `nil`.
	Stderr() io.Writer
	// StderrPath returns the original path used to open the `Stderr()` writer.
	StderrPath() string
	// Terminal returns `true` if the connection is emulating a terminal. If
	// `true` `Stderr()` will always return `nil` and `StderrPath()` will always
	// return `""`.
	Terminal() bool
}

UpstreamIO is an interface describing the IO to connect to above the shim. Depending on the callers settings there may be no opened IO.

func NewNpipeIO 

func NewNpipeIO(ctx context.Context, stdin, stdout, stderr string, terminal bool) (_ UpstreamIO, err error)

NewNpipeIO creates connected upstream io. It is the callers responsibility to validate that `if terminal == true`, `stderr == ""`.

Source Files

cmd.go create.go diag.go hcsdoc_lcow.go hcsdoc_wcow.go io.go io_npipe.go layers.go network.go resources.go resources_lcow.go resources_wcow.go

Version
v0.8.9
Published
Apr 28, 2020
Platform
windows/amd64
Imports
38 packages
Last checked
51 minutes ago –

Tools for package owners.