github/containerd
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity

Merge pull request #9376 from austinvazquez/update-getting-started-for-v2

Browse Source 
Update documentation for containerd v2.0 packages
This commit is contained in:
Phil Estes 2023-11-16 23:46:46 +00:00 committed by GitHub
commit 7ea66e3af7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 52 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
README.md
View File

@ -1,10 +1,10 @@
![containerd banner light mode](https://raw.githubusercontent.com/cncf/artwork/master/projects/containerd/horizontal/color/containerd-horizontal-color.png#gh-light-mode-only) ![containerd banner light mode](https://raw.githubusercontent.com/cncf/artwork/master/projects/containerd/horizontal/color/containerd-horizontal-color.png#gh-light-mode-only)
![containerd banner dark mode](https://raw.githubusercontent.com/cncf/artwork/master/projects/containerd/horizontal/white/containerd-horizontal-white.png#gh-dark-mode-only) ![containerd banner dark mode](https://raw.githubusercontent.com/cncf/artwork/master/projects/containerd/horizontal/white/containerd-horizontal-white.png#gh-dark-mode-only)
[![PkgGoDev](https://pkg.go.dev/badge/github.com/containerd/containerd)](https://pkg.go.dev/github.com/containerd/containerd) [![PkgGoDev](https://pkg.go.dev/badge/github.com/containerd/containerd/v2)](https://pkg.go.dev/github.com/containerd/containerd/v2)
[![Build Status](https://github.com/containerd/containerd/workflows/CI/badge.svg)](https://github.com/containerd/containerd/actions?query=workflow%3ACI) [![Build Status](https://github.com/containerd/containerd/workflows/CI/badge.svg)](https://github.com/containerd/containerd/actions?query=workflow%3ACI)
[![Nightlies](https://github.com/containerd/containerd/workflows/Nightly/badge.svg)](https://github.com/containerd/containerd/actions?query=workflow%3ANightly) [![Nightlies](https://github.com/containerd/containerd/workflows/Nightly/badge.svg)](https://github.com/containerd/containerd/actions?query=workflow%3ANightly)
[![Go Report Card](https://goreportcard.com/badge/github.com/containerd/containerd)](https://goreportcard.com/report/github.com/containerd/containerd) [![Go Report Card](https://goreportcard.com/badge/github.com/containerd/containerd/v2)](https://goreportcard.com/report/github.com/containerd/containerd/v2)
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1271/badge)](https://bestpractices.coreinfrastructure.org/projects/1271) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1271/badge)](https://bestpractices.coreinfrastructure.org/projects/1271)
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 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.
@ -107,9 +107,9 @@ containerd offers a full client package to help you integrate containerd into yo
import ( import (
"context" "context"
"github.com/containerd/containerd" containerd "github.com/containerd/containerd/v2/client"
"github.com/containerd/containerd/cio" "github.com/containerd/containerd/v2/cio"
"github.com/containerd/containerd/namespaces" "github.com/containerd/containerd/v2/namespaces"
) )

4
RELEASES.md
View File

@ -240,7 +240,7 @@ containerd versions:
| Runtime Shim API | Stable | 1.2 | - | | Runtime Shim API | Stable | 1.2 | - |
| Daemon Config | Stable | 1.0 | - | | Daemon Config | Stable | 1.0 | - |
| CRI GRPC API | Stable | 1.6 (_CRI v1_) | [cri-api](https://github.com/kubernetes/cri-api/tree/master/pkg/apis/runtime/v1) | | CRI GRPC API | Stable | 1.6 (_CRI v1_) | [cri-api](https://github.com/kubernetes/cri-api/tree/master/pkg/apis/runtime/v1) |
| Go client API | Unstable | _future_ | [godoc](https://godoc.org/github.com/containerd/containerd) | | Go client API | Unstable | _future_ | [godoc](https://godoc.org/github.com/containerd/containerd/v2/client) |
| `ctr` tool | Unstable | Out of scope | - | | `ctr` tool | Unstable | Out of scope | - |
From the version stated in the above table, that component must adhere to the From the version stated in the above table, that component must adhere to the
@ -308,7 +308,7 @@ follow that format.
### Go client API ### Go client API
The Go client API, documented in The Go client API, documented in
[godoc](https://godoc.org/github.com/containerd/containerd), is currently [godoc](https://godoc.org/github.com/containerd/containerd/v2/client), is currently
considered unstable. It is recommended to vendor the necessary components to considered unstable. It is recommended to vendor the necessary components to
stabilize your project build. Note that because the Go API interfaces with the stabilize your project build. Note that because the Go API interfaces with the
GRPC API, clients written against a 1.0 Go API should remain compatible with GRPC API, clients written against a 1.0 Go API should remain compatible with

12
docs/PLUGINS.md
View File

@ -13,7 +13,7 @@ with an image registry, or loading an image from tar. containerd's Go client
gives a user access to many points of extensions from creating their own gives a user access to many points of extensions from creating their own
options on container creation to resolving image registry names. options on container creation to resolving image registry names.
See [containerd's Go documentation](https://godoc.org/github.com/containerd/containerd) See [containerd's Go documentation](https://godoc.org/github.com/containerd/containerd/v2/client)
## External Plugins ## External Plugins
@ -75,11 +75,11 @@ version = 2
Implementing a proxy plugin is as easy as implementing the gRPC API for a Implementing a proxy plugin is as easy as implementing the gRPC API for a
service. For implementing a proxy plugin in Go, look at the go doc for service. For implementing a proxy plugin in Go, look at the go doc for
[content store service](https://godoc.org/github.com/containerd/containerd/api/services/content/v1#ContentServer), [snapshotter service](https://godoc.org/github.com/containerd/containerd/api/services/snapshots/v1#SnapshotsServer), and [diff service](https://pkg.go.dev/github.com/containerd/containerd/api/services/diff/v1#DiffServer). [content store service](https://godoc.org/github.com/containerd/containerd/v2/api/services/content/v1#ContentServer), [snapshotter service](https://godoc.org/github.com/containerd/containerd/v2/api/services/snapshots/v1#SnapshotsServer), and [diff service](https://pkg.go.dev/github.com/containerd/containerd/v2/api/services/diff/v1#DiffServer).
The following example creates a snapshot plugin binary which can be used The following example creates a snapshot plugin binary which can be used
with any implementation of with any implementation of
[containerd's Snapshotter interface](https://godoc.org/github.com/containerd/containerd/snapshots#Snapshotter) [containerd's Snapshotter interface](https://godoc.org/github.com/containerd/containerd/v2/snapshots#Snapshotter)
```go ```go
package main package main
@ -90,9 +90,9 @@ import (
"google.golang.org/grpc" "google.golang.org/grpc"
snapshotsapi "github.com/containerd/containerd/api/services/snapshots/v1" snapshotsapi "github.com/containerd/containerd/v2/api/services/snapshots/v1"
"github.com/containerd/containerd/contrib/snapshotservice" "github.com/containerd/containerd/v2/contrib/snapshotservice"
"github.com/containerd/containerd/snapshots/native" "github.com/containerd/containerd/v2/snapshots/native"
) )
func main() { func main() {

2
docs/client-opts.md
View File

@ -65,7 +65,7 @@ If we want to make a `SpecOpt` to setup a container to monitor the host system w
package monitor package monitor
import ( import (
"github.com/containerd/containerd/oci" "github.com/containerd/containerd/v2/oci"
specs "github.com/opencontainers/runtime-spec/specs-go" specs "github.com/opencontainers/runtime-spec/specs-go"
) )

10
docs/content-flow.md
View File

@ -422,12 +422,12 @@ in turn, depends on the next layer down, so it is protected from collection, and
### Container ### Container
With the above in place, we know how to create an active snapshot that is useful for the container. We simply With the above in place, we know how to create an active snapshot that is useful for the container. We simply
need to [Prepare()](https://godoc.org/github.com/containerd/containerd/snapshots#Snapshotter) the active snapshot, need to [Prepare()](https://godoc.org/github.com/containerd/containerd/v2/snapshots#Snapshotter) the active snapshot,
passing it an ID and the parent, in this case the top layer of committed snapshots. passing it an ID and the parent, in this case the top layer of committed snapshots.
Thus, the steps are: Thus, the steps are:
1. Get the content into the content store, either via [Pull()](https://godoc.org/github.com/containerd/containerd#Client.Pull), or via loading it in the [content.Store API](https://godoc.org/github.com/containerd/containerd/content#Store) 1. Get the content into the content store, either via [Pull()](https://godoc.org/github.com/containerd/containerd/v2/client#Client.Pull), or via loading it in the [content.Store API](https://godoc.org/github.com/containerd/containerd/v2/content#Store)
1. Unpack the image to create committed snapshots for each layer, using [image.Unpack()](https://godoc.org/github.com/containerd/containerd#Image). Alternatively, if you use [Pull()](https://godoc.org/github.com/containerd/containerd#Client.Pull), you can pass it an option to unpack when pulling, using [WithPullUnpack()](https://godoc.org/github.com/containerd/containerd#WithPullUnpack) 1. Unpack the image to create committed snapshots for each layer, using [image.Unpack()](https://godoc.org/github.com/containerd/containerd/v2/client#Image). Alternatively, if you use [Pull()](https://godoc.org/github.com/containerd/containerd/v2/client#Client.Pull), you can pass it an option to unpack when pulling, using [WithPullUnpack()](https://godoc.org/github.com/containerd/containerd/v2/client#WithPullUnpack)
1. Create an active snapshot using [Prepare()](https://godoc.org/github.com/containerd/containerd/snapshots#Snapshotter). You can skip this step if you plan on creating a container, as you can pass it as an option to the next step. 1. Create an active snapshot using [Prepare()](https://godoc.org/github.com/containerd/containerd/v2/snapshots#Snapshotter). You can skip this step if you plan on creating a container, as you can pass it as an option to the next step.
1. Create a container using [NewContainer()](https://godoc.org/github.com/containerd/containerd#Client.NewContainer), optionally telling it to create a snapshot with [WithNewSnapshot()](https://godoc.org/github.com/containerd/containerd#WithNewSnapshot) 1. Create a container using [NewContainer()](https://godoc.org/github.com/containerd/containerd/v2/client#Client.NewContainer), optionally telling it to create a snapshot with [WithNewSnapshot()](https://godoc.org/github.com/containerd/containerd/v2/client#WithNewSnapshot)

12
docs/garbage-collection.md
View File

@ -4,7 +4,7 @@
longer being used. The client is responsible for ensuring that all resources longer being used. The client is responsible for ensuring that all resources
which are created are either used or held by a lease at all times, else they which are created are either used or held by a lease at all times, else they
will be considered eligible for removal. The Go client library will be considered eligible for removal. The Go client library
(`github.com/containerd/containerd`) has built-in behavior to ensure resources (`github.com/containerd/containerd/v2/client`) has built-in behavior to ensure resources
are properly tracked and leased. However, the lifecycles of leases are the are properly tracked and leased. However, the lifecycles of leases are the
responsibility of the caller of the library. The `containerd` daemon has strict responsibility of the caller of the library. The `containerd` daemon has strict
resource management and will garbage collect any unused resource. resource management and will garbage collect any unused resource.
@ -43,7 +43,7 @@ _But, of course, more complicated use cases are supported..._
If the program or lease are intended to be longer lived, instead of the very If the program or lease are intended to be longer lived, instead of the very
easy `client.WithLease`, the lease manager can be used directly. This also easy `client.WithLease`, the lease manager can be used directly. This also
allows for setting custom labels on the lease or manipulating its resources. allows for setting custom labels on the lease or manipulating its resources.
Use `client.LeasesService()` to get a [lease Manager](https://godoc.org/github.com/containerd/containerd/leases#Manager) Use `client.LeasesService()` to get a [lease Manager](https://godoc.org/github.com/containerd/containerd/v2/leases#Manager)
which can be used to create, list, and delete leases as well as manage the which can be used to create, list, and delete leases as well as manage the
referenced resources for that lease. referenced resources for that lease.
@ -157,9 +157,9 @@ may also request a garbage collection during resource removal. In this case,
the garbage collection will be scheduled immediately (or after `schedule_delay` the garbage collection will be scheduled immediately (or after `schedule_delay`
when configured to non-zero). The service will not return until the garbage when configured to non-zero). The service will not return until the garbage
collection has completed. This is currently supported on removal of images and collection has completed. This is currently supported on removal of images and
leases. Use [`images.SynchronousDelete()`](https://godoc.org/github.com/containerd/containerd/images#SynchronousDelete) leases. Use [`images.SynchronousDelete()`](https://godoc.org/github.com/containerd/containerd/v2/images#SynchronousDelete)
for [`images.Store`](https://godoc.org/github.com/containerd/containerd/images#Store)'s for [`images.Store`](https://godoc.org/github.com/containerd/containerd/v2/images#Store)'s
`Delete` and `Delete` and
[`leases.SynchronousDelete`](https://godoc.org/github.com/containerd/containerd/leases#SynchronousDelete) [`leases.SynchronousDelete`](https://godoc.org/github.com/containerd/containerd/v2/leases#SynchronousDelete)
for [`leases.Manager`](https://godoc.org/github.com/containerd/containerd/leases#Manager)'s for [`leases.Manager`](https://godoc.org/github.com/containerd/containerd/v2/leases#Manager)'s
`Delete`. `Delete`.

24
docs/getting-started.md
View File

@ -189,7 +189,7 @@ See the header of [`go.mod`](https://github.com/containerd/containerd/blob/main/
### Connecting to containerd ### Connecting to containerd
We will start a new `main.go` file and import the containerd root package that contains the client. We will start a new `main.go` file and import the containerd client package.
```go ```go
@ -198,7 +198,7 @@ package main
import ( import (
"log" "log"
"github.com/containerd/containerd" containerd "github.com/containerd/containerd/v2/client"
) )
func main() { func main() {
@ -252,8 +252,8 @@ import (
"context" "context"
"log" "log"
"github.com/containerd/containerd" containerd "github.com/containerd/containerd/v2/client"
"github.com/containerd/containerd/namespaces" "github.com/containerd/containerd/v2/namespaces"
) )
func main() { func main() {
@ -327,9 +327,9 @@ import (
"context" "context"
"log" "log"
"github.com/containerd/containerd" containerd "github.com/containerd/containerd/v2/client"
"github.com/containerd/containerd/oci" "github.com/containerd/containerd/v2/namespaces"
"github.com/containerd/containerd/namespaces" "github.com/containerd/containerd/v2/oci"
) )
func main() { func main() {
@ -474,10 +474,10 @@ import (
"syscall" "syscall"
"time" "time"
"github.com/containerd/containerd" "github.com/containerd/containerd/v2/cio"
"github.com/containerd/containerd/cio" containerd "github.com/containerd/containerd/v2/client"
"github.com/containerd/containerd/oci" "github.com/containerd/containerd/v2/oci"
"github.com/containerd/containerd/namespaces" "github.com/containerd/containerd/v2/namespaces"
) )
func main() { func main() {
@ -526,7 +526,7 @@ func redisExample() error {
// make sure we wait before calling start // make sure we wait before calling start
exitStatusC, err := task.Wait(ctx) exitStatusC, err := task.Wait(ctx)
if err != nil { if err != nil {
fmt.Println(err) return err
} }
// call start on the task to execute the redis server // call start on the task to execute the redis server

2
docs/namespaces.md
View File

@ -12,7 +12,7 @@ It is trivial for clients to switch namespaces.
## Who specifies the namespace? ## Who specifies the namespace?
The client specifies the namespace via the `context`. The client specifies the namespace via the `context`.
There is a `github.com/containerd/containerd/namespaces` package that allows a user to get and set the namespace on a context. There is a `github.com/containerd/containerd/v2/namespaces` package that allows a user to get and set the namespace on a context.
```go ```go
// set a namespace // set a namespace

2
docs/ops.md
View File

@ -19,7 +19,7 @@ USAGE:
containerd [global options] command [command options] [arguments...] containerd [global options] command [command options] [arguments...]
VERSION: VERSION:
v1.7.0-beta.0 v2.0.0-beta.0
DESCRIPTION: DESCRIPTION:

16
docs/remote-snapshotter.md
View File

@ -15,6 +15,10 @@ The containerd client's `Pull` API with unpacking-mode allows the underlying sna
Remote snapshotter needs to be plugged into containerd in [the same ways as normal snapshotters](/docs/PLUGINS.md). Remote snapshotter needs to be plugged into containerd in [the same ways as normal snapshotters](/docs/PLUGINS.md).
```go ```go
import (
containerd "github.com/containerd/containerd/v2/client"
)
image, err := client.Pull(ctx, ref, image, err := client.Pull(ctx, ref,
containerd.WithPullUnpack, containerd.WithPullUnpack,
containerd.WithPullSnapshotter("my-remote-snapshotter"), containerd.WithPullSnapshotter("my-remote-snapshotter"),
@ -39,7 +43,10 @@ This is useful if the values of these labels are determined statically regardles
These user-defined labels must be prefixed by `containerd.io/snapshot/`. These user-defined labels must be prefixed by `containerd.io/snapshot/`.
```go ```go
import "github.com/containerd/containerd/snapshots" import (
containerd "github.com/containerd/containerd/v2/client"
"github.com/containerd/containerd/v2/snapshots"
)
image, err := client.Pull(ctx, ref, image, err := client.Pull(ctx, ref,
containerd.WithPullUnpack, containerd.WithPullUnpack,
@ -61,10 +68,13 @@ Every time the containerd client queries remote snapshot, it passes `Annotations
These annotations are passed to the snapshotter as user-defined labels. These annotations are passed to the snapshotter as user-defined labels.
The values of annotations can be dynamically added and modified in the handler wrapper. The values of annotations can be dynamically added and modified in the handler wrapper.
Note that annotations must be prefixed by `containerd.io/snapshot/`. Note that annotations must be prefixed by `containerd.io/snapshot/`.
`github.com/containerd/containerd/pkg/snapshotters` is a handler implementation used by the CRI package, nerdctl and moby. `github.com/containerd/containerd/v2/pkg/snapshotters` is a handler implementation used by the CRI package, nerdctl and moby.
```go ```go
import "github.com/containerd/containerd/pkg/snapshotters" import (
containerd "github.com/containerd/containerd/v2/client"
"github.com/containerd/containerd/v2/pkg/snapshotters"
)
if _, err := client.Pull(ctx, ref, if _, err := client.Pull(ctx, ref,
containerd.WithPullUnpack, containerd.WithPullUnpack,