containerd

package module
v1.0.0-beta.2 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2017 License: Apache-2.0, CC-BY-SA-4.0 Imports: 66 Imported by: 0

README

banner

GoDoc Build Status FOSSA Status Go Report Card

containerd is an industry-standard container runtime with an emphasis on simplicity, robustness and portability. It is available as a daemon for Linux and Windows, which can manage the complete container lifecycle of its host system: image transfer and storage, container execution and supervision, low-level storage and network attachments, etc.

containerd is designed to be embedded into a larger system, rather than being used directly by developers or end-users.

architecture

Getting Started

If you are interested in trying out containerd please see our Getting Started Guide.

Features

Client

containerd offers a full client package to help you integrate containerd into your platform.


import "github.com/containerd/containerd"

func main() {
	client, err := containerd.New("/run/containerd/containerd.sock")
	defer client.Close()
}

Namespaces

Namespaces allow multiple consumers to use the same containerd without conflicting with each other. It has the benefit of sharing content but still having separation with containers and images.

To set a namespace for requests to the API:

context    = context.Background()
// create a context for docker
docker = namespaces.WithNamespace(context, "docker")

containerd, err := client.NewContainer(docker, "id")

To set a default namespace on the client:

client, err := containerd.New(address, containerd.WithDefaultNamespace("docker"))

Distribution

// pull an image
image, err := client.Pull(context, "docker.io/library/redis:latest")

// push an image
err := client.Push(context, "docker.io/library/redis:latest", image.Target())

Containers

In containerd, a container is a metadata object. Resources such as an OCI runtime specification, image, root filesystem, and other metadata can be attached to a container.

redis, err := client.NewContainer(context, "redis-master")
defer redis.Delete(context)

OCI Runtime Specification

containerd fully supports the OCI runtime specification for running containers. We have built in functions to help you generate runtime specifications based on images as well as custom parameters.

You can specify options when creating a container about how to modify the specification.

redis, err := client.NewContainer(context, "redis-master", containerd.WithNewSpec(containerd.WithImageConfig(image)))

Root Filesystems

containerd allows you to use overlay or snapshot filesystems with your containers. It comes with builtin support for overlayfs and btrfs.

// pull an image and unpack it into the configured snapshotter
image, err := client.Pull(context, "docker.io/library/redis:latest", containerd.WithPullUnpack)

// allocate a new RW root filesystem for a container based on the image
redis, err := client.NewContainer(context, "redis-master",
	containerd.WithNewSnapshot("redis-rootfs", image),
	containerd.WithNewSpec(containerd.WithImageConfig(image)),

)

// use a readonly filesystem with multiple containers
for i := 0; i < 10; i++ {
	id := fmt.Sprintf("id-%s", i)
	container, err := client.NewContainer(ctx, id,
		containerd.WithNewSnapshotView(id, image),
		containerd.WithNewSpec(containerd.WithImageConfig(image)),
	)
}

Tasks

Taking a container object and turning it into a runnable process on a system is done by creating a new Task from the container. A task represents the runnable object within containerd.

// create a new task
task, err := redis.NewTask(context, containerd.Stdio)
defer task.Delete(context)

// the task is now running and has a pid that can be use to setup networking
// or other runtime settings outside of containerd
pid := task.Pid()

// start the redis-server process inside the container
err := task.Start(context)

// wait for the task to exit and get the exit status
status, err := task.Wait(context)

Checkpoint and Restore

If you have criu installed on your machine you can checkpoint and restore containers and their tasks. This allow you to clone and/or live migrate containers to other machines.

// checkpoint the task then push it to a registry
checkpoint, err := task.Checkpoint(context, containerd.WithExit)

err := client.Push(context, "myregistry/checkpoints/redis:master", checkpoint)

// on a new machine pull the checkpoint and restore the redis container
image, err := client.Pull(context, "myregistry/checkpoints/redis:master")

checkpoint := image.Target()

redis, err = client.NewContainer(context, "redis-master", containerd.WithCheckpoint(checkpoint, "redis-rootfs"))
defer container.Delete(context)

task, err = redis.NewTask(context, containerd.Stdio, containerd.WithTaskCheckpoint(checkpoint))
defer task.Delete(context)

err := task.Start(context)

Developer Quick-Start

To build the daemon and ctr simple test client, the following build system dependencies are required:

  • Go 1.8.x or above (requires 1.8 due to use of golang plugin(s))
  • Protoc 3.x compiler and headers (download at the Google protobuf releases page)
  • Btrfs headers and libraries for your distribution. Note that building the btrfs driver can be disabled via build tag removing this dependency.

For proper results, install the protoc release into /usr/local on your build system. For example, the following commands will download and install the 3.1.0 release for a 64-bit Linux host:

$ wget -c https://github.com/google/protobuf/releases/download/v3.1.0/protoc-3.1.0-linux-x86_64.zip
$ sudo unzip protoc-3.1.0-linux-x86_64.zip -d /usr/local

With the required dependencies installed, the Makefile target named binaries will compile the ctr and containerd binaries and place them in the bin/ directory. Using sudo make install will place the binaries in /usr/local/bin. When making any changes to the gRPC API, make generate will use the installed protoc compiler to regenerate the API generated code packages.

