containerd

package module
v1.7.22 Latest Latest
Warning

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

Go to latest
Published: Sep 9, 2024 License: Apache-2.0 Imports: 93 Imported by: 2,715

README ¶

containerd banner light mode containerd banner dark mode

PkgGoDev Build Status Nightlies 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 a member of CNCF with 'graduated' status.

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

architecture

Announcements

Hello Kubernetes v1.24!

The containerd project would like to announce containerd v1.6.4. While other prior releases are supported, this latest release and the containerd v1.5.11 release are recommended for Kubernetes v1.24.

We felt it important to announce this, particularly in view of the dockershim removal from this release of Kubernetes.

It should be noted here that moving to CRI integrations has been in the plan for many years. containerd began as part of Docker and was donated to CNCF. containerd remains in use today by Docker/moby/buildkit etc., and has many other adopters. containerd has a namespace that isolates use of containerd from various clients/adopters. The Kubernetes namespace is appropriately named k8s.io. The CRI API and containerd CRI plugin project has, from the start, been an effort to reduce the impact surface for Kubernetes container runtime integration. If you can't tell, we are excited to see this come to fruition.

If you have any concerns or questions, we will be here to answer them in issues, discussions, and/or on slack. Below you will find information/detail about our CRI Integration implementation.

For containerd users already on v1.6.0-v1.6.3, there are known issues addressed by v1.6.4. The issues are primarily related to CNI setup

Now Recruiting

We are a large inclusive OSS project that is welcoming help of any kind shape or form:

  • Documentation help is needed to make the product easier to consume and extend.
  • We need OSS community outreach/organizing help to get the word out; manage and create messaging and educational content; and help with social media, community forums/groups, and google groups.
  • We are actively inviting new security advisors to join the team.
  • New subprojects are being created, core and non-core that could use additional development help.
  • Each of the containerd projects has a list of issues currently being worked on or that need help resolving.
    • If the issue has not already been assigned to someone or has not made recent progress, and you are interested, please inquire.
    • If you are interested in starting with a smaller/beginner-level issue, look for issues with an exp/beginner tag, for example containerd/containerd beginner issues.

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.

Nightly builds

There are nightly builds available for download here. Binaries are generated from main branch every night for Linux and Windows.

Please be aware: nightly builds might have critical bugs, it's not recommended for use in production and no support provided.

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 described 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.

Supported Registries

Any registry which is compliant with the OCI Distribution Specification is supported by containerd.

For configuring registries, see registry host configuration documentation

Features

Client

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


import (
  "context"

  "github.com/containerd/containerd"
  "github.com/containerd/containerd/cio"
  "github.com/containerd/containerd/namespaces"
)


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 while maintaining 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 built-in 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.NewCreator(cio.WithStdio))
defer task.Delete(context)

// the task is now running and has a pid that can be used 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 allows 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
checkpoint, err := client.Pull(context, "myregistry/checkpoints/redis:master")

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

