containerd

package module
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Oct 24, 2018 License: Apache-2.0 Imports: 68 Imported by: 0

README ¶

containerd banner

GoDoc Build Status Windows Build Status FOSSA Status Go Report Card CII Best Practices

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

See our documentation on containerd.io:

See how to build containerd from source at BUILDING.

If you are interested in trying out containerd see our example at Getting Started.

Runtime Requirements

Runtime requirements for containerd are very minimal. Most interactions with the Linux and Windows container feature sets are handled via runc and/or OS-specific libraries (e.g. hcsshim for Microsoft). The current required version of runc is always listed in RUNC.md.

There are specific features used by containerd core code and snapshotters that will require a minimum kernel version on Linux. With the understood caveat of distro kernel versioning, a reasonable starting point for Linux is a minimum 4.x kernel version.

The overlay filesystem snapshotter, used by default, uses features that were finalized in the 4.x kernel series. If you choose to use btrfs, there may be more flexibility in kernel version (minimum recommended is 3.18), but will require the btrfs kernel module and btrfs tools to be installed on your Linux distribution.

To use Linux checkpoint and restore features, you will need criu installed on your system. See more details in Checkpoint and Restore.

Build requirements for developers are listed in BUILDING.

Features

Client

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


import (
  "github.com/containerd/containerd"
  "github.com/containerd/containerd/cio"
)


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(oci.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(oci.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(oci.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, cio.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)

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, cio.Stdio, containerd.WithTaskCheckpoint(checkpoint))
defer task.Delete(context)

err := task.Start(context)

Snapshot Plugins

In addition to the built-in Snapshot plugins in containerd, additional external plugins can be configured using GRPC. An external plugin is made available using the configured name and appears as a plugin alongside the built-in ones.

To add an external snapshot plugin, add the plugin to containerd's config file (by default at /etc/containerd/config.toml). The string following proxy_plugin. will be used as the name of the snapshotter and the address should refer to a socket with a GRPC listener serving containerd's Snapshot GRPC API. Remember to restart containerd for any configuration changes to take effect.

[proxy_plugins]
  [proxy_plugins.customsnapshot]
    type = "snapshot"
    address =  "/var/run/mysnapshotter.sock"

See PLUGINS.md for how to create plugins

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://join.slack.com/t/dockercommunity/shared_invite/enQtNDM4NjAwNDMyOTUwLWZlMDZmYWRjZjk4Zjc5ZGQ5NWZkOWI1Yjk2NGE3ZWVlYjYxM2VhYjczOWIyZDFhZTE3NTUwZWQzMjhmNGYyZTg

Reporting security issues

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

Licenses

The containerd codebase 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. You may obtain a copy of the license, titled CC-BY-4.0, at http://creativecommons.org/licenses/by/4.0/.

Project details

containerd is the primary open source project within the broader containerd GitHub repository. However, all projects within the repo have common maintainership, governance, and contributing guidelines which are stored in a project repository commonly for all containerd projects.

Please find all these core project documents, including the:

information in our containerd/project repository.

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 = "native"
)
View Source 
const StopSignalLabel = "io.containerd.image.config.stop-signal"

StopSignalLabel is a well-known containerd label for storing the stop signal specified in the OCI image config

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 GetOCIStopSignal ¶ added in v1.2.0 

func GetOCIStopSignal(ctx context.Context, image Image, defaultSignal string) (string, error)

GetOCIStopSignal retrieves the stop signal specified in the OCI image config

func GetStopSignal ¶ added in v1.2.0 

func GetStopSignal(ctx context.Context, container Container, defaultSignal syscall.Signal) (syscall.Signal, error)

GetStopSignal retrieves the container stop signal, specified by the well-known containerd label (StopSignalLabel)

func NewImageStoreFromClient ¶ 

func NewImageStoreFromClient(client imagesapi.ImagesClient) images.Store

NewImageStoreFromClient returns a new image store client

