containerd

package module
v1.0.0-alpha3 Latest Latest
Warning

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

 Go to latest Published: Aug 2, 2017 License: Apache-2.0, CC-BY-SA-4.0 Imports: 65 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.

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())

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.

spec, err := containerd.GenerateSpec(containerd.WithImageConfig(context, image))

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",
	containerd.WithSpec(spec),
)
defer redis.Delete(context)

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.WithSpec(spec),
	containerd.WithNewSnapshot("redis-rootfs", 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.WithSpec(spec),
		containerd.WithNewSnapshotView(id, 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

containerd will be released with a 1.0 when feature complete and this version will be supported for 1 year with security and bug fixes applied and released.

The upgrade path for containerd is that the 0.0.x patch releases are always backward compatible with its major and minor version. Minor (0.x.0) version will always be compatible with the previous minor release. i.e. 1.2.0 is backwards compatible with 1.1.0 and 1.1.0 is compatible with 1.0.0. There is no compatibility guarantees with upgrades from two minor releases. i.e. 1.0.0 to 1.2.0.

There are not backwards compatibility guarantees with upgrades to major versions. i.e 1.0.0 to 2.0.0. Each major version will be supported for 1 year with bug fixes and security patches.

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

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 UnknownExitStatus = 255

Variables

This section is empty.

Functions

func GenerateSpec 

func GenerateSpec(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

func WithExit added in v1.0.0 

func WithExit(r *CheckpointTaskInfo) error

func WithHostHosts 

func WithHostHosts(s *specs.Spec) error

func WithHostLocaltime 

func WithHostLocaltime(s *specs.Spec) error

func WithHostResoveconf 

func WithHostResoveconf(s *specs.Spec) error

func WithNoNewPrivileges 

func WithNoNewPrivileges(s *specs.Spec) error

WithNoNewPrivileges sets no_new_privileges on the process for the container

func WithPullUnpack added in v1.0.0 

func WithPullUnpack(client *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 allocated for the container

func WithStdinCloser added in v1.0.0 

func WithStdinCloser(r *IOCloseInfo)

func WithTTY 

func WithTTY(s *specs.Spec) error

Types

type CheckpointTaskInfo added in v1.0.0 

type CheckpointTaskInfo struct {
	ParentCheckpoint digest.Digest
	Options          interface{}
}

type CheckpointTaskOpts added in v1.0.0 

type CheckpointTaskOpts func(*CheckpointTaskInfo) error

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

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

func (*Client) DiffService added in v1.0.0 

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

func (*Client) EventService added in v1.0.0 

func (c *Client) EventService() eventsapi.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

func (*Client) ImageService added in v1.0.0 

func (c *Client) ImageService() images.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) IsServing added in v1.0.0 

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

func (*Client) ListImages added in v1.0.0 

func (c *Client) ListImages(ctx context.Context) ([]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)

func (*Client) NamespaceService added in v1.0.0 

func (c *Client) NamespaceService() namespacesapi.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 ...RemoteOpts) (Image, error)

func (*Client) Push added in v1.0.0 

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

func (*Client) SnapshotService added in v1.0.0 

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

func (*Client) TaskService added in v1.0.0 

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

func (*Client) Version added in v1.0.0 

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

func (*Client) VersionService added in v1.0.0 

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

type ClientOpt added in v1.0.0 

type ClientOpt func(c *clientOpts) error

func WithDefaultNamespace added in v1.0.0 

func WithDefaultNamespace(ns string) ClientOpt

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() string
	Info() containers.Container
	Delete(context.Context, ...DeleteOpts) error
	NewTask(context.Context, IOCreation, ...NewTaskOpts) (Task, error)
	Spec() (*specs.Spec, error)
	Task(context.Context, IOAttach) (Task, error)
	Image(context.Context) (Image, error)
	Labels(context.Context) (map[string]string, error)
	SetLabels(context.Context, map[string]string) (map[string]string, error)
}

type DeleteOpts added in v1.0.0 

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

type ExportOpt added in v1.0.0 

type ExportOpt func(c *exportOpts) error

func WithOCIExportFormat 

func WithOCIExportFormat() ExportOpt

type FIFOSet 

type FIFOSet struct {
	// Dir is the directory holding the task fifos
	Dir          string
	In, Out, Err string
	Terminal     bool
}

func NewFifos 

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

NewFifos returns a new set of fifos for the task

type IO 

type IO struct {
	Terminal bool
	Stdin    string
	Stdout   string
	Stderr   string
	// contains filtered or unexported fields
}

func Stdio 

func Stdio(id string) (*IO, error)

Stdio returns an IO implementation 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

func (*IO) Cancel 

func (i *IO) Cancel()

func (*IO) Close 

func (i *IO) Close() error

func (*IO) Wait 

func (i *IO) Wait()

type IOAttach 

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

func WithAttach 

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

type IOCloseInfo added in v1.0.0 

type IOCloseInfo struct {
	Stdin bool
}

type IOCloserOpts added in v1.0.0 

type IOCloserOpts func(*IOCloseInfo)

type IOCreation 

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

func NewIO 

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

func NewIOWithTerminal 

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

type Image added in v1.0.0 

type Image interface {
	Name() string
	Target() ocispec.Descriptor

	Unpack(context.Context, string) error
}

type ImportOpt added in v1.0.0 

type ImportOpt func(c *importOpts) error

func WithOCIImportFormat 

func WithOCIImportFormat() ImportOpt

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 NewContainerOpts added in v1.0.0 

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

func WithCheckpoint added in v1.0.0 

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

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

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 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 WithRuntime added in v1.0.0 

func WithRuntime(name string) 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

func WithSpec added in v1.0.0 

func WithSpec(spec *specs.Spec) NewContainerOpts

WithSpec sets the provided spec for a new container

type NewTaskOpts added in v1.0.0 

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

func WithRootFS added in v1.0.0 

func WithRootFS(mounts []mount.Mount) NewTaskOpts

func WithTaskCheckpoint added in v1.0.0 

func WithTaskCheckpoint(desc v1.Descriptor) NewTaskOpts

type Process added in v1.0.0 

type Process interface {
	Pid() uint32
	Start(context.Context) error
	Delete(context.Context) (uint32, error)
	Kill(context.Context, syscall.Signal) error
	Wait(context.Context) (uint32, error)
	CloseIO(context.Context, ...IOCloserOpts) error
	Resize(ctx context.Context, w, h uint32) error
	IO() *IO
	Status(context.Context) (Status, error)
}

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

	// 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 RemoteOpts 

type RemoteOpts func(*Client, *RemoteContext) error

func WithImageHandler added in v1.0.0 

func WithImageHandler(h images.Handler) RemoteOpts

WithImageHandler adds a base handler to be called on dispatch.

func WithPullSnapshotter added in v1.0.0 

func WithPullSnapshotter(snapshotterName string) RemoteOpts

WithPullSnapshotter specifies snapshotter name used for unpacking

func WithResolver added in v1.0.0 

func WithResolver(resolver remotes.Resolver) RemoteOpts

WithResolver specifies the resolver to use.

type SpecOpts 

type SpecOpts func(s *specs.Spec) error

SpecOpts sets spec specific information to a newly generated OCI spec

func WithApparmorProfile 

func WithApparmorProfile(profile string) SpecOpts

WithApparmor sets the provided apparmor profile to the spec

func WithHostNamespace 

func WithHostNamespace(ns specs.LinuxNamespaceType) SpecOpts

func WithImageConfig 

func WithImageConfig(ctx context.Context, i Image) SpecOpts

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 WithProcessArgs 

func WithProcessArgs(args ...string) SpecOpts

WithProcessArgs replaces the args on the generated spec

func WithRootFSPath 

func WithRootFSPath(path string, readonly bool) SpecOpts

WithRootFSPath specifies unmanaged rootfs path.

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

type Status added in v1.0.0 

type Status string
const (
	Running Status = "running"
	Created Status = "created"
	Stopped Status = "stopped"
	Paused  Status = "paused"
	Pausing Status = "pausing"
)

type Task added in v1.0.0 

type Task interface {
	Pid() uint32
	Delete(context.Context) (uint32, error)
	Kill(context.Context, syscall.Signal) error
	Pause(context.Context) error
	Resume(context.Context) error
	Start(context.Context) error
	Status(context.Context) (Status, error)
	Wait(context.Context) (uint32, error)
	Exec(context.Context, string, *specs.Process, IOCreation) (Process, error)
	Pids(context.Context) ([]uint32, error)
	CloseIO(context.Context, ...IOCloserOpts) error
	Resize(ctx context.Context, w, h uint32) error
	IO() *IO
	Checkpoint(context.Context, ...CheckpointTaskOpts) (v1.Descriptor, error)
	Update(context.Context, ...UpdateTaskOpts) error
}

type TaskInfo added in v1.0.0 

type TaskInfo struct {
	Checkpoint *types.Descriptor
	RootFS     []mount.Mount
	Options    interface{}
}

type UpdateTaskInfo added in v1.0.0 

type UpdateTaskInfo struct {
	Resources interface{}
}

type UpdateTaskOpts added in v1.0.0 

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

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  string
	Revision string
}

Source Files

View all Source files

Directories

Path Synopsis
api
cmd
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
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.
metrics
Package namespaces provides tools for working with namespaces across containerd.
 Package namespaces provides tools for working with namespaces across containerd.
Package oci provides basic operations for manipulating OCI images.
 Package oci provides basic operations for manipulating OCI images.
Package progress assists in displaying human readable progress information.
 Package progress assists in displaying human readable progress information.
protobuf
services
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.

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.