Note: A build tag is currently available to disable building the btrfs snapshot driver. Adding BUILDTAGS=no_btrfs to your environment before calling the binaries Makefile target will disable the btrfs driver within the containerd Go build.

Vendoring of external imports uses the vndr tool which uses a simple config file, vendor.conf, to provide the URL and version or hash details for each vendored import. After modifying vendor.conf run the vndr tool to update the vendor/ directory contents. Combining the vendor.conf update with the changeset in vendor/ after running vndr should become a single commit for a PR which relies on vendored updates.

Please refer to RUNC.md for the currently supported version of runc that is used by containerd.

Releases and API Stability

Please see RELEASES.md for details on versioning and stability of containerd components.

Development reports.

Weekly summary on the progress and what is being worked on. https://github.com/containerd/containerd/tree/master/reports

Communication

For async communication and long running discussions please use issues and pull requests on the github repo. This will be the best place to discuss design and implementation.

For sync communication we have a community slack with a #containerd channel that everyone is welcome to join and chat about development.

Slack: https://dockr.ly/community

Reporting security issues

If you are reporting a security issue, please reach out discreetly at containerd-security@googlegroups.com.

Copyright ©2016-2017 Docker, Inc. All rights reserved, except as follows. Code is released under the Apache 2.0 license. The README.md file, and files in the "docs" folder are licensed under the Creative Commons Attribution 4.0 International License under the terms and conditions set forth in the file "LICENSE.docs". You may obtain a duplicate copy of the same license, titled CC-BY-SA-4.0, at http://creativecommons.org/licenses/by/4.0/.

Documentation

Index

Constants

View Source 
const (
	// DefaultSnapshotter will set the default snapshotter for the platform.
	// This will be based on the client compilation target, so take that into
	// account when choosing this value.
	DefaultSnapshotter = "overlayfs"
)
View Source 
const UnknownExitStatus = 255

UnknownExitStatus is returned when containerd is unable to determine the exit status of a process. This can happen if the process never starts or if an error was encountered when obtaining the exit status, it is set to 255.

Variables

This section is empty.

Functions

func DialAddress 

func DialAddress(address string) string

DialAddress returns the address with unix:// prepended to the provided address

func Dialer 

func Dialer(address string, timeout time.Duration) (net.Conn, error)

Dialer returns a GRPC net.Conn connected to the provided address

func GenerateSpec 

func GenerateSpec(ctx context.Context, client *Client, c *containers.Container, opts ...SpecOpts) (*specs.Spec, error)

GenerateSpec will generate a default spec from the provided image for use as a containerd container

func NewRemoteContainerStore added in v1.0.0 

func NewRemoteContainerStore(client containersapi.ContainersClient) containers.Store

NewRemoteContainerStore returns the container Store connected with the provided client

func WithExit added in v1.0.0 

func WithExit(r *CheckpointTaskInfo) error

WithExit causes the task to exit after a successful checkpoint

func WithHostHostsFile 

func WithHostHostsFile(_ context.Context, _ *Client, _ *containers.Container, s *specs.Spec) error

WithHostHostsFile bind-mounts the host's /etc/hosts into the container as readonly

func WithHostLocaltime 

func WithHostLocaltime(_ context.Context, _ *Client, _ *containers.Container, s *specs.Spec) error

WithHostLocaltime bind-mounts the host's /etc/localtime into the container as readonly

func WithHostResolvconf 

func WithHostResolvconf(_ context.Context, _ *Client, _ *containers.Container, s *specs.Spec) error

WithHostResolvconf bind-mounts the host's /etc/resolv.conf into the container as readonly

func WithKillAll added in v1.0.0 

func WithKillAll(ctx context.Context, p Process, i *KillInfo) error

WithKillAll kills all processes for a task

func WithNoNewPrivileges 

func WithNoNewPrivileges(_ context.Context, _ *Client, _ *containers.Container, s *specs.Spec) error

WithNoNewPrivileges sets no_new_privileges on the process for the container

func WithProcessKill added in v1.0.0 

func WithProcessKill(ctx context.Context, p Process) error

WithProcessKill will forcefully kill and delete a process

func WithPullUnpack added in v1.0.0 

func WithPullUnpack(_ *Client, c *RemoteContext) error

WithPullUnpack is used to unpack an image after pull. This uses the snapshotter, content store, and diff service configured for the client.

func WithSchema1Conversion added in v1.0.0 

func WithSchema1Conversion(client *Client, c *RemoteContext) error

WithSchema1Conversion is used to convert Docker registry schema 1 manifests to oci manifests on pull. Without this option schema 1 manifests will return a not supported error.

func WithSnapshotCleanup added in v1.0.0 

func WithSnapshotCleanup(ctx context.Context, client *Client, c containers.Container) error

WithSnapshotCleanup deletes the rootfs snapshot allocated for the container

func WithStdinCloser added in v1.0.0 

func WithStdinCloser(r *IOCloseInfo)

WithStdinCloser closes the stdin of a process

func WithTTY 

func WithTTY(_ context.Context, _ *Client, _ *containers.Container, s *specs.Spec) error

WithTTY sets the information on the spec as well as the environment variables for using a TTY

Types

type CheckpointTaskInfo added in v1.0.0 