func NewNamespaceStoreFromClient ¶ 

func NewNamespaceStoreFromClient(client api.NamespacesClient) namespaces.Store

NewNamespaceStoreFromClient returns a new namespace store

func NewRemoteContainerStore ¶ 

func NewRemoteContainerStore(client containersapi.ContainersClient) containers.Store

NewRemoteContainerStore returns the container Store connected with the provided client

func ParseSignal ¶ added in v1.2.0 

func ParseSignal(rawSignal string) (syscall.Signal, error)

ParseSignal parses a given string into a syscall.Signal it checks that the signal exists in the platform-appropriate signalMap

func WithInstallLibs ¶ added in v1.2.0 

func WithInstallLibs(c *InstallConfig)

WithInstallLibs installs libs from the image

func WithInstallReplace ¶ added in v1.2.0 

func WithInstallReplace(c *InstallConfig)

WithInstallReplace will replace existing files

func WithKillAll ¶ 

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

WithKillAll kills all processes for a task

func WithNoNewKeyring ¶ added in v1.2.0 

func WithNoNewKeyring(ctx context.Context, c *Client, ti *TaskInfo) error

WithNoNewKeyring causes tasks not to be created with a new keyring for secret storage. There is an upper limit on the number of keyrings in a linux system

func WithNoPivotRoot ¶ 

func WithNoPivotRoot(_ context.Context, _ *Client, info *TaskInfo) error

WithNoPivotRoot instructs the runtime not to you pivot_root

func WithProcessKill ¶ 

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

WithProcessKill will forcefully kill and delete a process

func WithPullUnpack ¶ 

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 ¶ 

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 ¶ 

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

WithSnapshotCleanup deletes the rootfs snapshot allocated for the container

func WithStdinCloser ¶ 

func WithStdinCloser(r *IOCloseInfo)

WithStdinCloser closes the stdin of a process

Types ¶

type CheckpointTaskInfo ¶ 

type CheckpointTaskInfo struct {
	Name string
	// 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 ¶ 

type CheckpointTaskOpts func(*CheckpointTaskInfo) error

CheckpointTaskOpts allows the caller to set checkpoint options

func WithCheckpointName ¶ 

func WithCheckpointName(name string) CheckpointTaskOpts

WithCheckpointName sets the image name for the checkpoint

type Client ¶ 

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 ¶ 

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 ¶ 

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 ¶ 

func (c *Client) Close() error

Close closes the clients connection to containerd

func (*Client) ContainerService ¶ 

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

ContainerService returns the underlying container Store

func (*Client) Containers ¶ 

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

Containers returns all containers created in containerd

func (*Client) ContentStore ¶ 

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

ContentStore returns the underlying content Store

func (*Client) DiffService ¶ 

func (c *Client) DiffService() DiffService

DiffService returns the underlying Differ

func (*Client) EventService ¶ 

func (c *Client) EventService() EventService

EventService returns the underlying event service

func (*Client) Export ¶ 

func (c *Client) Export(ctx context.Context, exporter images.Exporter, 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. TODO(AkihiroSuda): support exporting multiple descriptors at once to a single archive stream.

func (*Client) Fetch ¶ added in v1.2.0 

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

Fetch downloads the provided content into containerd's content store and returns a non-platform specific image reference

func (*Client) GetImage ¶ 

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

GetImage returns an existing image

func (*Client) HealthService ¶ 

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

HealthService returns the underlying GRPC HealthClient

func (*Client) ImageService ¶ 

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

ImageService returns the underlying image Store

func (*Client) Import ¶ 

func (c *Client) Import(ctx context.Context, reader io.Reader, opts ...ImportOpt) ([]images.Image, error)

Import imports an image from a Tar stream using reader. Caller needs to specify importer. Future version may use oci.v1 as the default. Note that unreferrenced blobs may be imported to the content store as well.

func (*Client) Install ¶ added in v1.2.0 

func (c *Client) Install(ctx context.Context, image Image, opts ...InstallOpts) error

Install a binary image into the opt service

func (*Client) IntrospectionService ¶ 

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

IntrospectionService returns the underlying Introspection Client

func (*Client) IsServing ¶ 

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) LeasesService ¶ 

func (c *Client) LeasesService() leases.Manager

LeasesService returns the underlying Leases Client

func (*Client) ListImages ¶ 

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

ListImages returns all existing images

func (*Client) LoadContainer ¶ 

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

LoadContainer loads an existing container from metadata

func (*Client) NamespaceService ¶ 

func (c *Client) NamespaceService() namespaces.Store

NamespaceService returns the underlying Namespaces Store

func (*Client) NewContainer ¶ 

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 ¶ 

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

Pull downloads the provided content into containerd's content store and returns a platform specific image object

func (*Client) Push ¶ 

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) Reconnect ¶ 

