Merge pull request #9376 from austinvazquez/update-getting-started-for-v2
Update documentation for containerd v2.0 packages
This commit is contained in:
Phil Estes
GitHub
commit
7ea66e3af7
10
README.md
10
README.md
@ -1,10 +1,10 @@
|
||||
|
||||
|
||||
|
||||
[](https://pkg.go.dev/github.com/containerd/containerd)
|
||||
[](https://pkg.go.dev/github.com/containerd/containerd/v2)
|
||||
[](https://github.com/containerd/containerd/actions?query=workflow%3ACI)
|
||||
[](https://github.com/containerd/containerd/actions?query=workflow%3ANightly)
|
||||
[](https://goreportcard.com/report/github.com/containerd/containerd)
|
||||
[](https://goreportcard.com/report/github.com/containerd/containerd/v2)
|
||||
[](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.
|
||||
@ -107,9 +107,9 @@ containerd offers a full client package to help you integrate containerd into yo
|
||||
import (
|
||||
"context"
|
||||
|
||||
"github.com/containerd/containerd"
|
||||
"github.com/containerd/containerd/cio"
|
||||
"github.com/containerd/containerd/namespaces"
|
||||
containerd "github.com/containerd/containerd/v2/client"
|
||||
"github.com/containerd/containerd/v2/cio"
|
||||
"github.com/containerd/containerd/v2/namespaces"
|
||||
)
|
||||
|
||||
|
||||
|
||||
@ -240,7 +240,7 @@ containerd versions:
|
||||
| Runtime Shim API | Stable | 1.2 | - |
|
||||
| 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) |
|
||||
| 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 | - |
|
||||
|
||||
From the version stated in the above table, that component must adhere to the
|
||||
@ -308,7 +308,7 @@ follow that format.
|
||||
### Go client API
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
@ -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
|
||||
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
|
||||
|
||||
@ -75,11 +75,11 @@ version = 2
|
||||
|
||||
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
|
||||
[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
|
||||
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
|
||||
package main
|
||||
|
||||
@ -90,9 +90,9 @@ import (
|
||||
|
||||
"google.golang.org/grpc"
|
||||
|
||||
snapshotsapi "github.com/containerd/containerd/api/services/snapshots/v1"
|
||||
"github.com/containerd/containerd/contrib/snapshotservice"
|
||||
"github.com/containerd/containerd/snapshots/native"
|
||||
snapshotsapi "github.com/containerd/containerd/v2/api/services/snapshots/v1"
|
||||
"github.com/containerd/containerd/v2/contrib/snapshotservice"
|
||||
"github.com/containerd/containerd/v2/snapshots/native"
|
||||
)
|
||||
|
||||
func main() {
|
||||
|
||||
@ -65,7 +65,7 @@ If we want to make a `SpecOpt` to setup a container to monitor the host system w
|
||||
package monitor
|
||||
|
||||
import (
|
||||
"github.com/containerd/containerd/oci"
|
||||
"github.com/containerd/containerd/v2/oci"
|
||||
specs "github.com/opencontainers/runtime-spec/specs-go"
|
||||
)
|
||||
|
||||
|
||||
@ -422,12 +422,12 @@ in turn, depends on the next layer down, so it is protected from collection, and
|
||||
### Container
|
||||
|
||||
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.
|
||||
|
||||
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. 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. 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 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. 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/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/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/v2/client#Client.NewContainer), optionally telling it to create a snapshot with [WithNewSnapshot()](https://godoc.org/github.com/containerd/containerd/v2/client#WithNewSnapshot)
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
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
|
||||
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
|
||||
responsibility of the caller of the library. The `containerd` daemon has strict
|
||||
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
|
||||
easy `client.WithLease`, the lease manager can be used directly. This also
|
||||
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
|
||||
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`
|
||||
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
|
||||
leases. Use [`images.SynchronousDelete()`](https://godoc.org/github.com/containerd/containerd/images#SynchronousDelete)
|
||||
for [`images.Store`](https://godoc.org/github.com/containerd/containerd/images#Store)'s
|
||||
leases. Use [`images.SynchronousDelete()`](https://godoc.org/github.com/containerd/containerd/v2/images#SynchronousDelete)
|
||||
for [`images.Store`](https://godoc.org/github.com/containerd/containerd/v2/images#Store)'s
|
||||
`Delete` and
|
||||
[`leases.SynchronousDelete`](https://godoc.org/github.com/containerd/containerd/leases#SynchronousDelete)
|
||||
for [`leases.Manager`](https://godoc.org/github.com/containerd/containerd/leases#Manager)'s
|
||||
[`leases.SynchronousDelete`](https://godoc.org/github.com/containerd/containerd/v2/leases#SynchronousDelete)
|
||||
for [`leases.Manager`](https://godoc.org/github.com/containerd/containerd/v2/leases#Manager)'s
|
||||
`Delete`.
|
||||
|
||||
@ -189,7 +189,7 @@ See the header of [`go.mod`](https://github.com/containerd/containerd/blob/main/
|
||||
|
||||
### 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
|
||||
@ -198,7 +198,7 @@ package main
|
||||
import (
|
||||
"log"
|
||||
|
||||
"github.com/containerd/containerd"
|
||||
containerd "github.com/containerd/containerd/v2/client"
|
||||
)
|
||||
|
||||
func main() {
|
||||
@ -252,8 +252,8 @@ import (
|
||||
"context"
|
||||
"log"
|
||||
|
||||
"github.com/containerd/containerd"
|
||||
"github.com/containerd/containerd/namespaces"
|
||||
containerd "github.com/containerd/containerd/v2/client"
|
||||
"github.com/containerd/containerd/v2/namespaces"
|
||||
)
|
||||
|
||||
func main() {
|
||||
@ -327,9 +327,9 @@ import (
|
||||
"context"
|
||||
"log"
|
||||
|
||||
"github.com/containerd/containerd"
|
||||
"github.com/containerd/containerd/oci"
|
||||
"github.com/containerd/containerd/namespaces"
|
||||
containerd "github.com/containerd/containerd/v2/client"
|
||||
"github.com/containerd/containerd/v2/namespaces"
|
||||
"github.com/containerd/containerd/v2/oci"
|
||||
)
|
||||
|
||||
func main() {
|
||||
@ -474,10 +474,10 @@ import (
|
||||
"syscall"
|
||||
"time"
|
||||
|
||||
"github.com/containerd/containerd"
|
||||
"github.com/containerd/containerd/cio"
|
||||
"github.com/containerd/containerd/oci"
|
||||
"github.com/containerd/containerd/namespaces"
|
||||
"github.com/containerd/containerd/v2/cio"
|
||||
containerd "github.com/containerd/containerd/v2/client"
|
||||
"github.com/containerd/containerd/v2/oci"
|
||||
"github.com/containerd/containerd/v2/namespaces"
|
||||
)
|
||||
|
||||
func main() {
|
||||
@ -526,7 +526,7 @@ func redisExample() error {
|
||||
// make sure we wait before calling start
|
||||
exitStatusC, err := task.Wait(ctx)
|
||||
if err != nil {
|
||||
fmt.Println(err)
|
||||
return err
|
||||
}
|
||||
|
||||
// call start on the task to execute the redis server
|
||||
|
||||
@ -12,7 +12,7 @@ It is trivial for clients to switch namespaces.
|
||||
## Who specifies the namespace?
|
||||
|
||||
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
|
||||
// set a namespace
|
||||
|
||||
@ -19,7 +19,7 @@ USAGE:
|
||||
containerd [global options] command [command options] [arguments...]
|
||||
|
||||
VERSION:
|
||||
v1.7.0-beta.0
|
||||
v2.0.0-beta.0
|
||||
|
||||
DESCRIPTION:
|
||||
|
||||
|
||||
@ -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).
|
||||
|
||||
```go
|
||||
import (
|
||||
containerd "github.com/containerd/containerd/v2/client"
|
||||
)
|
||||
|
||||
image, err := client.Pull(ctx, ref,
|
||||
containerd.WithPullUnpack,
|
||||
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/`.
|
||||
|
||||
```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,
|
||||
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.
|
||||
The values of annotations can be dynamically added and modified in the handler wrapper.
|
||||
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
|
||||
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,
|
||||
containerd.WithPullUnpack,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user