task, err = redis.NewTask(context, cio.NewCreator(cio.WithStdio), 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.

Downloadable 64-bit Intel/AMD binaries of all official releases are available on our releases page.

For other architectures and distribution support, you will find that many Linux distributions package their own containerd and provide it across several architectures, such as Canonical's Ubuntu packaging.

Enabling command auto-completion

Starting with containerd 1.4, the urfave client feature for auto-creation of bash and zsh autocompletion data is enabled. To use the autocomplete feature in a bash shell for example, source the autocomplete/ctr file in your .bashrc, or manually like:

$ source ./contrib/autocomplete/ctr
Distribution of ctr autocomplete for bash and zsh

For bash, copy the contrib/autocomplete/ctr script into /etc/bash_completion.d/ and rename it to ctr. The zsh_autocomplete file is also available and can be used similarly for zsh users.

Provide documentation to users to source this file into their shell if you don't place the autocomplete file in a location where it is automatically loaded for the user's shell environment.

CRI

cri is a containerd plugin implementation of the Kubernetes container runtime interface (CRI). With it, you are able to use containerd as the container runtime for a Kubernetes cluster.

cri

CRI Status

cri is a native plugin of containerd. Since containerd 1.1, the cri plugin is built into the release binaries and enabled by default.

Note: As of containerd 1.5, the cri plugin is merged into the containerd/containerd repo. For example, the source code previously stored under containerd/cri/pkg was moved to containerd/containerd/pkg/cri package.

The cri plugin has reached GA status, representing that it is:

See results on the containerd k8s test dashboard

Validating Your cri Setup

A Kubernetes incubator project, cri-tools, includes programs for exercising CRI implementations. More importantly, cri-tools includes the program critest which is used for running CRI Validation Testing.

CRI Guides

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 catch us in the #containerd and #containerd-dev Slack channels on Cloud Native Computing Foundation's (CNCF) Slack - cloud-native.slack.com. Everyone is welcome to join and chat. Get Invite to CNCF Slack.

Security audit

Security audits for the containerd project are hosted on our website. Please see the security page at containerd.io for more information.

Reporting security issues

Please follow the instructions at containerd/project

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 organization. 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.

Adoption

Interested to see who is using containerd? Are you using containerd in a project? Please add yourself via pull request to our ADOPTERS.md file.

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

View Source
var (
	// ErrCheckpointRWUnsupported is returned if the container runtime does not support checkpoint
	ErrCheckpointRWUnsupported = errors.New("rw checkpoint is only supported on v2 runtimes")
	// ErrMediaTypeNotFound returns an error when a media type in the manifest is unknown
	ErrMediaTypeNotFound = errors.New("media type not found")
)
View Source
var (
	// ErrImageNameNotFoundInIndex is returned when the image name is not found in the index
	ErrImageNameNotFoundInIndex = errors.New("image name not found in index")
	// ErrRuntimeNameNotFoundInIndex is returned when the runtime is not found in the index
	ErrRuntimeNameNotFoundInIndex = errors.New("runtime not found in index")
	// ErrSnapshotterNameNotFoundInIndex is returned when the snapshotter is not found in the index
	ErrSnapshotterNameNotFoundInIndex = errors.New("snapshotter not found in index")
)

Functions ¶

func CheckRuntime ¶ added in v1.3.0

func CheckRuntime(current, expected string) bool

CheckRuntime returns true if the current runtime matches the expected runtime. Providing various parts of the runtime schema will match those parts of the expected runtime

func GetIndexByMediaType ¶ added in v1.3.0

func GetIndexByMediaType(index *imagespec.Index, mt string) (*imagespec.Descriptor, error)

GetIndexByMediaType returns the index in a manifest for the specified media type

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

func NewImageStoreFromClient(client imagesapi.ImagesClient) images.Store

NewImageStoreFromClient returns a new image store client

func NewNamespaceStoreFromClient ¶ added in v1.0.0

func NewNamespaceStoreFromClient(client api.NamespacesClient) namespaces.Store

NewNamespaceStoreFromClient returns a new namespace store

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 ParseSignal deprecated added in v1.2.0

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

ParseSignal parses a given string into a syscall.Signal the rawSignal can be a string with "SIG" prefix, or a signal number in string format.

Deprecated: Use github.com/moby/sys/signal instead.

func WithCheckpointImage ¶ added in v1.3.0

func WithCheckpointImage(ctx context.Context, client *Client, c *containers.Container, index *imagespec.Index, copts *options.CheckpointOptions) error

WithCheckpointImage includes the container image in the checkpoint

func WithCheckpointRW ¶ added in v1.3.0

func WithCheckpointRW(ctx context.Context, client *Client, c *containers.Container, index *imagespec.Index, copts *options.CheckpointOptions) error

WithCheckpointRW includes the rw in the checkpoint

func WithCheckpointRuntime ¶ added in v1.3.0

func WithCheckpointRuntime(ctx context.Context, client *Client, c *containers.Container, index *imagespec.Index, copts *options.CheckpointOptions) error

WithCheckpointRuntime includes the container runtime info

func WithCheckpointTask ¶ added in v1.3.0

func WithCheckpointTask(ctx context.Context, client *Client, c *containers.Container, index *imagespec.Index, copts *options.CheckpointOptions) error

WithCheckpointTask includes the running task

func WithCheckpointTaskExit ¶ added in v1.3.0

func WithCheckpointTaskExit(ctx context.Context, client *Client, c *containers.Container, index *imagespec.Index, copts *options.CheckpointOptions) error

WithCheckpointTaskExit causes the task to exit after checkpoint

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

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

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

WithNoPivotRoot instructs the runtime not to you pivot_root

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 WithRemapperLabels ¶ added in v1.4.0

func WithRemapperLabels(ctrUID, hostUID, ctrGID, hostGID, length uint32) snapshots.Opt

WithRemapperLabels creates the labels used by any supporting snapshotter to shift the filesystem ownership (user namespace mapping) automatically; currently supported by the fuse-overlayfs snapshotter

func WithSchema1Conversion deprecated 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.

Deprecated: use Schema 2 or OCI images.

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 WithoutRefreshedMetadata ¶ added in v1.3.0

func WithoutRefreshedMetadata(i *InfoConfig)

WithoutRefreshedMetadata will use the current metadata attached to the container object

Types ¶

type CheckpointOpts ¶ added in v1.3.0

CheckpointOpts are options to manage the checkpoint operation

type CheckpointTaskInfo ¶ added in v1.0.0

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{}
	// contains filtered or unexported fields
}

CheckpointTaskInfo allows specific checkpoint information to be set for the task

func (*CheckpointTaskInfo) Runtime ¶ added in v1.3.0

func (i *CheckpointTaskInfo) Runtime() string

Runtime name for the container

type CheckpointTaskOpts ¶ added in v1.0.0

