README ¶
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.
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.
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
- func GetOCIStopSignal(ctx context.Context, image Image, defaultSignal string) (string, error)
- func GetStopSignal(ctx context.Context, container Container, defaultSignal syscall.Signal) (syscall.Signal, error)
- func NewImageStoreFromClient(client imagesapi.ImagesClient) images.Store
- func NewNamespaceStoreFromClient(client api.NamespacesClient) namespaces.Store
- func NewRemoteContainerStore(client containersapi.ContainersClient) containers.Store
- func ParseSignal(rawSignal string) (syscall.Signal, error)
- func WithInstallLibs(c *InstallConfig)
- func WithInstallReplace(c *InstallConfig)
- func WithKillAll(ctx context.Context, i *KillInfo) error
- func WithNoNewKeyring(ctx context.Context, c *Client, ti *TaskInfo) error
- func WithNoPivotRoot(_ context.Context, _ *Client, info *TaskInfo) error
- func WithProcessKill(ctx context.Context, p Process) error
- func WithPullUnpack(_ *Client, c *RemoteContext) error
- func WithSchema1Conversion(client *Client, c *RemoteContext) error
- func WithSnapshotCleanup(ctx context.Context, client *Client, c containers.Container) error
- func WithStdinCloser(r *IOCloseInfo)
- type CheckpointTaskInfo
- type CheckpointTaskOpts
- type Client
- func (c *Client) Close() error
- func (c *Client) ContainerService() containers.Store
- func (c *Client) Containers(ctx context.Context, filters ...string) ([]Container, error)
- func (c *Client) ContentStore() content.Store
- func (c *Client) DiffService() DiffService
- func (c *Client) EventService() EventService
- func (c *Client) Export(ctx context.Context, exporter images.Exporter, desc ocispec.Descriptor, ...) (io.ReadCloser, error)
- func (c *Client) Fetch(ctx context.Context, ref string, opts ...RemoteOpt) (images.Image, error)
- func (c *Client) GetImage(ctx context.Context, ref string) (Image, error)
- func (c *Client) HealthService() grpc_health_v1.HealthClient
- func (c *Client) ImageService() images.Store
- func (c *Client) Import(ctx context.Context, reader io.Reader, opts ...ImportOpt) ([]images.Image, error)
- func (c *Client) Install(ctx context.Context, image Image, opts ...InstallOpts) error
- func (c *Client) IntrospectionService() introspectionapi.IntrospectionClient
- func (c *Client) IsServing(ctx context.Context) (bool, error)
- func (c *Client) LeasesService() leases.Manager
- func (c *Client) ListImages(ctx context.Context, filters ...string) ([]Image, error)
- func (c *Client) LoadContainer(ctx context.Context, id string) (Container, error)
- func (c *Client) NamespaceService() namespaces.Store
- func (c *Client) NewContainer(ctx context.Context, id string, opts ...NewContainerOpts) (Container, error)
- func (c *Client) Pull(ctx context.Context, ref string, opts ...RemoteOpt) (Image, error)
- func (c *Client) Push(ctx context.Context, ref string, desc ocispec.Descriptor, opts ...RemoteOpt) error
- func (c *Client) Reconnect() error
- func (c *Client) SnapshotService(snapshotterName string) snapshots.Snapshotter
- func (c *Client) Subscribe(ctx context.Context, filters ...string) (ch <-chan *events.Envelope, errs <-chan error)
- func (c *Client) TaskService() tasks.TasksClient
- func (c *Client) Version(ctx context.Context) (Version, error)
- func (c *Client) VersionService() versionservice.VersionClient
- func (c *Client) WithLease(ctx context.Context) (context.Context, func(context.Context) error, error)
- type ClientOpt
- type Container
- type DeleteOpts
- type DiffService
- type EventService
- type ExitStatus
- type ExportOpt
- type IOCloseInfo
- type IOCloserOpts
- type Image
- type ImportOpt
- type InstallConfig
- type InstallOpts
- type KillInfo
- type KillOpts
- type NewContainerOpts
- func WithCheckpoint(im Image, snapshotKey string) NewContainerOpts
- func WithContainerExtension(name string, extension interface{}) NewContainerOpts
- func WithContainerLabels(labels map[string]string) NewContainerOpts
- func WithImage(i Image) NewContainerOpts
- func WithImageStopSignal(image Image, defaultSignal string) NewContainerOpts
- func WithNewSnapshot(id string, i Image) NewContainerOpts
- func WithNewSnapshotView(id string, i Image) NewContainerOpts
- func WithNewSpec(opts ...oci.SpecOpts) NewContainerOpts
- func WithRemappedSnapshot(id string, i Image, uid, gid uint32) NewContainerOpts
- func WithRemappedSnapshotView(id string, i Image, uid, gid uint32) NewContainerOpts
- func WithRuntime(name string, options interface{}) NewContainerOpts
- func WithSnapshot(id string) NewContainerOpts
- func WithSnapshotter(name string) NewContainerOpts
- func WithSpec(s *oci.Spec, opts ...oci.SpecOpts) NewContainerOpts
- type NewTaskOpts
- type Process
- type ProcessDeleteOpts
- type ProcessInfo
- type ProcessStatus
- type RemoteContext
- type RemoteOpt
- func WithImageHandler(h images.Handler) RemoteOpt
- func WithPlatform(platform string) RemoteOpt
- func WithPlatformMatcher(m platforms.MatchComparer) RemoteOpt
- func WithPullLabel(key, value string) RemoteOpt
- func WithPullLabels(labels map[string]string) RemoteOpt
- func WithPullSnapshotter(snapshotterName string) RemoteOpt
- func WithResolver(resolver remotes.Resolver) RemoteOpt
- type ServicesOpt
- func WithContainerService(containerService containersapi.ContainersClient) ServicesOpt
- func WithContentStore(contentStore content.Store) ServicesOpt
- func WithDiffService(diffService diff.DiffClient) ServicesOpt
- func WithEventService(eventService EventService) ServicesOpt
- func WithImageService(imageService imagesapi.ImagesClient) ServicesOpt
- func WithLeasesService(leasesService leases.Manager) ServicesOpt
- func WithNamespaceService(namespaceService namespacesapi.NamespacesClient) ServicesOpt
- func WithSnapshotters(snapshotters map[string]snapshots.Snapshotter) ServicesOpt
- func WithTaskService(taskService tasks.TasksClient) ServicesOpt
- type Status
- type Task
- type TaskInfo
- type UpdateContainerOpts
- type UpdateTaskInfo
- type UpdateTaskOpts
- type Version
Constants ¶
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" )
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
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.6
GetOCIStopSignal retrieves the stop signal specified in the OCI image config
func GetStopSignal ¶ added in v1.2.6
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.6
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.6
func WithInstallLibs(c *InstallConfig)
WithInstallLibs installs libs from the image
func WithInstallReplace ¶ added in v1.2.6
func WithInstallReplace(c *InstallConfig)
WithInstallReplace will replace existing files
func WithKillAll ¶
WithKillAll kills all processes for a task
func WithNoNewKeyring ¶ added in v1.2.6
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 ¶
WithNoPivotRoot instructs the runtime not to you pivot_root
func WithProcessKill ¶
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 ¶
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 ¶
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) ContainerService ¶
func (c *Client) ContainerService() containers.Store
ContainerService returns the underlying container Store
func (*Client) Containers ¶
Containers returns all containers created in containerd
func (*Client) ContentStore ¶
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.6
Fetch downloads the provided content into containerd's content store and returns a non-platform specific image reference
func (*Client) HealthService ¶
func (c *Client) HealthService() grpc_health_v1.HealthClient
HealthService returns the underlying GRPC HealthClient
func (*Client) ImageService ¶
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) IntrospectionService ¶
func (c *Client) IntrospectionService() introspectionapi.IntrospectionClient
IntrospectionService returns the underlying Introspection Client
func (*Client) IsServing ¶
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 ¶
LeasesService returns the underlying Leases Client
func (*Client) ListImages ¶
ListImages returns all existing images
func (*Client) LoadContainer ¶
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 ¶
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) 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) VersionService ¶
func (c *Client) VersionService() versionservice.VersionClient
VersionService returns the underlying VersionClient
type ClientOpt ¶
type ClientOpt func(c *clientOpts) error
ClientOpt allows callers to set options on the containerd client
func WithDefaultNamespace ¶
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.6
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.6
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 ¶
DeleteOpts allows the caller to set options for the deletion of a container
type DiffService ¶
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 ¶
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 NewImageWithPlatform ¶ added in v1.2.6
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.6
WithDigestRef is used to create digest images for each manifest in the index.
func WithImageRefTranslator ¶ added in v1.2.6
WithImageRefTranslator is used to translate the index reference to an image reference for the image store.
func WithIndexName ¶ added in v1.2.6
WithIndexName creates a tag pointing to the imported index
type InstallConfig ¶ added in v1.2.6
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.6
type InstallOpts func(*InstallConfig)
InstallOpts configures binary installs
func WithInstallPath ¶ added in v1.2.6
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 ¶
KillOpts allows options to be set for the killing of a process
func WithKillExecID ¶
WithKillExecID specifies the process ID
type NewContainerOpts ¶
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.6
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.
type NewTaskOpts ¶
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 ¶
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 ¶
WithImageHandler adds a base handler to be called on dispatch.
func WithPlatform ¶
WithPlatform allows the caller to specify a platform to retrieve content for
func WithPlatformMatcher ¶ added in v1.2.6
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 ¶
WithPullLabel sets a label to be associated with a pulled reference
func WithPullLabels ¶
WithPullLabels associates a set of labels to a pulled reference
func WithPullSnapshotter ¶
WithPullSnapshotter specifies snapshotter name used for unpacking
func WithResolver ¶
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 ¶
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 ¶
func WithResources(resources interface{}) UpdateTaskOpts
WithResources sets the provided resources for task updates. Resources must be either a *specs.LinuxResources or a *specs.WindowsResources
Source Files ¶
- client.go
- client_opts.go
- container.go
- container_opts.go
- container_opts_unix.go
- containerstore.go
- diff.go
- events.go
- export.go
- grpc.go
- image.go
- image_store.go
- import.go
- install.go
- install_opts.go
- lease.go
- namespaces.go
- process.go
- services.go
- signal_map_linux.go
- signals.go
- snapshotter_default_linux.go
- task.go
- task_opts.go
- task_opts_unix.go
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. |
cmd
|
|
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. |
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 |
metrics
|
|
Package namespaces provides tools for working with namespaces across containerd.
|
Package namespaces provides tools for working with namespaces across containerd. |
pkg
|
|
progress
Package progress assists in displaying human readable progress information.
|
Package progress assists in displaying human readable progress information. |
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. |
linux/runctypes
Package runctypes is a generated protocol buffer package.
|
Package runctypes is a generated protocol buffer package. |
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/shim/v1
Package shim is a generated protocol buffer package.
|
Package shim is a generated protocol buffer package. |
v2/runc/options
Package options is a generated protocol buffer package.
|
Package options is a generated protocol buffer package. |
v2/runhcs/options
Package options is a generated protocol buffer package.
|
Package options is a generated protocol buffer package. |
v2/task
Package task is a generated protocol buffer package.
|
Package task is a generated protocol buffer package. |
storage
Package storage provides a metadata storage implementation for snapshot drivers.
|
Package storage provides a metadata storage implementation for snapshot drivers. |
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. |