diff --git a/README.md b/README.md index 7641626f4be2..47c239ad165b 100644 --- a/README.md +++ b/README.md @@ -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 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) [![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) 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" ) diff --git a/RELEASES.md b/RELEASES.md index 7887e0c69646..32c52e936dc5 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -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 diff --git a/docs/PLUGINS.md b/docs/PLUGINS.md index 9c088294d760..6022658213df 100644 --- a/docs/PLUGINS.md +++ b/docs/PLUGINS.md @@ -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() { diff --git a/docs/client-opts.md b/docs/client-opts.md index fe770b7db97f..2aeace8d9865 100644 --- a/docs/client-opts.md +++ b/docs/client-opts.md @@ -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" ) diff --git a/docs/content-flow.md b/docs/content-flow.md index 00b17f3779f9..e29fc8f90c9f 100644 --- a/docs/content-flow.md +++ b/docs/content-flow.md @@ -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) diff --git a/docs/garbage-collection.md b/docs/garbage-collection.md index 809d67b96102..bfcc6d111410 100644 --- a/docs/garbage-collection.md +++ b/docs/garbage-collection.md @@ -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`. diff --git a/docs/getting-started.md b/docs/getting-started.md index a8cc49ada917..ed5b4d137eef 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -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 diff --git a/docs/namespaces.md b/docs/namespaces.md index 95f2a97cf3c6..69374346fc4f 100644 --- a/docs/namespaces.md +++ b/docs/namespaces.md @@ -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 diff --git a/docs/ops.md b/docs/ops.md index a7faf0759db3..da71308332fb 100644 --- a/docs/ops.md +++ b/docs/ops.md @@ -19,7 +19,7 @@ USAGE: containerd [global options] command [command options] [arguments...] VERSION: - v1.7.0-beta.0 + v2.0.0-beta.0 DESCRIPTION: diff --git a/docs/remote-snapshotter.md b/docs/remote-snapshotter.md index e924fbd7547e..3394f07b378b 100644 --- a/docs/remote-snapshotter.md +++ b/docs/remote-snapshotter.md @@ -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,