func (c *Client) Reconnect() error

Reconnect re-establishes the GRPC connection to the containerd daemon

func (*Client) SnapshotService ¶ 

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

SnapshotService returns the underlying snapshotter for the provided snapshotter name

func (*Client) Subscribe ¶ 

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

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

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

The subscriber can stop receiving events by canceling the provided context. The errs channel will be closed and return a nil error.

func (*Client) TaskService ¶ 

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

TaskService returns the underlying TasksClient

func (*Client) Version ¶ 

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

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

func (*Client) VersionService ¶ 

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

VersionService returns the underlying VersionClient

func (*Client) WithLease ¶ 

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

WithLease attaches a lease on the context

type ClientOpt ¶ 

type ClientOpt func(c *clientOpts) error

ClientOpt allows callers to set options on the containerd client

func WithDefaultNamespace ¶ 

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 WithDefaultRuntime ¶ added in v1.2.0 

func WithDefaultRuntime(rt string) ClientOpt

WithDefaultRuntime sets the default runtime on the client

func WithDialOpts ¶ 

func WithDialOpts(opts []grpc.DialOption) ClientOpt

WithDialOpts allows grpc.DialOptions to be set on the connection

func WithServices ¶ 

func WithServices(opts ...ServicesOpt) ClientOpt

WithServices sets services used by the client.

func WithTimeout ¶ added in v1.2.0 

func WithTimeout(d time.Duration) ClientOpt

WithTimeout sets the connection timeout for the client

type Container ¶ 

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, cio.Creator, ...NewTaskOpts) (Task, error)
	// Spec returns the OCI runtime specification
	Spec(context.Context) (*oci.Spec, error)
	// Task returns the current task for the container
	//
	// If cio.Attach 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, cio.Attach) (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 ¶ 

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 DiffService ¶ 

type DiffService interface {
	diff.Comparer
	diff.Applier
}

DiffService handles the computation and application of diffs

func NewDiffServiceFromClient ¶ 

func NewDiffServiceFromClient(client diffapi.DiffClient) DiffService

NewDiffServiceFromClient returns a new diff service which communicates over a GRPC connection.

type EventService ¶ 

type EventService interface {
	events.Publisher
	events.Forwarder
	events.Subscriber
}

EventService handles the publish, forward and subscribe of events.

func NewEventServiceFromClient ¶ 

func NewEventServiceFromClient(client eventsapi.EventsClient) EventService

NewEventServiceFromClient returns a new event service which communicates over a GRPC connection.

type ExitStatus ¶ 

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 ¶ 

func (s ExitStatus) Error() error

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

func (ExitStatus) ExitCode ¶ 

func (s ExitStatus) ExitCode() uint32

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

func (ExitStatus) ExitTime ¶ 

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 ¶ 

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 ¶ 

type ExportOpt func(c *exportOpts) error

ExportOpt allows the caller to specify export-specific options

type IOCloseInfo ¶ 

type IOCloseInfo struct {
	Stdin bool
}

IOCloseInfo allows specific io pipes to be closed on a process

