Skip to content

Commit db97449

Browse files
author
Maksym Pavlenko
authored
Merge pull request containerd#10730 from mxpv/features
Move features section to a separate file
2 parents 3df2cc1 + 146a977 commit db97449

File tree

2 files changed

+165
-158
lines changed

2 files changed

+165
-158
lines changed

‎README.md‎

Lines changed: 2 additions & 158 deletions
Original file line numberDiff line numberDiff line change
@@ -89,164 +89,8 @@ For configuring registries, see [registry host configuration documentation](docs
8989

9090
## Features
9191

92-
### Client
93-
94-
containerd offers a full client package to help you integrate containerd into your platform.
95-
96-
```go
97-
98-
import (
99-
"context"
100-
101-
containerd "github.com/containerd/containerd/v2/client"
102-
"github.com/containerd/containerd/v2/pkg/cio"
103-
"github.com/containerd/containerd/v2/pkg/namespaces"
104-
)
105-
106-
107-
func main() {
108-
client, err := containerd.New("/run/containerd/containerd.sock")
109-
defer client.Close()
110-
}
111-
112-
```
113-
114-
### Namespaces
115-
116-
Namespaces allow multiple consumers to use the same containerd without conflicting with each other. It has the benefit of sharing content while maintaining separation with containers and images.
117-
118-
To set a namespace for requests to the API:
119-
120-
```go
121-
context = context.Background()
122-
// create a context for docker
123-
docker = namespaces.WithNamespace(context, "docker")
124-
125-
containerd, err := client.NewContainer(docker, "id")
126-
```
127-
128-
To set a default namespace on the client:
129-
130-
```go
131-
client, err := containerd.New(address, containerd.WithDefaultNamespace("docker"))
132-
```
133-
134-
### Distribution
135-
136-
```go
137-
// pull an image
138-
image, err := client.Pull(context, "docker.io/library/redis:latest")
139-
140-
// push an image
141-
err := client.Push(context, "docker.io/library/redis:latest", image.Target())
142-
```
143-
144-
### Containers
145-
146-
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.
147-
148-
```go
149-
redis, err := client.NewContainer(context, "redis-master")
150-
defer redis.Delete(context)
151-
```
152-
153-
### OCI Runtime Specification
154-
155-
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.
156-
157-
You can specify options when creating a container about how to modify the specification.
158-
159-
```go
160-
redis, err := client.NewContainer(context, "redis-master", containerd.WithNewSpec(oci.WithImageConfig(image)))
161-
```
162-
163-
### Root Filesystems
164-
165-
containerd allows you to use overlay or snapshot filesystems with your containers. It comes with built-in support for overlayfs and btrfs.
166-
167-
```go
168-
// pull an image and unpack it into the configured snapshotter
169-
image, err := client.Pull(context, "docker.io/library/redis:latest", containerd.WithPullUnpack)
170-
171-
// allocate a new RW root filesystem for a container based on the image
172-
redis, err := client.NewContainer(context, "redis-master",
173-
containerd.WithNewSnapshot("redis-rootfs", image),
174-
containerd.WithNewSpec(oci.WithImageConfig(image)),
175-
)
176-
177-
// use a readonly filesystem with multiple containers
178-
for i := 0; i < 10; i++ {
179-
id := fmt.Sprintf("id-%s", i)
180-
container, err := client.NewContainer(ctx, id,
181-
containerd.WithNewSnapshotView(id, image),
182-
containerd.WithNewSpec(oci.WithImageConfig(image)),
183-
)
184-
}
185-
```
186-
187-
### Tasks
188-
189-
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.
190-
191-
```go
192-
// create a new task
193-
task, err := redis.NewTask(context, cio.NewCreator(cio.WithStdio))
194-
defer task.Delete(context)
195-
196-
// the task is now running and has a pid that can be used to setup networking
197-
// or other runtime settings outside of containerd
198-
pid := task.Pid()
199-
200-
// start the redis-server process inside the container
201-
err := task.Start(context)
202-
203-
// wait for the task to exit and get the exit status
204-
status, err := task.Wait(context)
205-
```
206-
207-
### Checkpoint and Restore
208-
209-
If you have [criu](https://criu.org/Main_Page) installed on your machine you can checkpoint and restore containers and their tasks. This allows you to clone and/or live migrate containers to other machines.
210-
211-
```go
212-
// checkpoint the task then push it to a registry
213-
checkpoint, err := task.Checkpoint(context)
214-
215-
err := client.Push(context, "myregistry/checkpoints/redis:master", checkpoint)
216-
217-
// on a new machine pull the checkpoint and restore the redis container
218-
checkpoint, err := client.Pull(context, "myregistry/checkpoints/redis:master")
219-
220-
redis, err = client.NewContainer(context, "redis-master", containerd.WithNewSnapshot("redis-rootfs", checkpoint))
221-
defer container.Delete(context)
222-
223-
task, err = redis.NewTask(context, cio.NewCreator(cio.WithStdio), containerd.WithTaskCheckpoint(checkpoint))
224-
defer task.Delete(context)
225-
226-
err := task.Start(context)
227-
```
228-
229-
### Snapshot Plugins
230-
231-
In addition to the built-in Snapshot plugins in containerd, additional external
232-
plugins can be configured using GRPC. An external plugin is made available using
233-
the configured name and appears as a plugin alongside the built-in ones.
234-
235-
To add an external snapshot plugin, add the plugin to containerd's config file
236-
(by default at `/etc/containerd/config.toml`). The string following
237-
`proxy_plugin.` will be used as the name of the snapshotter and the address
238-
should refer to a socket with a GRPC listener serving containerd's Snapshot
239-
GRPC API. Remember to restart containerd for any configuration changes to take
240-
effect.
241-
242-
```
243-
[proxy_plugins]
244-
[proxy_plugins.customsnapshot]
245-
type = "snapshot"
246-
address = "/var/run/mysnapshotter.sock"
247-
```
248-
249-
See [PLUGINS.md](/docs/PLUGINS.md) for how to create plugins
92+
For a detailed overview of containerd's core concepts and the features it supports,
93+
please refer to the [FEATURES.MD](./docs/features.md) document.
25094

25195
### Releases and API Stability
25296

‎docs/features.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
2+
# Features
3+
4+
The sections below cover core features of `containerd`.
5+
6+
## Client
7+
8+
containerd offers a full client package to help you integrate containerd into your platform.
9+
10+
```go
11+
12+
import (
13+
"context"
14+
15+
containerd "github.com/containerd/containerd/v2/client"
16+
"github.com/containerd/containerd/v2/pkg/cio"
17+
"github.com/containerd/containerd/v2/pkg/namespaces"
18+
)
19+
20+
21+
func main() {
22+
client, err := containerd.New("/run/containerd/containerd.sock")
23+
defer client.Close()
24+
}
25+
26+
```
27+
28+
## Namespaces
29+
30+
Namespaces allow multiple consumers to use the same containerd without conflicting with each other. It has the benefit of sharing content while maintaining separation with containers and images.
31+
32+
To set a namespace for requests to the API:
33+
34+
```go
35+
context = context.Background()
36+
// create a context for docker
37+
docker = namespaces.WithNamespace(context, "docker")
38+
39+
containerd, err := client.NewContainer(docker, "id")
40+
```
41+
42+
To set a default namespace on the client:
43+
44+
```go
45+
client, err := containerd.New(address, containerd.WithDefaultNamespace("docker"))
46+
```
47+
48+
## Distribution
49+
50+
```go
51+
// pull an image
52+
image, err := client.Pull(context, "docker.io/library/redis:latest")
53+
54+
// push an image
55+
err := client.Push(context, "docker.io/library/redis:latest", image.Target())
56+
```
57+
58+
## Containers
59+
60+
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.
61+
62+
```go
63+
redis, err := client.NewContainer(context, "redis-master")
64+
defer redis.Delete(context)
65+
```
66+
67+
## OCI Runtime Specification
68+
69+
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.
70+
71+
You can specify options when creating a container about how to modify the specification.
72+
73+
```go
74+
redis, err := client.NewContainer(context, "redis-master", containerd.WithNewSpec(oci.WithImageConfig(image)))
75+
```
76+
77+
## Root Filesystems
78+
79+
containerd allows you to use overlay or snapshot filesystems with your containers. It comes with built-in support for overlayfs and btrfs.
80+
81+
```go
82+
// pull an image and unpack it into the configured snapshotter
83+
image, err := client.Pull(context, "docker.io/library/redis:latest", containerd.WithPullUnpack)
84+
85+
// allocate a new RW root filesystem for a container based on the image
86+
redis, err := client.NewContainer(context, "redis-master",
87+
containerd.WithNewSnapshot("redis-rootfs", image),
88+
containerd.WithNewSpec(oci.WithImageConfig(image)),
89+
)
90+
91+
// use a readonly filesystem with multiple containers
92+
for i := 0; i < 10; i++ {
93+
id := fmt.Sprintf("id-%s", i)
94+
container, err := client.NewContainer(ctx, id,
95+
containerd.WithNewSnapshotView(id, image),
96+
containerd.WithNewSpec(oci.WithImageConfig(image)),
97+
)
98+
}
99+
```
100+
101+
## Tasks
102+
103+
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.
104+
105+
```go
106+
// create a new task
107+
task, err := redis.NewTask(context, cio.NewCreator(cio.WithStdio))
108+
defer task.Delete(context)
109+
110+
// the task is now running and has a pid that can be used to setup networking
111+
// or other runtime settings outside of containerd
112+
pid := task.Pid()
113+
114+
// start the redis-server process inside the container
115+
err := task.Start(context)
116+
117+
// wait for the task to exit and get the exit status
118+
status, err := task.Wait(context)
119+
```
120+
121+
## Checkpoint and Restore
122+
123+
If you have [criu](https://criu.org/Main_Page) installed on your machine you can checkpoint and restore containers and their tasks. This allows you to clone and/or live migrate containers to other machines.
124+
125+
```go
126+
// checkpoint the task then push it to a registry
127+
checkpoint, err := task.Checkpoint(context)
128+
129+
err := client.Push(context, "myregistry/checkpoints/redis:master", checkpoint)
130+
131+
// on a new machine pull the checkpoint and restore the redis container
132+
checkpoint, err := client.Pull(context, "myregistry/checkpoints/redis:master")
133+
134+
redis, err = client.NewContainer(context, "redis-master", containerd.WithNewSnapshot("redis-rootfs", checkpoint))
135+
defer container.Delete(context)
136+
137+
task, err = redis.NewTask(context, cio.NewCreator(cio.WithStdio), containerd.WithTaskCheckpoint(checkpoint))
138+
defer task.Delete(context)
139+
140+
err := task.Start(context)
141+
```
142+
143+
## Snapshot Plugins
144+
145+
In addition to the built-in Snapshot plugins in containerd, additional external
146+
plugins can be configured using GRPC. An external plugin is made available using
147+
the configured name and appears as a plugin alongside the built-in ones.
148+
149+
To add an external snapshot plugin, add the plugin to containerd's config file
150+
(by default at `/etc/containerd/config.toml`). The string following
151+
`proxy_plugin.` will be used as the name of the snapshotter and the address
152+
should refer to a socket with a GRPC listener serving containerd's Snapshot
153+
GRPC API. Remember to restart containerd for any configuration changes to take
154+
effect.
155+
156+
```
157+
[proxy_plugins]
158+
[proxy_plugins.customsnapshot]
159+
type = "snapshot"
160+
address = "/var/run/mysnapshotter.sock"
161+
```
162+
163+
See [PLUGINS.md](PLUGINS.md) for how to create plugins

0 commit comments

Comments
 (0)