0071832226
Until now it's been possible to set per-interface sysctls using, for
example, '--sysctl net.ipv6.conf.eth0.accept_ra=2'. But, the index in
the interface name is allocated serially, and the numbering in a container
with more than one interface may change when a container is restarted.
The change to make it possible to connect a container to more than one
network when it's created increased the ambiguity.
This change adds label "com.docker.network.endpoint.sysctls" to the
DriverOpts in EndpointSettings. This option is explicitly associated
with the interface.
Settings in "--sysctl" for "eth0" are migrated to DriverOpts.
Because using "--sysctl" with any interface apart from "eth0" would have
unpredictable results, it is now an error to use any other interface name
in the top level "--sysctl" option. The error message includes a hint at
how to use the new per-interface setting.
The per-endpoint sysctl name has the interface name replaced by
"IFNAME". For example:
net.ipv6.conf.eth0.accept_ra=2
becomes:
net.ipv6.conf.IFNAME.accept_ra=2
The value of DriverOpts["com.docker.network.endpoint.sysctls"] is a
comma separated list.
Settings from '--sysctl' are applied by the runtime lib during task
creation. So, task creation fails if the endpoint does not exist.
Applying per-endpoint settings during interface configuration means the
endpoint can be created later, which paves the way for removal of the
SetKey OCI prestart hook.
Unlike other DriverOpts, the sysctl label itself is not driver-specific,
but each driver has a chance to check settings/values and raise an error
if a setting would cause it a problem - no such checks have been added
in this initial version. As a future extension, if required, it would be
possible for the driver to echo back valid/extended/modified settings to
libnetwork for it to apply to the interface. (At that point, the syntax
for the options could become driver specific to allow, for example, a
driver to create more than one interface).
Signed-off-by: Rob Murray <rob.murray@docker.com>
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.yamlA 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, 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 responsespaths, 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 when 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:9000. 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.