type CheckpointTaskOpts func(*CheckpointTaskInfo) error

CheckpointTaskOpts allows the caller to set checkpoint options

func WithCheckpointImagePath ¶ added in v1.3.0

func WithCheckpointImagePath(path string) CheckpointTaskOpts

WithCheckpointImagePath sets image path for checkpoint option

func WithCheckpointName ¶ added in v1.0.0

func WithCheckpointName(name string) CheckpointTaskOpts

WithCheckpointName sets the image name for the checkpoint

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) Conn ¶ added in v1.3.0

func (c *Client) Conn() *grpc.ClientConn

Conn returns the underlying GRPC connection object

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) DefaultNamespace ¶ added in v1.7.0

func (c *Client) DefaultNamespace() string

DefaultNamespace return the default namespace

func (*Client) DiffService ¶ added in v1.0.0

func (c *Client) DiffService() DiffService

DiffService returns the underlying Differ

func (*Client) EventService ¶ added in v1.0.0

func (c *Client) EventService() EventService

EventService returns the underlying event service

func (*Client) Export ¶ added in v1.0.0

func (c *Client) Export(ctx context.Context, w io.Writer, opts ...archive.ExportOpt) error

Export exports images to a Tar stream. The tar archive is in OCI format with a Docker compatible manifest when a single target platform is given.

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

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

GetImage returns an existing image

func (*Client) GetLabel ¶ added in v1.3.0

func (c *Client) GetLabel(ctx context.Context, label string) (string, error)

GetLabel gets a label value from namespace store If there is no default label, an empty string returned with nil error

func (*Client) GetSnapshotterCapabilities ¶ added in v1.7.0

func (c *Client) GetSnapshotterCapabilities(ctx context.Context, snapshotterName string) ([]string, error)

GetSnapshotterCapabilities returns the capabilities of a snapshotter.

func (*Client) GetSnapshotterSupportedPlatforms ¶ added in v1.5.0

func (c *Client) GetSnapshotterSupportedPlatforms(ctx context.Context, snapshotterName string) (platforms.MatchComparer, error)

GetSnapshotterSupportedPlatforms returns a platform matchers which represents the supported platforms for the given snapshotters

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, 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 unreferenced 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. More info: https://github.com/containerd/containerd/blob/main/docs/managed-opt.md.

func (*Client) IntrospectionService ¶ added in v1.0.0

func (c *Client) IntrospectionService() introspection.Service

IntrospectionService returns the underlying Introspection Client

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) LeasesService ¶ added in v1.1.0

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

LeasesService returns the underlying Leases Client

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) LoadSandbox ¶ added in v1.7.0

func (c *Client) LoadSandbox(ctx context.Context, id string) (Sandbox, error)

LoadSandbox laods existing sandbox metadata object using the id

func (*Client) NamespaceService ¶ added in v1.0.0

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

NamespaceService returns the underlying Namespaces Store

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 with the provided id. The id must be unique within the namespace.

func (*Client) NewSandbox ¶ added in v1.7.0

func (c *Client) NewSandbox(ctx context.Context, sandboxID string, opts ...NewSandboxOpts) (Sandbox, error)

NewSandbox creates new sandbox client

func (*Client) Pull ¶ added in v1.0.0

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

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

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) Reconnect ¶ added in v1.1.0

func (c *Client) Reconnect() error

Reconnect re-establishes the GRPC connection to the containerd daemon

func (*Client) Restore ¶ added in v1.3.0

func (c *Client) Restore(ctx context.Context, id string, checkpoint Image, opts ...RestoreOpts) (Container, error)

Restore restores a container from a checkpoint

func (*Client) Runtime ¶ added in v1.5.0

func (c *Client) Runtime() string

Runtime returns the name of the runtime being used

func (*Client) SandboxController ¶ added in v1.7.0

func (c *Client) SandboxController() sandbox.Controller

SandboxController returns the underlying sandbox controller client

func (*Client) SandboxStore ¶ added in v1.7.0

func (c *Client) SandboxStore() sandbox.Store

SandboxStore returns the underlying sandbox store client

func (*Client) Server ¶ added in v1.3.0

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

Server returns server information from the introspection service

func (*Client) SnapshotService ¶ added in v1.0.0

func (c *Client) SnapshotService(snapshotterName string) snapshots.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 *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 ¶ added in v1.0.0

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

TaskService returns the underlying TasksClient

func (*Client) Transfer ¶ added in v1.7.0

func (c *Client) Transfer(ctx context.Context, src interface{}, dest interface{}, opts ...transfer.Opt) error

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

func (*Client) WithLease ¶ added in v1.0.0

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

WithLease attaches a lease on the context

type ClientOpt ¶ added in v1.0.0

type ClientOpt func(c *clientOpts) error

ClientOpt allows callers to set options on the containerd client

func WithCallOpts ¶ added in v1.6.0

func WithCallOpts(opts []grpc.CallOption) ClientOpt