type CheckpointTaskInfo struct {
	// ParentCheckpoint is the digest of a parent checkpoint
	ParentCheckpoint digest.Digest
	// Options hold runtime specific settings for checkpointing a task
	Options interface{}
}

CheckpointTaskInfo allows specific checkpoint information to be set for the task

type CheckpointTaskOpts added in v1.0.0 

type CheckpointTaskOpts func(*CheckpointTaskInfo) error

CheckpointTaskOpts allows the caller to set checkpoint options

type Client added in v1.0.0 

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

Client is the client to interact with containerd and its various services using a uniform interface

func New added in v1.0.0 

func New(address string, opts ...ClientOpt) (*Client, error)

New returns a new containerd client that is connected to the containerd instance provided by address

func NewWithConn added in v1.0.0 

func NewWithConn(conn *grpc.ClientConn, opts ...ClientOpt) (*Client, error)

NewWithConn returns a new containerd client that is connected to the containerd instance provided by the connection

func (*Client) Close added in v1.0.0 

func (c *Client) Close() error

Close closes the clients connection to containerd

func (*Client) ContainerService added in v1.0.0 

func (c *Client) ContainerService() containers.Store

ContainerService returns the underlying container Store

func (*Client) Containers added in v1.0.0 

func (c *Client) Containers(ctx context.Context, filters ...string) ([]Container, error)

Containers returns all containers created in containerd

func (*Client) ContentStore added in v1.0.0 

func (c *Client) ContentStore() content.Store

ContentStore returns the underlying content Store

func (*Client) DiffService added in v1.0.0 

func (c *Client) DiffService() diff.Differ

DiffService returns the underlying Differ

func (*Client) EventService added in v1.0.0 

func (c *Client) EventService() eventsapi.EventsClient

EventService returns the underlying EventsClient

func (*Client) Export added in v1.0.0 

func (c *Client) Export(ctx context.Context, desc ocispec.Descriptor, opts ...ExportOpt) (io.ReadCloser, error)

Export exports an image to a Tar stream. OCI format is used by default. It is up to caller to put "org.opencontainers.image.ref.name" annotation to desc.

func (*Client) GetImage added in v1.0.0 

func (c *Client) GetImage(ctx context.Context, ref string) (Image, error)

GetImage returns an existing image

func (*Client) HealthService added in v1.0.0 

func (c *Client) HealthService() grpc_health_v1.HealthClient

HealthService returns the underlying GRPC HealthClient

func (*Client) ImageService added in v1.0.0 

func (c *Client) ImageService() images.Store

ImageService returns the underlying image Store

func (*Client) Import added in v1.0.0 

func (c *Client) Import(ctx context.Context, ref string, reader io.Reader, opts ...ImportOpt) (Image, error)

Import imports an image from a Tar stream using reader. OCI format is assumed by default.

Note that unreferenced blobs are imported to the content store as well.

func (*Client) IntrospectionService added in v1.0.0 

func (c *Client) IntrospectionService() introspectionapi.IntrospectionClient

func (*Client) IsServing added in v1.0.0 

func (c *Client) IsServing(ctx context.Context) (bool, error)

IsServing returns true if the client can successfully connect to the containerd daemon and the healthcheck service returns the SERVING response. This call will block if a transient error is encountered during connection. A timeout can be set in the context to ensure it returns early.

func (*Client) ListImages added in v1.0.0 

func (c *Client) ListImages(ctx context.Context, filters ...string) ([]Image, error)

ListImages returns all existing images

func (*Client) LoadContainer added in v1.0.0 

func (c *Client) LoadContainer(ctx context.Context, id string) (Container, error)

LoadContainer loads an existing container from metadata

func (*Client) NamespaceService added in v1.0.0 

func (c *Client) NamespaceService() namespacesapi.NamespacesClient

NamespaceService returns the underlying NamespacesClient

func (*Client) NewContainer added in v1.0.0 

func (c *Client) NewContainer(ctx context.Context, id string, opts ...NewContainerOpts) (Container, error)

NewContainer will create a new container in container with the provided id the id must be unique within the namespace

func (*Client) Pull added in v1.0.0 

func (c *Client) Pull(ctx context.Context, ref string, opts ...RemoteOpt) (Image, error)

Pull downloads the provided content into containerd's content store

func (*Client) Push added in v1.0.0 

func (c *Client) Push(ctx context.Context, ref string, desc ocispec.Descriptor, opts ...RemoteOpt) error

Push uploads the provided content to a remote resource

func (*Client) SnapshotService added in v1.0.0 

func (c *Client) SnapshotService(snapshotterName string) snapshot.Snapshotter

SnapshotService returns the underlying snapshotter for the provided snapshotter name

func (*Client) Subscribe added in v1.0.0 

func (c *Client) Subscribe(ctx context.Context, filters ...string) (ch <-chan *eventsapi.Envelope, errs <-chan error)

Subscribe to events that match one or more of the provided filters.

Callers should listen on both the envelope channel and errs channel. If the errs channel returns nil or an error, the subscriber should terminate.

To cancel shutdown reciept of events, cancel the provided context. The errs channel will be closed and return a nil error.

func (*Client) TaskService added in v1.0.0 

func (c *Client) TaskService() tasks.TasksClient

