Package: containerd
containerd API Python packageThis repository provides a Python3 API tocontainerd's(gRPC) API, directly generated from theoriginal containerd.protoAPI
definitions. As it is
generated from the protocol files, this Python package does not aim to be a
fully Pythonesque package. In consequence, the usual idiosyncrasies of gRPC and
protoc shine through.Note:with Python2 going end-of-life in January 2020 we don't support
Python2 in this package at this very late time in the lifecycle.VersioningThe versioning of this package complies withPEP
440.The version is composed of the version of the supported containerd API (e.g. 1.2
or 1.3) and an incremental number for each pycontainerd release for that
specific containerd API version (starting from 0) connected with a '.' (a dot).Ideally the Python containerd API has to be generated only once per containerd
API version, resulting in x.y.0 package versions.The result is version numbers like:1.2.1 for the second release for API 1.21.3.0 for the first release for API 1.3LicenseThis project is licensed asApache License, Version 2.0(SPDX-License-Identifier: Apache-2.0).You can obtain the full license text from the fileLicenseof this repository.InstallationInstallation depends on your starting point:You get the packages fromhttps://pypi.org/project/containerdYou have apycontainerdPython Wheel package (something likecontainerd-x.y.z-py3-none-any.whl).You only have the source code (the result of cloning the git repository).DependenciesPython3 PIP is needed for Wheel installations (either from a ready Wheel package
or from a self-built package). PIP takes care of installing all the Python
packages listed as dependencies. Runtime dependencies are nevertheless listed
below.Installation from PyPI (AKA PIP)Simply let PIP install the latest release for the corresponding containerd API version.For example, for the container API version 1.5:sudo pip3 install "containerd==1.5.*"The quotes are important to avoid that the shell tries to resolve the "*" and passes it untouched to PIP.Installation from Wheel packageGo to the directory where the wheel package is available and run:sudopip3installcontainerd-<x.y.z>-py3-none-any.whlBeingcontainerd-<x.y.z>-py3-none-any.whlthe filename of the wheel package.NOTE: a global installation is required (or rather, more convenient) because
thecontainerdAPI socket is usually only reachable forroot.Installation from source codeAdditionally, if building from source code you'll also needmake.A Makefile is being provided that takes care ofBuilding the Wheel packageInstalling the Wheel packageGet into the directory corresponding the API version of your containerd installation and run following:makeinstallThe second step is under the hood simply running the installation of the wheel
package explained above. Including the global installation, therefore asudoexecution is asking for the user's password (assuming the user has that right).Package Structure and UsageThe resulting Wheel package provides following Python packages (they have to be
imported individually), providing multiple modules:containerd.eventscontainerd.services.containers.v1containerd.services.content.v1containerd.services.diff.v1containerd.services.events.v1containerd.services.images.v1containerd.services.introspection.v1containerd.services.leases.v1containerd.services.namespaces.v1containerd.services.snapshots.v1containerd.services.tasks.v1containerd.services.version.v1containerd.typescontainerd.types.taskscontainerd.protobuf (note: this is not a protobuf alias)containerd.vendor.gogoprotoIn order to get the modules being provided by a package you can run:python3-c'import <package> ; help(<package>)'For example, forcontainerd.events:python3-c'import containerd.events ; help(containerd.events)'ExamplesList All NamespacesThe following simple example queries containerd for its list of available
containerd namespaces. Make sure you have the necessary privileges to connect to
containerd; you may need to run this script as root:importgrpcfromcontainerd.services.namespaces.v1importnamespace_pb2_grpc,namespace_pb2withgrpc.insecure_channel('unix:///run/containerd/containerd.sock')aschannel:namespacev1=namespace_pb2_grpc.NamespacesStub(channel)namespaces=namespacev1.List(namespace_pb2.ListNamespacesRequest()).namespacesfornamespaceinnamespaces:print('namespace:',namespace.name)Usually, you want to add proper error handling. This is just a very simplistic
example to illustrate the principle.List Containers in a Specific NamespaceSeveral of containerd's APIs are namespaced. That is, they work only on a single
namespace at a time. The namespace applies on the level of individual service
calls and needs to be specified as an (additional) metadata element to these
calls. If not specified, it the namespace will default to the namespace nameddefault. The following example lists all containers in the"moby"namespace;
this is the containerd namespace used by Docker.importgrpcfromcontainerd.services.containers.v1importcontainers_pb2_grpc,containers_pb2withgrpc.insecure_channel('unix:///run/containerd/containerd.sock')aschannel:containersv1=containers_pb2_grpc.ContainersStub(channel)containers=containersv1.List(containers_pb2.ListContainersRequest(),metadata=(('containerd-namespace','moby'),)).containersforcontainerincontainers:print('container ID:',container.id)Watch containerd Events FlowingContainerd events can be easily read from the endless event stream via thecontainerd.services.events.v1API, using theSubscribeservice. The
following example subscribes to all events and then prints their type and
contents as the events come:importgrpcfromcontainerd.services.events.v1importunwrap,events_pb2,events_pb2_grpcfromgoogle.protobufimportany_pb2withgrpc.insecure_channel('unix:///run/containerd/containerd.sock')aschannel:print("waiting for containerd events...")eventsv1=events_pb2_grpc.EventsStub(channel)forevineventsv1.Subscribe(events_pb2.SubscribeRequest()):print('event type: ',ev.event.type_url)print('value: ',unwrap(ev))Note:containerd.services.events.v1.unwrap(envelope)is a convenience
function which unwraps the event object inside an event envelope returned bySubscribe(): the unwrapped event object is returned as a Python object of
sub classcontainerd.events.*(as opposed to the arbitrary "any" binary
value inside the event envelope).Executable ProgramsTo help containerd client developers getting started, we've included two simple
examples which are also made available as the CLI programslsctrandwatchctr(source code inexamples/) when cloning the repository.You first have to install the wheel package for thecontainerdpackage.lsctrlists all containerd containers in all namespaces. It is basically
kind of an all-in-one combination of thectrcommands for namespaces,
containers, and tasks in a single command.watchctrwatches containerd events, such as container creation, start, stop,
et cetera, and then prints them to the terminal.To check that it works, run thelsctrcommand: this should list all available
containerd containers, across all containerd namespaces (remember to usesudoin case you don't have the necessary privileges as an ordinary user to talk to
containerd):sudolsctrThis should spit out something like this, when running on a recent Docker CE
installation, which uses containerd under the hood:moby
  ⤏ labels (0):
  ▩ container: 0eeb9e2862e9f68e832a2e2c60a2e44e74d54b05266532cf19b112f4d959e3fb
    ▷ PID: 3359 ⚐ status: RUNNING
    ⚙ runtime: io.containerd.runtime.v1.linux
    ⤏ labels (1):
        "com.docker/engine.bundle.path": "/var/run/docker/containerd/0eeb9e2862e9f68e832a2e2c60a2e44e74d54b05266532cf19b112f4d959e3fb"
    ◷ created: 2019-09-04 07:24:32.646856 ◷ updated: 2019-09-04 07:24:32.646856
  ▩ container: 1663afd0ddc6e0bba30b7fcc27b26044ece6022d970e32731db5dcb807b168df
    ▷ PID: 66062 ⚐ status: RUNNING
    ⚙ runtime: io.containerd.runtime.v1.linux
    ⤏ labels (1):
        "com.docker/engine.bundle.path": "/var/run/docker/containerd/1663afd0ddc6e0bba30b7fcc27b26044ece6022d970e32731db5dcb807b168df"
    ◷ created: 2019-08-16 08:08:21.471493 ◷ updated: 2019-08-16 08:08:21.471493