WithCallOpts allows grpc.CallOptions to be set on the connection

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 WithDefaultPlatform ¶ added in v1.3.0

func WithDefaultPlatform(platform platforms.MatchComparer) ClientOpt

WithDefaultPlatform sets the default platform matcher on the client

func WithDefaultRuntime ¶ added in v1.2.0

func WithDefaultRuntime(rt string) ClientOpt

WithDefaultRuntime sets the default runtime on the client

func WithDialOpts ¶ added in v1.0.0

func WithDialOpts(opts []grpc.DialOption) ClientOpt

WithDialOpts allows grpc.DialOptions to be set on the connection

func WithInMemoryServices ¶ added in v1.7.0

func WithInMemoryServices(ic *plugin.InitContext) ClientOpt

WithInMemoryServices is suitable for cases when there is need to use containerd's client from another (in-memory) containerd plugin (such as CRI).

func WithServices ¶ added in v1.1.0

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

type Container interface {
	// ID identifies the container
	ID() string
	// Info returns the underlying container record type
	Info(context.Context, ...InfoOpts) (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]typeurl.Any, error)
	// Update a container
	Update(context.Context, ...UpdateContainerOpts) error
	// Checkpoint creates a checkpoint image of the current container
	Checkpoint(context.Context, string, ...CheckpointOpts) (Image, 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 DiffService ¶ added in v1.1.0

type DiffService interface {
	diff.Comparer
	diff.Applier
}

DiffService handles the computation and application of diffs

func NewDiffServiceFromClient ¶ added in v1.0.0

func NewDiffServiceFromClient(client diffapi.DiffClient) DiffService

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

type EventService ¶ added in v1.1.0

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

EventService handles the publish, forward and subscribe of events.

func NewEventServiceFromClient ¶ added in v1.1.0

func NewEventServiceFromClient(client eventsapi.EventsClient) EventService

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

type ExitStatus ¶ added in v1.0.0

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

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

func NewExitStatus ¶ added in v1.3.0

func NewExitStatus(code uint32, t time.Time, err error) *ExitStatus

NewExitStatus populates an ExitStatus

func (ExitStatus) Error ¶ added in v1.0.0

func (s ExitStatus) Error() error

Error returns the error, if any, that occurred 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 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 Image ¶ added in v1.0.0

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, ...UnpackOpt) 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)
	// Usage returns a usage calculation for the image.
	Usage(context.Context, ...UsageOpt) (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
	// Metadata returns the underlying image metadata
	Metadata() images.Image
	// Platform returns the platform match comparer. Can be nil.
	Platform() platforms.MatchComparer
	// Spec returns the OCI image spec for a given image.
	Spec(ctx context.Context) (ocispec.Image, error)
}

Image describes an image used by containers

func NewImage ¶ added in v1.1.0

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

type ImportOpt func(*importOpts) error

ImportOpt allows the caller to specify import specific options

func WithAllPlatforms ¶ added in v1.3.0

func WithAllPlatforms(allPlatforms bool) ImportOpt

WithAllPlatforms is used to import content for all platforms.

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 WithDiscardUnpackedLayers ¶ added in v1.7.0

func WithDiscardUnpackedLayers() ImportOpt

WithDiscardUnpackedLayers allows the garbage collector to clean up layers from content store after unpacking.

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 WithImportCompression ¶ added in v1.3.0

func WithImportCompression() ImportOpt

WithImportCompression compresses uncompressed layers on import. This is used for import formats which do not include the manifest.

func WithImportPlatform ¶ added in v1.5.15

func WithImportPlatform(platformMacher platforms.MatchComparer) ImportOpt

WithImportPlatform is used to import content for specific platform.

func WithIndexName ¶ added in v1.2.0

func WithIndexName(name string) ImportOpt

WithIndexName creates a tag pointing to the imported index

func WithSkipDigestRef ¶ added in v1.6.0

func WithSkipDigestRef(f func(string) bool) ImportOpt

WithSkipDigestRef is used to specify when to skip applying WithDigestRef. The callback receives an image reference (or an empty string if not specified in the image). When the callback returns true, the skip occurs.

func WithSkipMissing ¶ added in v1.7.12

func WithSkipMissing() ImportOpt

WithSkipMissing allows to import an archive which doesn't contain all the referenced blobs.

type InfoConfig ¶ added in v1.3.0

type InfoConfig struct {
	// Refresh will to a fetch of the latest container metadata
	Refresh bool
}

InfoConfig specifies how container metadata is fetched

type InfoOpts ¶ added in v1.3.0

type InfoOpts func(*InfoConfig)

InfoOpts controls how container metadata is fetched and returned

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

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

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

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

func WithKillExecID ¶ added in v1.0.0

func WithKillExecID(execID string) KillOpts

WithKillExecID specifies the process ID

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 WithAdditionalContainerLabels ¶ added in v1.5.0

func WithAdditionalContainerLabels(labels map[string]string) NewContainerOpts