TaskService returns the underlying TasksClient

func (*Client) Version added in v1.0.0 

func (c *Client) Version(ctx context.Context) (Version, error)

Version returns the version of containerd that the client is connected to

func (*Client) VersionService added in v1.0.0 

func (c *Client) VersionService() versionservice.VersionClient

VersionService returns the underlying VersionClient

type ClientOpt added in v1.0.0 

type ClientOpt func(c *clientOpts) error

ClientOpt allows callers to set options on the containerd client

func WithDefaultNamespace added in v1.0.0 

func WithDefaultNamespace(ns string) ClientOpt

WithDefaultNamespace sets the default namespace on the client

Any operation that does not have a namespace set on the context will be provided the default namespace

func WithDialOpts added in v1.0.0 

func WithDialOpts(opts []grpc.DialOption) ClientOpt

WithDialOpts allows grpc.DialOptions to be set on the connection

type Container added in v1.0.0 

type Container interface {
	// ID identifies the container
	ID() string
	// Info returns the underlying container record type
	Info(context.Context) (containers.Container, error)
	// Delete removes the container
	Delete(context.Context, ...DeleteOpts) error
	// NewTask creates a new task based on the container metadata
	NewTask(context.Context, IOCreation, ...NewTaskOpts) (Task, error)
	// Spec returns the OCI runtime specification
	Spec(context.Context) (*specs.Spec, error)
	// Task returns the current task for the container
	//
	// If IOAttach options are passed the client will reattach to the IO for the running
	// task. If no task exists for the container a NotFound error is returned
	//
	// Clients must make sure that only one reader is attached to the task and consuming
	// the output from the task's fifos
	Task(context.Context, IOAttach) (Task, error)
	// Image returns the image that the container is based on
	Image(context.Context) (Image, error)
	// Labels returns the labels set on the container
	Labels(context.Context) (map[string]string, error)
	// SetLabels sets the provided labels for the container and returns the final label set
	SetLabels(context.Context, map[string]string) (map[string]string, error)
	// Extensions returns the extensions set on the container
	Extensions(context.Context) (map[string]prototypes.Any, error)
	// Update a container
	Update(context.Context, ...UpdateContainerOpts) error
}

Container is a metadata object for container resources and task creation

type DeleteOpts added in v1.0.0 

type DeleteOpts func(ctx context.Context, client *Client, c containers.Container) error

DeleteOpts allows the caller to set options for the deletion of a container

type DirectIO 

type DirectIO struct {
	Stdin  io.WriteCloser
	Stdout io.ReadCloser
	Stderr io.ReadCloser
	// contains filtered or unexported fields
}

DirectIO allows task IO to be handled externally by the caller

func NewDirectIO 

func NewDirectIO(ctx context.Context, terminal bool) (*DirectIO, error)

NewDirectIO returns an IO implementation that exposes the pipes directly

func (*DirectIO) Cancel 

func (f *DirectIO) Cancel()

Cancel stops any IO copy operations

Not applicable for DirectIO

func (*DirectIO) Close 

func (f *DirectIO) Close() error

Close closes all open fds

func (*DirectIO) Config 

func (f *DirectIO) Config() IOConfig

Config returns the IOConfig

func (*DirectIO) Delete 

func (f *DirectIO) Delete() error

Delete removes the underlying directory containing fifos

func (*DirectIO) IOAttach 

func (f *DirectIO) IOAttach(set *FIFOSet) (IO, error)

IOAttach returns IO avaliable for use with task attachment

func (*DirectIO) IOCreate 

func (f *DirectIO) IOCreate(id string) (IO, error)

IOCreate returns IO avaliable for use with task creation

func (*DirectIO) Wait 

func (f *DirectIO) Wait()

Wait on any IO copy operations

Not applicable for DirectIO

type ExitStatus added in v1.0.0 

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

ExitStatus encapsulates a process' exit status. It is used by `Wait()` to return either a process exit code or an error

func (ExitStatus) Error added in v1.0.0 

func (s ExitStatus) Error() error

Error returns the error, if any, that occured while waiting for the process.

func (ExitStatus) ExitCode added in v1.0.0 

func (s ExitStatus) ExitCode() uint32

ExitCode returns the exit code of the process. This is only valid is Error() returns nil

func (ExitStatus) ExitTime added in v1.0.0 

func (s ExitStatus) ExitTime() time.Time

ExitTime returns the exit time of the process This is only valid is Error() returns nil

func (ExitStatus) Result added in v1.0.0 

func (s ExitStatus) Result() (uint32, time.Time, error)

Result returns the exit code and time of the exit status. An error may be returned here to which indicates there was an error 

at some point while waiting for the exit status. It does not signify
an error with the process itself.

If an error is returned, the process may still be running.

type ExportOpt added in v1.0.0 

type ExportOpt func(c *exportOpts) error

ExportOpt allows callers to set export options

func WithOCIExportFormat 

func WithOCIExportFormat() ExportOpt

WithOCIExportFormat sets the OCI image format as the export target

type FIFOSet 

type FIFOSet struct {
	// Dir is the directory holding the task fifos
	Dir string
	// In, Out, and Err fifo paths
	In, Out, Err string
	// Terminal returns true if a terminal is being used for the task
	Terminal bool
}

