Skip to content

Commit e7b6fea

Browse files
crosbymichaelcrosbymichael
authored
Merge pull request containerd#3022 from mxpv/devmapper
Integrate device mapper snapshotter
2 parents 3a80a80 + 87289a0 commit e7b6fea

File tree

16 files changed

+2927
-0
lines changed

16 files changed

+2927
-0
lines changed

‎BUILDING.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,7 @@ make generate
104104
> * `no_btrfs`: A build tag disables building the btrfs snapshot driver.
105105
> * `no_cri`: A build tag disables building Kubernetes [CRI](http://blog.kubernetes.io/2016/12/container-runtime-interface-cri-in-kubernetes.html) support into containerd.
106106
> See [here](https://github.com/containerd/cri-containerd#build-tags) for build tags of CRI plugin.
107+
> * `no_devmapper`: A build tag disables building the device mapper snapshot driver.
107108
>
108109
> For example, adding `BUILDTAGS=no_btrfs` to your environment before calling the **binaries**
109110
> Makefile target will disable the btrfs driver within the containerd Go build.

‎cmd/containerd/builtins_devmapper_linux.go‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// +build !no_devmapper
2+
3+
/*
4+
Copyright The containerd Authors.
5+
6+
Licensed under the Apache License, Version 2.0 (the "License");
7+
you may not use this file except in compliance with the License.
8+
You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing, software
13+
distributed under the License is distributed on an "AS IS" BASIS,
14+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
See the License for the specific language governing permissions and
16+
limitations under the License.
17+
*/
18+
19+
package main
20+
21+
import _ "github.com/containerd/containerd/snapshots/devmapper"

‎snapshots/devmapper/README.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
## Devmapper snapshotter
2+
3+
Devmapper is a `containerd` snapshotter plugin that stores snapshots in ext4-formatted filesystem images
4+
in a devicemapper thin pool.
5+
6+
## Setup
7+
8+
To make it work you need to prepare `thin-pool` in advance and update containerd's configuration file.
9+
This file is typically located at `/etc/containerd/config.toml`.
10+
11+
Here's minimal sample entry that can be made in the configuration file:
12+
13+
```
14+
[plugins]
15+
...
16+
[plugins.devmapper]
17+
pool_name = "containerd-pool"
18+
base_image_size = "128MB"
19+
...
20+
```
21+
22+
The following configuration flags are supported:
23+
* `root_path` - a directory where the metadata will be available (if empty
24+
default location for `containerd` plugins will be used)
25+
* `pool_name` - a name to use for the devicemapper thin pool. Pool name
26+
should be the same as in `/dev/mapper/` directory
27+
* `base_image_size` - defines how much space to allocate when creating the base device
28+
29+
Pool name and base image size are required snapshotter parameters.
30+
31+
## Run
32+
Give it a try with the following commands:
33+
34+
```bash
35+
ctr images pull --snapshotter devmapper docker.io/library/hello-world:latest
36+
ctr run --snapshotter devmapper docker.io/library/hello-world:latest test
37+
```
38+
39+
## Requirements
40+
41+
The devicemapper snapshotter requires `dmsetup` (>= 1.02.110) command line tool to be installed and
42+
available on your computer. On Ubuntu, it can be installed with `apt-get install dmsetup` command.

‎snapshots/devmapper/config.go‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
// +build linux
2+
3+
/*
4+
Copyright The containerd Authors.
5+
6+
Licensed under the Apache License, Version 2.0 (the "License");
7+
you may not use this file except in compliance with the License.
8+
You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing, software
13+
distributed under the License is distributed on an "AS IS" BASIS,
14+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
See the License for the specific language governing permissions and
16+
limitations under the License.
17+
*/
18+
19+
package devmapper
20+
21+
import (
22+
"fmt"
23+
"os"
24+
25+
"github.com/BurntSushi/toml"
26+
"github.com/docker/go-units"
27+
"github.com/hashicorp/go-multierror"
28+
"github.com/pkg/errors"
29+
)
30+
31+
// Config represents device mapper configuration loaded from file.
32+
// Size units can be specified in human-readable string format (like "32KIB", "32GB", "32Tb")
33+
type Config struct {
34+
// Device snapshotter root directory for metadata
35+
RootPath string `toml:"root_path"`
36+
37+
// Name for 'thin-pool' device to be used by snapshotter (without /dev/mapper/ prefix)
38+
PoolName string `toml:"pool_name"`
39+
40+
// Defines how much space to allocate when creating base image for container
41+
BaseImageSize string `toml:"base_image_size"`
42+
BaseImageSizeBytes uint64 `toml:"-"`
43+
}
44+
45+
// LoadConfig reads devmapper configuration file from disk in TOML format
46+
func LoadConfig(path string) (*Config, error) {
47+
if _, err := os.Stat(path); err != nil {
48+
if os.IsNotExist(err) {
49+
return nil, os.ErrNotExist
50+
}
51+
52+
return nil, err
53+
}
54+
55+
config := Config{}
56+
if _, err := toml.DecodeFile(path, &config); err != nil {
57+
return nil, errors.Wrapf(err, "failed to unmarshal data at '%s'", path)
58+
}
59+
60+
if err := config.parse(); err != nil {
61+
return nil, err
62+
}
63+
64+
if err := config.Validate(); err != nil {
65+
return nil, err
66+
}
67+
68+
return &config, nil
69+
}
70+
71+
func (c *Config) parse() error {
72+
baseImageSize, err := units.RAMInBytes(c.BaseImageSize)
73+
if err != nil {
74+
return errors.Wrapf(err, "failed to parse base image size: '%s'", c.BaseImageSize)
75+
}
76+
77+
c.BaseImageSizeBytes = uint64(baseImageSize)
78+
return nil
79+
}
80+
81+
// Validate makes sure configuration fields are valid
82+
func (c *Config) Validate() error {
83+
var result *multierror.Error
84+
85+
if c.PoolName == "" {
86+
result = multierror.Append(result, fmt.Errorf("pool_name is required"))
87+
}
88+
89+
if c.RootPath == "" {
90+
result = multierror.Append(result, fmt.Errorf("root_path is required"))
91+
}
92+
93+
if c.BaseImageSize == "" {
94+
result = multierror.Append(result, fmt.Errorf("base_image_size is required"))
95+
}
96+
97+
return result.ErrorOrNil()
98+
}

‎snapshots/devmapper/config_test.go‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
// +build linux
2+
3+
/*
4+
Copyright The containerd Authors.
5+
6+
Licensed under the Apache License, Version 2.0 (the "License");
7+
you may not use this file except in compliance with the License.
8+
You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing, software
13+
distributed under the License is distributed on an "AS IS" BASIS,
14+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
See the License for the specific language governing permissions and
16+
limitations under the License.
17+
*/
18+
19+
package devmapper
20+
21+
import (
22+
"io/ioutil"
23+
"os"
24+
"testing"
25+
26+
"github.com/BurntSushi/toml"
27+
"github.com/hashicorp/go-multierror"
28+
"gotest.tools/assert"
29+
is "gotest.tools/assert/cmp"
30+
)
31+
32+
func TestLoadConfig(t *testing.T) {
33+
expected := Config{
34+
RootPath: "/tmp",
35+
PoolName: "test",
36+
BaseImageSize: "128Mb",
37+
}
38+
39+
file, err := ioutil.TempFile("", "devmapper-config-")
40+
assert.NilError(t, err)
41+
42+
encoder := toml.NewEncoder(file)
43+
err = encoder.Encode(&expected)
44+
assert.NilError(t, err)
45+
46+
defer func() {
47+
err := file.Close()
48+
assert.NilError(t, err)
49+
50+
err = os.Remove(file.Name())
51+
assert.NilError(t, err)
52+
}()
53+
54+
loaded, err := LoadConfig(file.Name())
55+
assert.NilError(t, err)
56+
57+
assert.Equal(t, loaded.RootPath, expected.RootPath)
58+
assert.Equal(t, loaded.PoolName, expected.PoolName)
59+
assert.Equal(t, loaded.BaseImageSize, expected.BaseImageSize)
60+
61+
assert.Assert(t, loaded.BaseImageSizeBytes == 128*1024*1024)
62+
}
63+
64+
func TestLoadConfigInvalidPath(t *testing.T) {
65+
_, err := LoadConfig("")
66+
assert.Equal(t, os.ErrNotExist, err)
67+
68+
_, err = LoadConfig("/dev/null")
69+
assert.Assert(t, err != nil)
70+
}
71+
72+
func TestParseInvalidData(t *testing.T) {
73+
config := Config{
74+
BaseImageSize: "y",
75+
}
76+
77+
err := config.parse()
78+
assert.Error(t, err, "failed to parse base image size: 'y': invalid size: 'y'")
79+
}
80+
81+
func TestFieldValidation(t *testing.T) {
82+
config := &Config{}
83+
err := config.Validate()
84+
assert.Assert(t, err != nil)
85+
86+
multErr := (err).(*multierror.Error)
87+
assert.Assert(t, is.Len(multErr.Errors, 3))
88+
89+
assert.Assert(t, multErr.Errors[0] != nil, "pool_name is empty")
90+
assert.Assert(t, multErr.Errors[1] != nil, "root_path is empty")
91+
assert.Assert(t, multErr.Errors[2] != nil, "base_image_size is empty")
92+
}
93+
94+
func TestExistingPoolFieldValidation(t *testing.T) {
95+
config := &Config{
96+
PoolName: "test",
97+
RootPath: "test",
98+
BaseImageSize: "10mb",
99+
}
100+
101+
err := config.Validate()
102+
assert.NilError(t, err)
103+
}

‎snapshots/devmapper/device_info.go‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
// +build linux
2+
3+
/*
4+
Copyright The containerd Authors.
5+
6+
Licensed under the Apache License, Version 2.0 (the "License");
7+
you may not use this file except in compliance with the License.
8+
You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing, software
13+
distributed under the License is distributed on an "AS IS" BASIS,
14+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
See the License for the specific language governing permissions and
16+
limitations under the License.
17+
*/
18+
19+
package devmapper
20+
21+
import (
22+
"fmt"
23+
)
24+
25+
const (
26+
maxDeviceID = 0xffffff // Device IDs are 24-bit numbers
27+
)
28+
29+
// DeviceState represents current devmapper device state reflected in meta store
30+
type DeviceState int
31+
32+
const (
33+
// Unknown means that device just allocated and no operations were performed
34+
Unknown DeviceState = iota
35+
// Creating means that device is going to be created
36+
Creating
37+
// Created means that devices successfully created
38+
Created
39+
// Activating means that device is going to be activated
40+
Activating
41+
// Activated means that device successfully activated
42+
Activated
43+
// Suspending means that device is going to be suspended
44+
Suspending
45+
// Suspended means that device successfully suspended
46+
Suspended
47+
// Resuming means that device is going to be resumed from suspended state
48+
Resuming
49+
// Resumed means that device successfully resumed
50+
Resumed
51+
// Deactivating means that device is going to be deactivated
52+
Deactivating
53+
// Deactivated means that device successfully deactivated
54+
Deactivated
55+
// Removing means that device is going to be removed
56+
Removing
57+
// Removed means that device successfully removed but not yet deleted from meta store
58+
Removed
59+
)
60+
61+
func (s DeviceState) String() string {
62+
switch s {
63+
case Creating:
64+
return "Creating"
65+
case Created:
66+
return "Created"
67+
case Activating:
68+
return "Activating"
69+
case Activated:
70+
return "Activated"
71+
case Suspending:
72+
return "Suspending"
73+
case Suspended:
74+
return "Suspended"
75+
case Resuming:
76+
return "Resuming"
77+
case Resumed:
78+
return "Resumed"
79+
case Deactivating:
80+
return "Deactivating"
81+
case Deactivated:
82+
return "Deactivated"
83+
case Removing:
84+
return "Removing"
85+
case Removed:
86+
return "Removed"
87+
default:
88+
return fmt.Sprintf("unknown %d", s)
89+
}
90+
}
91+
92+
// DeviceInfo represents metadata for thin device within thin-pool
93+
type DeviceInfo struct {
94+
// DeviceID is a 24-bit number assigned to a device within thin-pool device
95+
DeviceID uint32 `json:"device_id"`
96+
// Size is a thin device size
97+
Size uint64 `json:"size"`
98+
// Name is a device name to be used in /dev/mapper/
99+
Name string `json:"name"`
100+
// ParentName is a name of parent device (if snapshot)
101+
ParentName string `json:"parent_name"`
102+
// State represents current device state
103+
State DeviceState `json:"state"`
104+
// Error details if device state change failed
105+
Error string `json:"error"`
106+
}

0 commit comments

Comments
 (0)