WithAdditionalContainerLabels adds the provided labels to the container The existing labels are preserved as long as they do not conflict with the added labels.

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

func WithContainerLabels ¶ added in v1.0.0

func WithContainerLabels(labels map[string]string) NewContainerOpts

WithContainerLabels sets the provided labels to the container. The existing labels are cleared. Use WithAdditionalContainerLabels to preserve the existing labels.

func WithImage ¶ added in v1.0.0

func WithImage(i Image) NewContainerOpts

WithImage sets the provided image as the base for the container

func WithImageConfigLabels ¶ added in v1.5.6

func WithImageConfigLabels(image Image) NewContainerOpts

WithImageConfigLabels sets the image config labels on the container. The existing labels are cleared as this is expected to be the first operation in setting up a container's labels. Use WithAdditionalContainerLabels to add/overwrite the existing image config labels.

func WithImageName ¶ added in v1.3.0

func WithImageName(n string) NewContainerOpts

WithImageName allows setting the image name 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 ¶ added in v1.0.0

func WithNewSnapshot(id string, i Image, opts ...snapshots.Opt) 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, opts ...snapshots.Opt) 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 ...oci.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 WithRestoreImage ¶ added in v1.3.0

func WithRestoreImage(ctx context.Context, id string, client *Client, checkpoint Image, index *imagespec.Index) NewContainerOpts

WithRestoreImage restores the image for the container

func WithRestoreRW ¶ added in v1.3.0

func WithRestoreRW(ctx context.Context, id string, client *Client, checkpoint Image, index *imagespec.Index) NewContainerOpts

WithRestoreRW restores the rw layer from the checkpoint for the container

func WithRestoreRuntime ¶ added in v1.3.0

func WithRestoreRuntime(ctx context.Context, id string, client *Client, checkpoint Image, index *imagespec.Index) NewContainerOpts

WithRestoreRuntime restores the runtime for the container

func WithRestoreSpec ¶ added in v1.3.0

func WithRestoreSpec(ctx context.Context, id string, client *Client, checkpoint Image, index *imagespec.Index) NewContainerOpts

WithRestoreSpec restores the spec from the checkpoint for the container

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 WithSandbox ¶ added in v1.7.0

func WithSandbox(sandboxID string) NewContainerOpts

WithSandbox joins the container to a container group (aka sandbox) from the given ID Note: shim runtime must support sandboxes environments.

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 *oci.Spec, opts ...oci.SpecOpts) NewContainerOpts

WithSpec sets the provided spec on the container

type NewSandboxOpts ¶ added in v1.7.0

type NewSandboxOpts func(ctx context.Context, client *Client, sandbox *api.Sandbox) error

NewSandboxOpts is a sandbox options and extensions to be provided by client

func WithSandboxExtension ¶ added in v1.7.0

func WithSandboxExtension(name string, ext interface{}) NewSandboxOpts

WithSandboxExtension attaches an extension to sandbox

func WithSandboxLabels ¶ added in v1.7.0

func WithSandboxLabels(labels map[string]string) NewSandboxOpts

WithSandboxLabels attaches map of labels to sandbox

func WithSandboxRuntime ¶ added in v1.7.0

func WithSandboxRuntime(name string, options interface{}) NewSandboxOpts

WithSandboxRuntime allows a user to specify the runtime to be used to run a sandbox

func WithSandboxSpec ¶ added in v1.7.0

func WithSandboxSpec(s *oci.Spec, opts ...oci.SpecOpts) NewSandboxOpts

WithSandboxSpec will provide the sandbox runtime spec

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 WithGIDOwner ¶ added in v1.4.0

func WithGIDOwner(gid uint32) NewTaskOpts

WithGIDOwner allows console I/O to work with the remapped GID in user namespace

func WithRestoreImagePath ¶ added in v1.3.0

func WithRestoreImagePath(path string) NewTaskOpts

WithRestoreImagePath sets image path for create option

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 WithRuntimePath ¶ added in v1.6.0

func WithRuntimePath(absRuntimePath string) NewTaskOpts

WithRuntimePath will force task service to use a custom path to the runtime binary instead of resolving it from runtime name.

func WithShimCgroup ¶ added in v1.3.0

func WithShimCgroup(path string) NewTaskOpts

WithShimCgroup sets the existing cgroup for the shim

func WithTaskCheckpoint ¶ added in v1.0.0

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

func WithUIDOwner ¶ added in v1.4.0

func WithUIDOwner(uid uint32) NewTaskOpts

WithUIDOwner allows console I/O to work with the remapped UID in user namespace

type Process ¶ added in v1.0.0

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 height 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 ¶ 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
}