FIFOSet is a set of fifos for use with tasks

func NewFifos 

func NewFifos(id string) (*FIFOSet, error)

NewFifos returns a new set of fifos for the task

type IO 

type IO interface {
	// Config returns the IO configuration.
	Config() IOConfig
	// Cancel aborts all current io operations
	Cancel()
	// Wait blocks until all io copy operations have completed
	Wait()
	// Close cleans up all open io resources
	Close() error
}

IO holds the io information for a task or process

func NullIO 

func NullIO(id string) (IO, error)

NullIO redirects the container's IO into /dev/null

func Stdio 

func Stdio(id string) (IO, error)

Stdio returns an IO set to be used for a task that outputs the container's IO as the current processes Stdio

func StdioTerminal 

func StdioTerminal(id string) (IO, error)

StdioTerminal will setup the IO for the task to use a terminal

type IOAttach 

type IOAttach func(*FIFOSet) (IO, error)

IOAttach allows callers to reattach to running tasks

There should only be one reader for a task's IO set because fifo's can only be read from one reader or the output will be sent only to the first reads

func WithAttach 

func WithAttach(stdin io.Reader, stdout, stderr io.Writer) IOAttach

WithAttach attaches the existing io for a task to the provided io.Reader/Writers

type IOCloseInfo added in v1.0.0 

type IOCloseInfo struct {
	Stdin bool
}

IOCloseInfo allows specific io pipes to be closed on a process

type IOCloserOpts added in v1.0.0 

type IOCloserOpts func(*IOCloseInfo)

IOCloserOpts allows the caller to set specific pipes as closed on a process

type IOConfig 

type IOConfig struct {
	// Terminal is true if one has been allocated
	Terminal bool
	// Stdin path
	Stdin string
	// Stdout path
	Stdout string
	// Stderr path
	Stderr string
}

IOConfig holds the io configurations.

type IOCreation 

type IOCreation func(id string) (IO, error)

IOCreation creates new IO sets for a task

func NewIO 

func NewIO(stdin io.Reader, stdout, stderr io.Writer) IOCreation

NewIO returns an IOCreation that will provide IO sets without a terminal

func NewIOWithTerminal 

func NewIOWithTerminal(stdin io.Reader, stdout, stderr io.Writer, terminal bool) IOCreation

NewIOWithTerminal creates a new io set with the provied io.Reader/Writers for use with a terminal

type Image added in v1.0.0 

type Image interface {
	// Name of the image
	Name() string
	// Target descriptor for the image content
	Target() ocispec.Descriptor
	// Unpack unpacks the image's content into a snapshot
	Unpack(context.Context, string) error
	// RootFS returns the unpacked diffids that make up images rootfs.
	RootFS(ctx context.Context) ([]digest.Digest, error)
	// Size returns the total size of the image's packed resources.
	Size(ctx context.Context) (int64, error)
	// Config descriptor for the image.
	Config(ctx context.Context) (ocispec.Descriptor, error)
}

Image describes an image used by containers

type ImportOpt added in v1.0.0 

type ImportOpt func(c *importOpts) error

ImportOpt allows the caller to specify import specific options

func WithImportLabel 

func WithImportLabel(key, value string) ImportOpt

WithImportLabel sets a label to be associated with an imported image

func WithImportLabels 

func WithImportLabels(labels map[string]string) ImportOpt

WithImportLabels associates a set of labels to an imported image

func WithOCIImportFormat 

func WithOCIImportFormat() ImportOpt

WithOCIImportFormat sets the import format for an OCI image format

func WithRefObject 

func WithRefObject(refObject string) ImportOpt

WithRefObject specifies the ref object to import. If refObject is empty, it is copied from the ref argument of Import().

type KillInfo added in v1.0.0 

type KillInfo struct {
	// All kills all processes inside the task
	// only valid on tasks, ignored on processes
	All bool
}

KillInfo contains information on how to process a Kill action

type KillOpts added in v1.0.0 

type KillOpts func(context.Context, Process, *KillInfo) error

KillOpts allows options to be set for the killing of a process

type NewContainerOpts added in v1.0.0 

type NewContainerOpts func(ctx context.Context, client *Client, c *containers.Container) error

NewContainerOpts allows the caller to set additional options when creating a container

func WithCheckpoint added in v1.0.0 

func WithCheckpoint(desc v1.Descriptor, snapshotKey string) NewContainerOpts

WithCheckpoint allows a container to be created from the checkpointed information provided by the descriptor. The image, snapshot, and runtime specifications are restored on the container

func WithContainerExtension added in v1.0.0 

func WithContainerExtension(name string, extension interface{}) NewContainerOpts

WithContainerExtension appends extension data to the container object. Use this to decorate the container object with additional data for the client integration.

Make sure to register the type of `extension` in the typeurl package via `typeurl.Register` otherwise the type data will be inferred, including how to encode and decode the object.

func WithContainerLabels added in v1.0.0 

func WithContainerLabels(labels map[string]string) NewContainerOpts

WithContainerLabels adds the provided labels to the container

func WithImage added in v1.0.0 

func WithImage(i Image) NewContainerOpts

WithImage sets the provided image as the base for the container

func WithNewSnapshot added in v1.0.0 

