Skip to content

config-linux: Convert linux.namespaces from an array to an object #598

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wking wants to merge 1 commit into from
Closed

config-linux: Convert linux.namespaces from an array to an object #598

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 14 additions & 25 deletions config-linux.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,9 @@ A namespace wraps a global system resource in an abstraction that makes it appea
Changes to the global resource are visible to other processes that are members of the namespace, but are invisible to other processes.
For more information, see [the man page](http://man7.org/linux/man-pages/man7/namespaces.7.html).

Namespaces are specified as an array of entries inside the `namespaces` root field.
The following parameters can be specified to setup namespaces:
* **`namespaces`** (object, OPTIONAL) specifies the container namespaces.
Valid keys are:

* **`type`** *(string, REQUIRED)* - namespace type. The following namespaces types are supported:
* **`pid`** processes inside the container will only be able to see other processes inside the same container.
* **`network`** the container will have its own network stack.
* **`mount`** the container will have an isolated mount table.
Expand All @@ -35,39 +34,29 @@ The following parameters can be specified to setup namespaces:
* **`user`** the container will be able to remap user and group IDs from the host to local users and groups within the container.
* **`cgroup`** the container will have an isolated view of the cgroup hierarchy.

* **`path`** *(string, OPTIONAL)* - path to namespace file in the [runtime mount namespace](glossary.md#runtime-namespace)
Values have the following properties:

* **`path`** *(string, OPTIONAL)* - path to namespace file in the [runtime mount namespace](glossary.md#runtime-namespace)

If a path is specified, that particular file is used to join that type of namespace.
If a namespace type is not specified in the `namespaces` array, the container MUST inherit the [runtime namespace](glossary.md#runtime-namespace) of that type.
If a namespace type is not specified in the `namespaces` object, the container MUST inherit the [runtime namespace](glossary.md#runtime-namespace) of that type.
If a new namespace is not created (because the namespace type is not listed, or because it is listed with a `path`), runtimes MUST assume that the setup for that namespace has already been done and error out if the config specifies anything else related to that namespace.

###### Example

```json
"namespaces": [
{
"type": "pid",
"namespaces": {
"pid": {
"path": "/proc/1234/ns/pid"
},
{
"type": "network",
"network": {
"path": "/var/run/netns/neta"
},
{
"type": "mount"
},
{
"type": "ipc"
},
{
"type": "uts"
},
{
"type": "user"
},
{
"type": "cgroup"
}
"mount": {},
"ipc": {},
"uts": {},
"user": {},
"cgroup": {}
Copy link
Contributor

@hqhq hqhq Oct 27, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then empty and absence have different meanings, I think that's some confusing we are trying to avoid.

Copy link
Contributor Author

@wking wking Oct 27, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm ok making that distinction (like I'm ok distinguishing unset and null). If the consensus is that we shouldn't make that distinction, alternatives include:

a. Using anyOf to allow boolean or namespace-object values and requiring path in namespace-objects. E.g. "pid": true or "pid": {"path": "..."}. This is clear in JSON Schema, but may be awkward to unmarshal in Go.

b. Replace namespace objects with the path string, and distinguish between unset, empty, and non-empty strings. This makes namespace payload extension more difficult, but I don't hear anyone calling for namespace extension at the moment.

c. Keep the namespace object, require path, and distinguish between empty and non-empty strings. This is just exchanging empty-string checking (one level deeper) for the empy-object check that currently concerns you.

Copy link
Contributor Author

@wking wking Oct 27, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

d. Adding a new boolean to the namespace object and erroring if new is true and path is set/non-empty.

Copy link
Contributor

@WeiZhang555 WeiZhang555 Oct 27, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm leaning towards b, as you said, as long as we don't have the need for namespace extension, it should be enough.
For better future extension, c looks better though.

a will be really disaster for json unmarshaling, and d looks redundant.

Copy link
Contributor Author

@wking wking Oct 27, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both (b) and (c) are really close to the PR's current approach. Do folks really see a significant difference between switching on empty strings vs. empty objects?

]
```

Expand Down
38 changes: 11 additions & 27 deletions config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -279,11 +279,9 @@ For Windows based systems the user structure has the following fields:
"arch": "amd64"
},
"linux": {
"namespaces": [
{
"type": "pid"
}
]
"namespaces": {
"pid": {}
}
}
}
```
Expand Down Expand Up @@ -691,28 +689,14 @@ Here is a full example `config.json` for reference.
}
]
},
"namespaces": [
{
"type": "pid"
},
{
"type": "network"
},
{
"type": "ipc"
},
{
"type": "uts"
},
{
"type": "mount"
},
{
"type": "user"
},
{
"type": "cgroup"
}
"namespaces": {
"pid": {},
"network": {},
"ipc": {},
"uts": {},
"mount": {},
"user": {},
"cgroup": {}
],
"maskedPaths": [
"/proc/kcore",
Expand Down
30 changes: 23 additions & 7 deletions schema/config-linux.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,13 +48,29 @@
},
"namespaces": {
"id": "https://opencontainers.org/schema/bundle/linux/namespaces",
"type": "array",
"items": {
"anyOf": [
{
"$ref": "defs-linux.json#/definitions/NamespaceReference"
}
]
"type": "object",
"properties": {
"cgroup": {
"$ref": "defs-linux.json#/definitions/Namespace"
},
"ipc": {
"$ref": "defs-linux.json#/definitions/Namespace"
},
"mount": {
"$ref": "defs-linux.json#/definitions/Namespace"
},
"network": {
"$ref": "defs-linux.json#/definitions/Namespace"
},
"pid": {
"$ref": "defs-linux.json#/definitions/Namespace"
},
"user": {
"$ref": "defs-linux.json#/definitions/Namespace"
},
"uts": {
"$ref": "defs-linux.json#/definitions/Namespace"
}
}
},
"resources": {
Expand Down
17 changes: 1 addition & 16 deletions schema/defs-linux.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -262,24 +262,9 @@
}
}
},
"NamespaceType": {
"type": "string",
"enum": [
"mount",
"pid",
"network",
"uts",
"ipc",
"user",
"cgroup"
]
},
"NamespaceReference": {
"Namespace": {
"type": "object",
"properties": {
"type": {
"$ref": "#/definitions/NamespaceType"
},
"path": {
"$ref": "defs.json#/definitions/FilePath"
}
Expand Down
4 changes: 1 addition & 3 deletions specs-go/config.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,7 @@ type Linux struct {
// If resources are specified, the cgroups at CgroupsPath will be updated based on resources.
CgroupsPath *string `json:"cgroupsPath,omitempty"`
// Namespaces contains the namespaces that are created and/or joined by the container
Namespaces []LinuxNamespace `json:"namespaces,omitempty"`
Namespaces map[LinuxNamespaceType]LinuxNamespace `json:"namespaces,omitempty"`
// Devices are a list of device nodes that are created for the container
Devices []LinuxDevice `json:"devices,omitempty"`
// Seccomp specifies the seccomp security settings for the container.
Expand All @@ -158,8 +158,6 @@ type Linux struct {

// LinuxNamespace is the configuration for a Linux namespace
type LinuxNamespace struct {
// Type is the type of Linux namespace
Type LinuxNamespaceType `json:"type"`
// Path is a path to an existing namespace persisted on disk that can be joined
// and is of the same type
Path string `json:"path,omitempty"`
Expand Down