type IOCloserOpts ¶ 

type IOCloserOpts func(*IOCloseInfo)

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

type Image ¶ 

type Image interface {
	// Name of the image
	Name() string
	// Target descriptor for the image content
	Target() ocispec.Descriptor
	// Labels of the image
	Labels() map[string]string
	// 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)
	// IsUnpacked returns whether or not an image is unpacked.
	IsUnpacked(context.Context, string) (bool, error)
	// ContentStore provides a content store which contains image blob data
	ContentStore() content.Store
}

Image describes an image used by containers

func NewImage ¶ 

func NewImage(client *Client, i images.Image) Image

NewImage returns a client image object from the metadata image

func NewImageWithPlatform ¶ added in v1.2.0 

func NewImageWithPlatform(client *Client, i images.Image, platform platforms.MatchComparer) Image

NewImageWithPlatform returns a client image object from the metadata image

type ImportOpt ¶ 

type ImportOpt func(*importOpts) error

ImportOpt allows the caller to specify import specific options

func WithDigestRef ¶ added in v1.2.0 

func WithDigestRef(f func(digest.Digest) string) ImportOpt

WithDigestRef is used to create digest images for each manifest in the index.

func WithImageRefTranslator ¶ added in v1.2.0 

func WithImageRefTranslator(f func(string) string) ImportOpt

WithImageRefTranslator is used to translate the index reference to an image reference for the image store.

func WithIndexName ¶ added in v1.2.0 

func WithIndexName(name string) ImportOpt

WithIndexName creates a tag pointing to the imported index

type InstallConfig ¶ added in v1.2.0 

type InstallConfig struct {
	// Libs installs libs from the image
	Libs bool
	// Replace will overwrite existing binaries or libs in the opt directory
	Replace bool
	// Path to install libs and binaries to
	Path string
}

InstallConfig sets the binary install configuration

type InstallOpts ¶ added in v1.2.0 

type InstallOpts func(*InstallConfig)

InstallOpts configures binary installs

func WithInstallPath ¶ added in v1.2.0 

func WithInstallPath(path string) InstallOpts

WithInstallPath sets the optional install path

type KillInfo ¶ 

type KillInfo struct {
	// All kills all processes inside the task
	// only valid on tasks, ignored on processes
	All bool
	// ExecID is the ID of a process to kill
	ExecID string
}

KillInfo contains information on how to process a Kill action

type KillOpts ¶ 

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

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

func WithKillExecID ¶ 

func WithKillExecID(execID string) KillOpts

WithKillExecID specifies the process ID

type NewContainerOpts ¶ 

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 ¶ 