func WithNewSnapshot(id string, i Image) NewContainerOpts

WithNewSnapshot allocates a new snapshot to be used by the container as the root filesystem in read-write mode

func WithNewSnapshotView added in v1.0.0 

func WithNewSnapshotView(id string, i Image) NewContainerOpts

WithNewSnapshotView allocates a new snapshot to be used by the container as the root filesystem in read-only mode

func WithNewSpec added in v1.0.0 

func WithNewSpec(opts ...SpecOpts) NewContainerOpts

WithNewSpec generates a new spec for a new container

func WithRemappedSnapshot added in v1.0.0 

func WithRemappedSnapshot(id string, i Image, uid, gid uint32) NewContainerOpts

WithRemappedSnapshot creates a new snapshot and remaps the uid/gid for the filesystem to be used by a container with user namespaces

func WithRemappedSnapshotView added in v1.0.0 

func WithRemappedSnapshotView(id string, i Image, uid, gid uint32) NewContainerOpts

WithRemappedSnapshotView is similar to WithRemappedSnapshot but rootfs is mounted as read-only.

func WithRuntime added in v1.0.0 

func WithRuntime(name string, options interface{}) NewContainerOpts

WithRuntime allows a user to specify the runtime name and additional options that should be used to create tasks for the container

func WithSnapshot added in v1.0.0 

func WithSnapshot(id string) NewContainerOpts

WithSnapshot uses an existing root filesystem for the container

func WithSnapshotter added in v1.0.0 

func WithSnapshotter(name string) NewContainerOpts

WithSnapshotter sets the provided snapshotter for use by the container

This option must appear before other snapshotter options to have an effect.

func WithSpec added in v1.0.0 

func WithSpec(s *specs.Spec, opts ...SpecOpts) NewContainerOpts

WithSpec sets the provided spec on the container

type NewTaskOpts added in v1.0.0 

type NewTaskOpts func(context.Context, *Client, *TaskInfo) error

NewTaskOpts allows the caller to set options on a new task

func WithRootFS added in v1.0.0 

func WithRootFS(mounts []mount.Mount) NewTaskOpts

WithRootFS allows a task to be created without a snapshot being allocated to its container

func WithTaskCheckpoint added in v1.0.0 

func WithTaskCheckpoint(desc v1.Descriptor) NewTaskOpts

WithTaskCheckpoint allows a task to be created with live runtime and memory data from a previous checkpoint. Additional software such as CRIU may be required to restore a task from a checkpoint

type Process added in v1.0.0 

type Process interface {
	// Pid is the system specific process id
	Pid() uint32
	// Start starts the process executing the user's defined binary
	Start(context.Context) error
	// Delete removes the process and any resources allocated returning the exit status
	Delete(context.Context, ...ProcessDeleteOpts) (*ExitStatus, error)
	// Kill sends the provided signal to the process
	Kill(context.Context, syscall.Signal, ...KillOpts) error
	// Wait asynchronously waits for the process to exit, and sends the exit code to the returned channel
	Wait(context.Context) (<-chan ExitStatus, error)
	// CloseIO allows various pipes to be closed on the process
	CloseIO(context.Context, ...IOCloserOpts) error
	// Resize changes the width and heigh of the process's terminal
	Resize(ctx context.Context, w, h uint32) error
	// IO returns the io set for the process
	IO() IO
	// Status returns the executing status of the process
	Status(context.Context) (Status, error)
}

Process represents a system process

type ProcessDeleteOpts added in v1.0.0 

type ProcessDeleteOpts func(context.Context, Process) error

ProcessDeleteOpts allows the caller to set options for the deletion of a task

type ProcessInfo added in v1.0.0 

type ProcessInfo struct {
	// Pid is the process ID
	Pid uint32
	// Info includes additional process information
	// Info varies by platform
	Info *google_protobuf.Any
}

type ProcessStatus added in v1.0.0 

type ProcessStatus string

ProcessStatus returns a human readable status for the Process representing its current status 

const (
	// Running indicates the process is currently executing
	Running ProcessStatus = "running"
	// Created indicates the process has been created within containerd but the
	// user's defined process has not started
	Created ProcessStatus = "created"
	// Stopped indicates that the process has ran and exited
	Stopped ProcessStatus = "stopped"
	// Paused indicates that the process is currently paused
	Paused ProcessStatus = "paused"
	// Pausing indicates that the process is currently switching from a
	// running state into a paused state
	Pausing ProcessStatus = "pausing"
	// Unknown indicates that we could not determine the status from the runtime
	Unknown ProcessStatus = "unknown"
)

type RemoteContext added in v1.0.0 

type RemoteContext struct {
	// Resolver is used to resolve names to objects, fetchers, and pushers.
	// If no resolver is provided, defaults to Docker registry resolver.
	Resolver remotes.Resolver

	// Unpack is done after an image is pulled to extract into a snapshotter.
	// If an image is not unpacked on pull, it can be unpacked any time
	// afterwards. Unpacking is required to run an image.
	Unpack bool

	// Snapshotter used for unpacking
	Snapshotter string

	// Labels to be applied to the created image
	Labels map[string]string

	// BaseHandlers are a set of handlers which get are called on dispatch.
	// These handlers always get called before any operation specific
	// handlers.
	BaseHandlers []images.Handler

	// ConvertSchema1 is whether to convert Docker registry schema 1
	// manifests. If this option is false then any image which resolves
	// to schema 1 will return an error since schema 1 is not supported.
	ConvertSchema1 bool
}