ProcessInfo provides platform specific process information

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

	// 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.
	// It is done simultaneously for schema 2 images when they are pulled.
	// If an image is not unpacked on pull, it can be unpacked any time
	// afterwards. Unpacking is required to run an image.
	Unpack bool

	// UnpackOpts handles options to the unpack call.
	UnpackOpts []UnpackOpt

	// Snapshotter used for unpacking
	Snapshotter string

	// SnapshotterOpts are additional options to be passed to a snapshotter during pull
	SnapshotterOpts []snapshots.Opt

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

	// HandlerWrapper wraps the handler which gets sent to dispatch.
	// Unlike BaseHandlers, this can run before and after the built
	// in handlers, allowing operations to run on the descriptor
	// after it has completed transferring.
	HandlerWrapper func(images.Handler) 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.
	//
	// Deprecated: use Schema 2 or OCI images.
	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

	// MaxConcurrentDownloads is the max concurrent content downloads for each pull.
	MaxConcurrentDownloads int

	// MaxConcurrentUploadedLayers is the max concurrent uploaded layers for each push.
	MaxConcurrentUploadedLayers int

	// AllMetadata downloads all manifests and known-configuration files
	AllMetadata bool

	// ChildLabelMap sets the labels used to reference child objects in the content
	// store. By default, all GC reference labels will be set for all fetched content.
	ChildLabelMap func(ocispec.Descriptor) []string
}

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 WithAllMetadata ¶ added in v1.3.0

func WithAllMetadata() RemoteOpt

WithAllMetadata downloads all manifests and known-configuration files

func WithChildLabelMap ¶ added in v1.4.0

func WithChildLabelMap(fn func(ocispec.Descriptor) []string) RemoteOpt

WithChildLabelMap sets the map function used to define the labels set on referenced child content in the content store. This can be used to overwrite the default GC labels or filter which labels get set for content. The default is `images.ChildGCLabels`.

func WithImageHandler ¶ added in v1.0.0

func WithImageHandler(h images.Handler) RemoteOpt

WithImageHandler adds a base handler to be called on dispatch.

func WithImageHandlerWrapper ¶ added in v1.3.0

func WithImageHandlerWrapper(w func(images.Handler) images.Handler) RemoteOpt

WithImageHandlerWrapper wraps the handlers to be called on dispatch.

func WithMaxConcurrentDownloads ¶ added in v1.3.0

func WithMaxConcurrentDownloads(max int) RemoteOpt

WithMaxConcurrentDownloads sets max concurrent download limit.

func WithMaxConcurrentUploadedLayers ¶ added in v1.5.0

func WithMaxConcurrentUploadedLayers(max int) RemoteOpt

WithMaxConcurrentUploadedLayers sets max concurrent uploaded layer limit.

func WithPlatform ¶ added in v1.1.0

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 ¶ 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, opts ...snapshots.Opt) 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.

func WithUnpackOpts ¶ added in v1.4.0

func WithUnpackOpts(opts []UnpackOpt) RemoteOpt

WithUnpackOpts is used to add unpack options to the unpacker.

type RestoreOpts ¶ added in v1.3.0

RestoreOpts are options to manage the restore operation

type Sandbox ¶ added in v1.7.0

type Sandbox interface {
	// ID is a sandbox identifier
	ID() string
	// PID returns sandbox's process PID or error if its not yet started.
	PID() (uint32, error)
	// NewContainer creates new container that will belong to this sandbox
	NewContainer(ctx context.Context, id string, opts ...NewContainerOpts) (Container, error)
	// Labels returns the labels set on the sandbox
	Labels(ctx context.Context) (map[string]string, error)
	// Start starts new sandbox instance
	Start(ctx context.Context) error
	// Stop sends stop request to the shim instance.
	Stop(ctx context.Context) error
	// Wait blocks until sandbox process exits.
	Wait(ctx context.Context) (<-chan ExitStatus, error)
	// Shutdown removes sandbox from the metadata store and shutdowns shim instance.
	Shutdown(ctx context.Context) error
}

Sandbox is a high level client to containerd's sandboxes.

type ServerInfo ¶ added in v1.3.0

type ServerInfo struct {
	UUID string
}

ServerInfo represents the introspected server information

type ServicesOpt ¶ added in v1.1.0

type ServicesOpt func(c *services)

ServicesOpt allows callers to set options on the services

func WithContainerClient ¶ added in v1.6.0

func WithContainerClient(containerService containersapi.ContainersClient) ServicesOpt

WithContainerClient sets the container service to use using a containers client.

func WithContainerStore ¶ added in v1.6.0

func WithContainerStore(containerStore containers.Store) ServicesOpt

WithContainerStore sets the container store.

func WithContentStore ¶ added in v1.1.0

func WithContentStore(contentStore content.Store) ServicesOpt

WithContentStore sets the content store.

func WithDiffClient ¶ added in v1.6.0

func WithDiffClient(diffService diff.DiffClient) ServicesOpt

WithDiffClient sets the diff service to use from a diff client.

func WithDiffService ¶ added in v1.1.0

func WithDiffService(diffService DiffService) ServicesOpt

WithDiffService sets the diff store.