func WithCheckpoint(im Image, 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 ¶ 

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` or container creation may fail.

func WithContainerLabels ¶ 

func WithContainerLabels(labels map[string]string) NewContainerOpts

WithContainerLabels adds the provided labels to the container

func WithImage ¶ 

func WithImage(i Image) NewContainerOpts

WithImage sets the provided image as the base for the container

func WithImageStopSignal ¶ added in v1.2.0 

func WithImageStopSignal(image Image, defaultSignal string) NewContainerOpts

WithImageStopSignal sets a well-known containerd label (StopSignalLabel) on the container for storing the stop signal specified in the OCI image config

func WithNewSnapshot ¶ 

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 ¶ 

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 ¶ 

func WithNewSpec(opts ...oci.SpecOpts) NewContainerOpts

WithNewSpec generates a new spec for a new container

func WithRemappedSnapshot ¶ 

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 ¶ 

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

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

func WithRuntime ¶ 

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 ¶ 

func WithSnapshot(id string) NewContainerOpts

WithSnapshot uses an existing root filesystem for the container

func WithSnapshotter ¶ 

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 ¶ 

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

WithSpec sets the provided spec on the container

type NewTaskOpts ¶ 

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

NewTaskOpts allows the caller to set options on a new task

func WithRootFS ¶ 

func WithRootFS(mounts []mount.Mount) NewTaskOpts

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

func WithTaskCheckpoint ¶ 

func WithTaskCheckpoint(im Image) 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 ¶ 

type Process interface {
	// ID of the process
	ID() string
	// 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() cio.IO
	// Status returns the executing status of the process
	Status(context.Context) (Status, error)
}

Process represents a system process

type ProcessDeleteOpts ¶ 

type ProcessDeleteOpts func(context.Context, Process) error

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

type ProcessInfo ¶ 

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

ProcessInfo provides platform specific process information

type ProcessStatus ¶ 

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 ¶ 

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

	// PlatformMatcher is used to match the platforms for an image
	// operation and define the preference when a single match is required
	// from multiple platforms.
	PlatformMatcher platforms.MatchComparer

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

	// Platforms defines which platforms to handle when doing the image operation.
	// Platforms is ignored when a PlatformMatcher is set, otherwise the
	// platforms will be used to create a PlatformMatcher with no ordering
	// preference.
	Platforms []string
}

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

type RemoteOpt ¶ 

type RemoteOpt func(*Client, *RemoteContext) error

RemoteOpt allows the caller to set distribution options for a remote

func WithImageHandler ¶ 

func WithImageHandler(h images.Handler) RemoteOpt

WithImageHandler adds a base handler to be called on dispatch.

func WithPlatform ¶ 

func WithPlatform(platform string) RemoteOpt

WithPlatform allows the caller to specify a platform to retrieve content for

func WithPlatformMatcher ¶ added in v1.2.0 

func WithPlatformMatcher(m platforms.MatchComparer) RemoteOpt

WithPlatformMatcher specifies the matcher to use for determining which platforms to pull content for. This value supersedes anything set with `WithPlatform`.

func WithPullLabel ¶ 

func WithPullLabel(key, value string) RemoteOpt

WithPullLabel sets a label to be associated with a pulled reference

func WithPullLabels ¶ 

func WithPullLabels(labels map[string]string) RemoteOpt

WithPullLabels associates a set of labels to a pulled reference

func WithPullSnapshotter ¶ 

func WithPullSnapshotter(snapshotterName string) RemoteOpt

WithPullSnapshotter specifies snapshotter name used for unpacking

func WithResolver ¶ 

func WithResolver(resolver remotes.Resolver) RemoteOpt

WithResolver specifies the resolver to use.

type ServicesOpt ¶ 

type ServicesOpt func(c *services)

ServicesOpt allows callers to set options on the services

func WithContainerService ¶ 

func WithContainerService(containerService containersapi.ContainersClient) ServicesOpt

WithContainerService sets the container service.

func WithContentStore ¶ 

func WithContentStore(contentStore content.Store) ServicesOpt

WithContentStore sets the content store.

func WithDiffService ¶ 

func WithDiffService(diffService diff.DiffClient) ServicesOpt

WithDiffService sets the diff service.

func WithEventService ¶ 

func WithEventService(eventService EventService) ServicesOpt

WithEventService sets the event service.

func WithImageService ¶ 

func WithImageService(imageService imagesapi.ImagesClient) ServicesOpt

WithImageService sets the image service.

func WithLeasesService ¶ 

func WithLeasesService(leasesService leases.Manager) ServicesOpt

WithLeasesService sets the lease service.

func WithNamespaceService ¶ 

func WithNamespaceService(namespaceService namespacesapi.NamespacesClient) ServicesOpt

WithNamespaceService sets the namespace service.

func WithSnapshotters ¶ 

func WithSnapshotters(snapshotters map[string]snapshots.Snapshotter) ServicesOpt

WithSnapshotters sets the snapshotters.

func WithTaskService ¶ 

func WithTaskService(taskService tasks.TasksClient) ServicesOpt

WithTaskService sets the task service.

type Status ¶ 

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 ¶ 

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, cio.Creator) (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) (Image, 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, cio.Attach) (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 ¶ 

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 ¶ 

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 ¶ 

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

UpdateTaskInfo allows updated specific settings to be changed on a task

type UpdateTaskOpts ¶ 

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

UpdateTaskOpts allows a caller to update task settings

func WithResources ¶ added in v1.2.0 

func WithResources(resources interface{}) UpdateTaskOpts

WithResources sets the provided resources for task updates. Resources must be either a *specs.LinuxResources or a *specs.WindowsResources

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
events
Package events is a generated protocol buffer package.
 Package events is a generated protocol buffer package.
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 defines the event pushing and subscription service.
 Package events defines the event pushing and subscription service.
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/leases/v1
Package leases is a generated protocol buffer package.
 Package leases 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/snapshots/v1
Package snapshots is a generated protocol buffer package.
 Package snapshots 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
tartest
cmd
containerd
containerd-shim
containerd-shim-runc-v1
containerd-shim-runhcs-v1
containerd-stress
containerd/command
ctr
ctr/app
ctr/commands
ctr/commands/containers
ctr/commands/content
ctr/commands/events
ctr/commands/images
ctr/commands/install
ctr/commands/leases
ctr/commands/namespaces
ctr/commands/plugins
ctr/commands/pprof
ctr/commands/run
ctr/commands/shim
ctr/commands/snapshots
ctr/commands/tasks
ctr/commands/version
protoc-gen-gogoctrd
local
proxy
testsuite
contrib
apparmor
nvidia
seccomp
snapshotservice
Package defaults provides several common defaults for interacting with containerd.
 Package defaults provides several common defaults for interacting with containerd.
apply
lcow
walking
walking/plugin
windows
Package errdefs defines the common errors used throughout containerd packages.
 Package errdefs defines the common errors used throughout containerd packages.
exchange
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.
gc
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.
scheduler
Package identifiers provides common validation for identifiers and keys across containerd.
 Package identifiers provides common validation for identifiers and keys across containerd.
archive
Package archive provides a Docker and OCI compatible importer
 Package archive provides a Docker and OCI compatible importer
oci
proxy
boltutil
metrics
cgroups
Package namespaces provides tools for working with namespaces across containerd.
 Package namespaces provides tools for working with namespaces across containerd.
pkg
dialer
progress
Package progress assists in displaying human readable progress information.
 Package progress assists in displaying human readable progress information.
seed
testutil
Package platforms provides a toolkit for normalizing, matching and specifying container platforms.
 Package platforms provides a toolkit for normalizing, matching and specifying container platforms.
protobuf
plugin
Package plugin is a generated protocol buffer package.
 Package plugin is a generated protocol buffer package.
plugin/fieldpath
docker
docker/schema1
linux/runctypes
Package runctypes is a generated protocol buffer package.
 Package runctypes is a generated protocol buffer package.
proc
restart
Package restart enables containers to have labels added and monitored to keep the container's task running if it is killed.
 Package restart enables containers to have labels added and monitored to keep the container's task running if it is killed.
restart/monitor
v1/linux
v1/linux/proc
v1/shim
v1/shim/client
v1/shim/v1
Package shim is a generated protocol buffer package.
 Package shim is a generated protocol buffer package.
v2
v2/runc
v2/runc/options
Package options is a generated protocol buffer package.
 Package options is a generated protocol buffer package.
v2/runhcs
v2/shim
v2/task
Package task is a generated protocol buffer package.
 Package task is a generated protocol buffer package.
containers
content
diff
events
healthcheck
images
introspection
leases
namespaces
opt
server
server/config
snapshots
tasks
version
btrfs
lcow
native
overlay
proxy
storage
Package storage provides a metadata storage implementation for snapshot drivers.
 Package storage provides a metadata storage implementation for snapshot drivers.
testsuite
windows
hcsshimtypes
Package hcsshimtypes holds the windows runtime specific types Package hcsshimtypes is a generated protocol buffer package.
 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.