RemoteContext is used to configure object resolutions and transfers with remote content stores and image providers.

type RemoteOpt added in v1.0.0 

type RemoteOpt func(*Client, *RemoteContext) error

RemoteOpt allows the caller to set distribution options for a remote

func WithImageHandler added in v1.0.0 

func WithImageHandler(h images.Handler) RemoteOpt

WithImageHandler adds a base handler to be called on dispatch.

func WithPullLabel added in v1.0.0 

func WithPullLabel(key, value string) RemoteOpt

WithPullLabel sets a label to be associated with a pulled reference

func WithPullLabels added in v1.0.0 

func WithPullLabels(labels map[string]string) RemoteOpt

WithPullLabels associates a set of labels to a pulled reference

func WithPullSnapshotter added in v1.0.0 

func WithPullSnapshotter(snapshotterName string) RemoteOpt

WithPullSnapshotter specifies snapshotter name used for unpacking

func WithResolver added in v1.0.0 

func WithResolver(resolver remotes.Resolver) RemoteOpt

WithResolver specifies the resolver to use.

type SpecOpts 

type SpecOpts func(context.Context, *Client, *containers.Container, *specs.Spec) error

SpecOpts sets spec specific information to a newly generated OCI spec

func WithCgroup 

func WithCgroup(path string) SpecOpts

WithCgroup sets the container's cgroup path

func WithHostNamespace 

func WithHostNamespace(ns specs.LinuxNamespaceType) SpecOpts

WithHostNamespace allows a task to run inside the host's linux namespace

func WithHostname 

func WithHostname(name string) SpecOpts

WithHostname sets the container's hostname

func WithImageConfig 

func WithImageConfig(i Image) SpecOpts

WithImageConfig configures the spec to from the configuration of an Image

func WithLinuxNamespace 

func WithLinuxNamespace(ns specs.LinuxNamespace) SpecOpts

WithLinuxNamespace uses the passed in namespace for the spec. If a namespace of the same type already exists in the spec, the existing namespace is replaced by the one provided.

func WithNamespacedCgroup 

func WithNamespacedCgroup() SpecOpts

WithNamespacedCgroup uses the namespace set on the context to create a root directory for containers in the cgroup with the id as the subcgroup

func WithProcessArgs 

func WithProcessArgs(args ...string) SpecOpts

WithProcessArgs replaces the args on the generated spec

func WithProcessCwd 

func WithProcessCwd(cwd string) SpecOpts

WithProcessCwd replaces the current working directory on the generated spec

func WithRootFSPath 

func WithRootFSPath(path string) SpecOpts

WithRootFSPath specifies unmanaged rootfs path.

func WithRootFSReadonly 

func WithRootFSReadonly() SpecOpts

WithRootFSReadonly sets specs.Root.Readonly to true

func WithUIDGID 

func WithUIDGID(uid, gid uint32) SpecOpts

WithUIDGID allows the UID and GID for the Process to be set

func WithUserID 

func WithUserID(uid uint32) SpecOpts

WithUserID sets the correct UID and GID for the container based on the image's /etc/passwd contents. If /etc/passwd does not exist, or uid is not found in /etc/passwd, it sets gid to be the same with uid, and not returns error.

func WithUserNamespace 

func WithUserNamespace(container, host, size uint32) SpecOpts

WithUserNamespace sets the uid and gid mappings for the task this can be called multiple times to add more mappings to the generated spec

func WithUsername 

func WithUsername(username string) SpecOpts

WithUsername sets the correct UID and GID for the container based on the the image's /etc/passwd contents. If /etc/passwd does not exist, or the username is not found in /etc/passwd, it returns error.

type Status added in v1.0.0 

type Status struct {
	// Status of the process
	Status ProcessStatus
	// ExitStatus returned by the process
	ExitStatus uint32
	// ExitedTime is the time at which the process died
	ExitTime time.Time
}

Status returns process status and exit information

type Task added in v1.0.0 

type Task interface {
	Process

	// Pause suspends the execution of the task
	Pause(context.Context) error
	// Resume the execution of the task
	Resume(context.Context) error
	// Exec creates a new process inside the task
	Exec(context.Context, string, *specs.Process, IOCreation) (Process, error)
	// Pids returns a list of system specific process ids inside the task
	Pids(context.Context) ([]ProcessInfo, error)
	// Checkpoint serializes the runtime and memory information of a task into an
	// OCI Index that can be push and pulled from a remote resource.
	//
	// Additional software like CRIU maybe required to checkpoint and restore tasks
	Checkpoint(context.Context, ...CheckpointTaskOpts) (v1.Descriptor, error)
	// Update modifies executing tasks with updated settings
	Update(context.Context, ...UpdateTaskOpts) error
	// LoadProcess loads a previously created exec'd process
	LoadProcess(context.Context, string, IOAttach) (Process, error)
	// Metrics returns task metrics for runtime specific metrics
	//
	// The metric types are generic to containerd and change depending on the runtime
	// For the built in Linux runtime, github.com/containerd/cgroups.Metrics
	// are returned in protobuf format
	Metrics(context.Context) (*types.Metric, error)
}

