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	Add more unit tests (thus coverage) to pkg api	2015-08-04 19:51:02 +02:00
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:

Automatically generate documentation.
Automatically generate the Go server and client. (A work-in-progress.)
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.