...You can uselsctr -hto see the few CLI options available.Package RequirementsThe following Python packages are required:grpcio– gRPC for Python; required in
order to communicate with containerd. This is a runtime dependency.protobuf– protobuf for Python;
required in order to communicate with containerd. This is a runtime
dependency.(optional)grpcio-tools– only required when re-generating the containerd
API Python code usinggenpb2.sh.Python ContainerD APIAPI Package (Re)GenerationIn case you need to regenerate or update the Python code for the containerd API,
in the top-level directory of this repository, run:./genpb2.shNormally, you should not need to regenerate the grpc/pb2 Python modules unless
you are a project contributor or maintainer.Project OrganizationThe overall directory structure of the Python containerd API package is as
follows (inside theapi_1.x/directories):containerd/contains the Python modules generated by protoc as well as a
very few hand-made modules. In order to avoid polluting the top-level package
namespace with proto dependencies,genpb2.sh"vendorizes" dependencies only
for such.protofiles for which no PyPI packages are available, moving such
dependencies inside thecontainerdtop-level Python package namespace.services/contains the containerd service API v1.events/contains the containerd event definitions.types/contains containerd type definitions required by services and
events.protobuf/internal dependency.vendor/contains the "vendorized" dependencies.gogoproto/modules not available as a PyPI package.genpb2.shis a script to recreate or update the_pb2.pyand_pb2_grpc.pyPython modules from the containerd API.protofile definitions and
dependencies. Seegenpb2.shfor more information on its workings.Survival ReferencesgRPC Basics – Python.Protocol Buffers Python Reference: Python Generated
Code.containerd API protocol
definitions.