kotovalexarian-likes-github/moby--moby
1
0
Fork 0
mirror of https://github.com/moby/moby.git synced 2022-11-09 12:21:53 -05:00
Code Releases Activity
moby--moby/api
History
Kir Kolyshkin 7120976d74 Implement none, private, and shareable ipc modes 
Since the commit d88fe447df ("Add support for sharing /dev/shm/ and
/dev/mqueue between containers") container's /dev/shm is mounted on the
host first, then bind-mounted inside the container. This is done that
way in order to be able to share this container's IPC namespace
(and the /dev/shm mount point) with another container.

Unfortunately, this functionality breaks container checkpoint/restore
(even if IPC is not shared). Since /dev/shm is an external mount, its
contents is not saved by `criu checkpoint`, and so upon restore any
application that tries to access data under /dev/shm is severily
disappointed (which usually results in a fatal crash).

This commit solves the issue by introducing new IPC modes for containers
(in addition to 'host' and 'container:ID'). The new modes are:

 - 'shareable':	enables sharing this container's IPC with others
		(this used to be the implicit default);

 - 'private':	disables sharing this container's IPC.

In 'private' mode, container's /dev/shm is truly mounted inside the
container, without any bind-mounting from the host, which solves the
issue.

While at it, let's also implement 'none' mode. The motivation, as
eloquently put by Justin Cormack, is:

> I wondered a while back about having a none shm mode, as currently it is
> not possible to have a totally unwriteable container as there is always
> a /dev/shm writeable mount. It is a bit of a niche case (and clearly
> should never be allowed to be daemon default) but it would be trivial to
> add now so maybe we should...

...so here's yet yet another mode:

 - 'none':	no /dev/shm mount inside the container (though it still
		has its own private IPC namespace).

Now, to ultimately solve the abovementioned checkpoint/restore issue, we'd
need to make 'private' the default mode, but unfortunately it breaks the
backward compatibility. So, let's make the default container IPC mode
per-daemon configurable (with the built-in default set to 'shareable'
for now). The default can be changed either via a daemon CLI option
(--default-shm-mode) or a daemon.json configuration file parameter
of the same name.

Note one can only set either 'shareable' or 'private' IPC modes as a
daemon default (i.e. in this context 'host', 'container', or 'none'
do not make much sense).

Some other changes this patch introduces are:

1. A mount for /dev/shm is added to default OCI Linux spec.

2. IpcMode.Valid() is simplified to remove duplicated code that parsed
   'container:ID' form. Note the old version used to check that ID does
   not contain a semicolon -- this is no longer the case (tests are
   modified accordingly). The motivation is we should either do a
   proper check for container ID validity, or don't check it at all
   (since it is checked in other places anyway). I chose the latter.

3. IpcMode.Container() is modified to not return container ID if the
   mode value does not start with "container:", unifying the check to
   be the same as in IpcMode.IsContainer().

3. IPC mode unit tests (runconfig/hostconfig_test.go) are modified
   to add checks for newly added values.

[v2: addressed review at https://github.com/moby/moby/pull/34087#pullrequestreview-51345997]
[v3: addressed review at https://github.com/moby/moby/pull/34087#pullrequestreview-53902833]
[v4: addressed the case of upgrading from older daemon, in this case
     container.HostConfig.IpcMode is unset and this is valid]
[v5: document old and new IpcMode values in api/swagger.yaml]
[v6: add the 'none' mode, changelog entry to docs/api/version-history.md]

Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
2017-08-14 10:50:39 +03:00
..
errors add testcase with api/errors/errors_test.go 2017-05-02 17:03:31 +08:00
fixtures
server Fix api server null pointer def on inspect/ls null ipam-driver networks 2017-08-03 13:35:58 -07:00
templates/server hack/swagger-gen.sh is not exist, it should be /hack/generate-swagger-api.sh 2016-11-22 16:32:32 +08:00
types Implement none, private, and shareable ipc modes 2017-08-14 10:50:39 +03:00
common.go Bump API version to 1.32 2017-07-27 18:50:31 +02:00
common_test.go Move some api package functions away 2017-06-23 19:37:26 +02:00
common_unix.go Windows: Require REST 1.25 or later 2016-10-31 14:33:59 -07:00
common_windows.go Fix a bit typos 2016-12-09 03:05:11 +08:00
names.go Move names to package api 2016-12-21 22:42:47 +01:00
README.md Minor grammatical fix 2017-05-01 03:30:27 -06:00
swagger-gen.yaml Use a config to generate swagger api types 2016-10-31 11:13:41 -04:00
swagger.yaml Implement none, private, and shareable ipc modes 2017-08-14 10:50:39 +03:00

README.md

Working on the Engine API

The Engine API is an HTTP API used by the command-line client to communicate with the daemon. It can also be used by third-party software to control the daemon.

It consists of various components in this repository:

  • api/swagger.yaml A Swagger definition of the API.
  • api/types/ Types shared by both the client and server, representing various objects, options, responses, etc. Most are written manually, but some are automatically generated from the Swagger definition. See #27919 for progress on this.
  • cli/ The command-line client.
  • client/ The Go client used by the command-line client. It can also be used by third-party Go programs.
  • daemon/ The daemon, which serves the API.

## Swagger definition

The API is defined by the Swagger definition in api/swagger.yaml. This definition can be used to:

  1. Automatically generate documentation.
  2. Automatically generate the Go server and client. (A work-in-progress.)
  3. Provide a machine readable version of the API for introspecting what it can do, automatically generating clients for other languages, etc.

Updating the API documentation

The API documentation is generated entirely from api/swagger.yaml. If you make updates to the API, you'll need to edit this file to represent the change in the documentation.

The file is split into two main sections:

  • definitions, which defines re-usable objects used in requests and responses
  • paths, which defines the API endpoints (and some inline objects which don't need to be reusable)

To make an edit, first look for the endpoint you want to edit under paths, then make the required edits. Endpoints may reference reusable objects with $ref, which can be found in the definitions section.

There is hopefully enough example material in the file for you to copy a similar pattern from elsewhere in the file (e.g. adding new fields or endpoints), but for the full reference, see the Swagger specification

swagger.yaml is validated by hack/validate/swagger to ensure it is a valid Swagger definition. This is useful for when you are making edits to ensure you are doing the right thing.

Viewing the API documentation

When you make edits to swagger.yaml, you may want to check the generated API documentation to ensure it renders correctly.

Run make swagger-docs and a preview will be running at http://localhost. Some of the styling may be incorrect, but you'll be able to ensure that it is generating the correct documentation.

The production documentation is generated by vendoring swagger.yaml into docker/docker.github.io.