func WithEventService ¶ added in v1.1.0

func WithEventService(eventService EventService) ServicesOpt

WithEventService sets the event service.

func WithImageClient ¶ added in v1.6.0

func WithImageClient(imageService imagesapi.ImagesClient) ServicesOpt

WithImageClient sets the image service to use using an images client.

func WithImageStore ¶ added in v1.6.0

func WithImageStore(imageStore images.Store) ServicesOpt

WithImageStore sets the image store.

func WithIntrospectionClient ¶ added in v1.6.0

func WithIntrospectionClient(in introspectionapi.IntrospectionClient) ServicesOpt

WithIntrospectionClient sets the introspection service using an introspection client.

func WithIntrospectionService ¶ added in v1.4.0

func WithIntrospectionService(in introspection.Service) ServicesOpt

WithIntrospectionService sets the introspection service.

func WithLeasesService ¶ added in v1.1.0

func WithLeasesService(leasesService leases.Manager) ServicesOpt

WithLeasesService sets the lease service.

func WithNamespaceClient ¶ added in v1.6.0

func WithNamespaceClient(namespaceService namespacesapi.NamespacesClient) ServicesOpt

WithNamespaceClient sets the namespace service using a namespaces client.

func WithNamespaceService ¶ added in v1.1.0

func WithNamespaceService(namespaceService namespaces.Store) ServicesOpt

WithNamespaceService sets the namespace service.

func WithSandboxController ¶ added in v1.7.0

func WithSandboxController(client sandbox.Controller) ServicesOpt

WithSandboxController sets the sandbox controller.

func WithSandboxStore ¶ added in v1.7.0

func WithSandboxStore(client sandbox.Store) ServicesOpt

WithSandboxStore sets the sandbox store.

func WithSnapshotters ¶ added in v1.1.0

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

WithSnapshotters sets the snapshotters.

func WithTaskClient ¶ added in v1.6.0

func WithTaskClient(taskService tasks.TasksClient) ServicesOpt

WithTaskClient sets the task service to use from a tasks client.

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, 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 pushed and pulled from a remote resource.
	//
	// Additional software like CRIU maybe required to checkpoint and restore tasks
	// NOTE: Checkpoint supports to dump task information to a directory, in this way,
	// an empty OCI Index will be returned.
	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)
	// Spec returns the current OCI specification for the task
	Spec(context.Context) (*oci.Spec, 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{}
	// RuntimePath is an absolute path that can be used to overwrite path
	// to a shim runtime binary.
	RuntimePath string
	// contains filtered or unexported fields
}

TaskInfo sets options for task creation

func (*TaskInfo) Runtime ¶ added in v1.3.0

func (i *TaskInfo) Runtime() string

Runtime name for the container

type UnpackConfig ¶ added in v1.3.0

type UnpackConfig struct {
	// ApplyOpts for applying a diff to a snapshotter
	ApplyOpts []diff.ApplyOpt
	// SnapshotOpts for configuring a snapshotter
	SnapshotOpts []snapshots.Opt
	// CheckPlatformSupported is whether to validate that a snapshotter
	// supports an image's platform before unpacking
	CheckPlatformSupported bool
	// DuplicationSuppressor is used to make sure that there is only one
	// in-flight fetch request or unpack handler for a given descriptor's
	// digest or chain ID.
	DuplicationSuppressor kmutex.KeyedLocker
}

UnpackConfig provides configuration for the unpack of an image

type UnpackOpt ¶ added in v1.3.0

type UnpackOpt func(context.Context, *UnpackConfig) error

UnpackOpt provides configuration for unpack

func WithSnapshotterPlatformCheck ¶ added in v1.5.0

func WithSnapshotterPlatformCheck() UnpackOpt

WithSnapshotterPlatformCheck sets `CheckPlatformSupported` on the UnpackConfig

func WithUnpackApplyOpts ¶ added in v1.7.14

func WithUnpackApplyOpts(opts ...diff.ApplyOpt) UnpackOpt

WithUnpackApplyOpts appends new apply options on the UnpackConfig.

func WithUnpackDuplicationSuppressor ¶ added in v1.6.3

func WithUnpackDuplicationSuppressor(suppressor kmutex.KeyedLocker) UnpackOpt

WithUnpackDuplicationSuppressor sets `DuplicationSuppressor` on the UnpackConfig.

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{}
	// Annotations allows arbitrary and/or experimental resource constraints for task update
	Annotations map[string]string
}

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 WithAnnotations ¶ added in v1.5.0

func WithAnnotations(annotations map[string]string) UpdateTaskOpts

WithAnnotations sets the provided annotations for task updates.

func WithResources ¶ added in v1.0.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 UsageOpt ¶ added in v1.3.0

type UsageOpt func(*usageOptions) error

UsageOpt is used to configure the usage calculation

func WithManifestUsage ¶ added in v1.3.0

func WithManifestUsage() UsageOpt