Task is the executable object within containerd

type TaskInfo added in v1.0.0 

type TaskInfo struct {
	// Checkpoint is the Descriptor for an existing checkpoint that can be used
	// to restore a task's runtime and memory state
	Checkpoint *types.Descriptor
	// RootFS is a list of mounts to use as the task's root filesystem
	RootFS []mount.Mount
	// Options hold runtime specific settings for task creation
	Options interface{}
}

TaskInfo sets options for task creation

type UpdateContainerOpts added in v1.0.0 

type UpdateContainerOpts func(ctx context.Context, client *Client, c *containers.Container) error

UpdateContainerOpts allows the caller to set additional options when updating a container

type UpdateTaskInfo added in v1.0.0 

type UpdateTaskInfo struct {
	// Resources updates a tasks resource constraints
	Resources interface{}
}

UpdateTaskInfo allows updated specific settings to be changed on a task

type UpdateTaskOpts added in v1.0.0 

type UpdateTaskOpts func(context.Context, *Client, *UpdateTaskInfo) error

UpdateTaskOpts allows a caller to update task settings

func WithResources added in v1.0.0 

func WithResources(resources *specs.LinuxResources) UpdateTaskOpts

WithResources sets the provided resources on the spec for task updates

type Version 

type Version struct {
	// Version number
	Version string
	// Revision from git that was built
	Revision string
}

Version of containerd

Source Files

View all Source files

Directories

Path Synopsis
api
services/containers/v1
Package containers is a generated protocol buffer package.
 Package containers is a generated protocol buffer package.
services/content/v1
Package content is a generated protocol buffer package.
 Package content is a generated protocol buffer package.
services/diff/v1
Package diff is a generated protocol buffer package.
 Package diff is a generated protocol buffer package.
services/events/v1
Package events is a generated protocol buffer package.
 Package events is a generated protocol buffer package.
services/images/v1
Package images is a generated protocol buffer package.
 Package images is a generated protocol buffer package.
services/introspection/v1
Package introspection is a generated protocol buffer package.
 Package introspection is a generated protocol buffer package.
services/namespaces/v1
Package namespaces is a generated protocol buffer package.
 Package namespaces is a generated protocol buffer package.
services/snapshot/v1
Package snapshot is a generated protocol buffer package.
 Package snapshot is a generated protocol buffer package.
services/tasks/v1
Package tasks is a generated protocol buffer package.
 Package tasks is a generated protocol buffer package.
services/version/v1
Package version is a generated protocol buffer package.
 Package version is a generated protocol buffer package.
types
Package types is a generated protocol buffer package.
 Package types is a generated protocol buffer package.
types/task
Package task is a generated protocol buffer package.
 Package task is a generated protocol buffer package.
compression
cmd
containerd
containerd-release
containerd-shim
containerd-stress
ctr
protoc-gen-gogoctrd
local
testsuite
contrib
apparmor
seccomp
walking
Package errdefs defines the common errors used throughout containerd packages.
 Package errdefs defines the common errors used throughout containerd packages.
Package filters defines a syntax and parser that can be used for the filtration of items across the containerd API.
 Package filters defines a syntax and parser that can be used for the filtration of items across the containerd API.
fs
fstest
Package gc experiments with providing central gc tooling to ensure deterministic resource removal within containerd.
 Package gc experiments with providing central gc tooling to ensure deterministic resource removal within containerd.
Package identifiers provides common validation for identifiers and keys across containerd.
 Package identifiers provides common validation for identifiers and keys across containerd.
runcopts
Package runcopts is a generated protocol buffer package.
 Package runcopts is a generated protocol buffer package.
shim
shim/v1
Package shim is a generated protocol buffer package.
 Package shim is a generated protocol buffer package.
boltutil
metrics
cgroups
lookup_test
Package namespaces provides tools for working with namespaces across containerd.
 Package namespaces provides tools for working with namespaces across containerd.
Package platforms provides a toolkit for normalizing, matching and specifying container platforms.
 Package platforms provides a toolkit for normalizing, matching and specifying container platforms.
Package progress assists in displaying human readable progress information.
 Package progress assists in displaying human readable progress information.
protobuf
google/rpc
Package rpc is a generated protocol buffer package.
 Package rpc is a generated protocol buffer package.
plugin
Package plugin is a generated protocol buffer package.
 Package plugin is a generated protocol buffer package.
plugin/fieldpath
docker
docker/schema1
services
containers
content
diff
events
healthcheck
images
introspection
namespaces
snapshot
tasks
version
btrfs
naive
overlay
storage
Package storage provides a metadata storage implementation for snapshot drivers.
 Package storage provides a metadata storage implementation for snapshot drivers.
testsuite
windows
Package sys provides access to the Get Child and Set Child prctl flags.
 Package sys provides access to the Get Child and Set Child prctl flags.
hcsshimtypes
hcsshimtypes holds the windows runtime specific types Package hcsshimtypes is a generated protocol buffer package.
 hcsshimtypes holds the windows runtime specific types Package hcsshimtypes is a generated protocol buffer package.

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.