WithManifestUsage is used to get the usage for an image based on what is reported by the manifests rather than what exists in the content store. NOTE: This function is best used with the manifest limit set to get a consistent value, otherwise non-existent manifests will be excluded.

func WithSnapshotUsage ¶ added in v1.3.0

func WithSnapshotUsage() UsageOpt

WithSnapshotUsage will check for referenced snapshots from the image objects and include the snapshot size in the total usage.

func WithUsageManifestLimit ¶ added in v1.3.0

func WithUsageManifestLimit(i int) UsageOpt

WithUsageManifestLimit sets the limit to the number of manifests which will be walked for usage. Setting this value to 0 will require all manifests to be walked, returning ErrNotFound if manifests are missing. NOTE: By default all manifests which exist will be walked and any non-existent manifests and their subobjects will be ignored.

type Version ¶

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

Version of containerd

Directories ¶

Path Synopsis
api module
cmd
ctr
contrib
Package defaults provides several common defaults for interacting with containerd.
Package defaults provides several common defaults for interacting with containerd.
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.
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.
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
converter
Package converter provides image converter
Package converter provides image converter
remote
Package remote contains gRPC implementation of internalapi.RuntimeService and internalapi.ImageManagerService.
Package remote contains gRPC implementation of internalapi.RuntimeService and internalapi.ImageManagerService.
client Module
log
Package metadata stores all labels and object specific metadata by namespace.
Package metadata stores all labels and object specific metadata by namespace.
pkg
atomicfile
Package atomicfile provides a mechanism (on Unix-like platforms) to present a consistent view of a file to separate processes even while the file is being written.
Package atomicfile provides a mechanism (on Unix-like platforms) to present a consistent view of a file to separate processes even while the file is being written.
cap
Package cap provides Linux capability utility
Package cap provides Linux capability utility
cleanup
Package providing utilies to help cleanup
Package providing utilies to help cleanup
cri
cri/server/bandwidth
Package bandwidth provides utilities for bandwidth shaping
Package bandwidth provides utilities for bandwidth shaping
cri/streaming/portforward
Package portforward contains server-side logic for handling port forwarding requests.
Package portforward contains server-side logic for handling port forwarding requests.
cri/streaming/remotecommand
Package remotecommand contains functions related to executing commands in and attaching to pods.
Package remotecommand contains functions related to executing commands in and attaching to pods.
epoch
Package epoch provides SOURCE_DATE_EPOCH utilities.
Package epoch provides SOURCE_DATE_EPOCH utilities.
failpoint
Package failpoint provides the code point in the path, which can be controlled by user's variable.
Package failpoint provides the code point in the path, which can be controlled by user's variable.
fifosync
Package fifosync provides a pattern on Unix-like operating systems for synchronizing across processes using Unix FIFOs (named pipes).
Package fifosync provides a pattern on Unix-like operating systems for synchronizing across processes using Unix FIFOs (named pipes).
kmutex
Package kmutex provides synchronization primitives to lock/unlock resource by unique key.
Package kmutex provides synchronization primitives to lock/unlock resource by unique key.
nri
oom
os
progress
Package progress assists in displaying human readable progress information.
Package progress assists in displaying human readable progress information.
randutil
Package randutil provides utilities for cyrpto/rand.
Package randutil provides utilities for cyrpto/rand.
rdt
seed
Package seed provides an initializer for the global math/rand seed.
Package seed provides an initializer for the global math/rand seed.
truncindex
Package truncindex provides a general 'index tree', used by Docker in order to be able to reference containers by only a few unambiguous characters of their id.
Package truncindex provides a general 'index tree', used by Docker in order to be able to reference containers by only a few unambiguous characters of their id.
userns
Deprecated: use github.com/moby/sys/userns
Deprecated: use github.com/moby/sys/userns
plugins
proto
Package proto provides convinient aliases that make google.golang.org/protobuf migration easier.
Package proto provides convinient aliases that make google.golang.org/protobuf migration easier.
types
Package types provides convinient aliases that make google.golang.org/protobuf migration easier.
Package types provides convinient aliases that make google.golang.org/protobuf migration easier.
docker
Package docker is deprecated, and has moved to github.com/distribution/reference.
Package docker is deprecated, and has moved to github.com/distribution/reference.
docker/config
Package config contains utilities for helping configure the Docker resolver
Package config contains utilities for helping configure the Docker resolver
docker/schema1
Package schema1 provides a converter to fetch an image formatted in Docker Image Manifest v2, Schema 1.
Package schema1 provides a converter to fetch an image formatted in Docker Image Manifest v2, Schema 1.
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.
v1
v1/shim/v1
Code generated by protoc-gen-go-ttrpc.
Code generated by protoc-gen-go-ttrpc.
v2
opt
storage
Package storage provides a metadata storage implementation for snapshot drivers.
Package storage provides a metadata storage implementation for snapshot drivers.
sys
third_party

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL