diff --git a/docs/api.md b/docs/api.md index eaa08a15..26dfe608 100644 --- a/docs/api.md +++ b/docs/api.md @@ -188,8 +188,7 @@ character, bytes are assumed as an intended unit. `volumes_from` and `dns` arguments raise [TypeError]( https://docs.python.org/3.4/library/exceptions.html#TypeError) exception if they are used against v1.10 and above of the Docker remote API. Those -arguments should be passed to `start()` instead, or as part of the `host_config` -dictionary. +arguments should be passed as part of the `host_config` dictionary. **Params**: @@ -715,83 +714,9 @@ Identical to the `docker search` command. Similar to the `docker start` command, but doesn't support attach options. Use `.logs()` to recover `stdout`/`stderr`. -`binds` allows to bind a directory in the host to the container. See [Using -volumes](volumes.md) for more information. - -`port_bindings` exposes container ports to the host. -See [Port bindings](port-bindings.md) for more information. - -`lxc_conf` allows to pass LXC configuration options using a dictionary. - -`privileged` starts the container in privileged mode. - -[Links](http://docs.docker.io/en/latest/use/working_with_links_names/) can be -specified with the `links` argument. They can either be specified as a -dictionary mapping name to alias or as a list of `(name, alias)` tuples. - -`dns` and `volumes_from` are only available if they are used with version v1.10 -of docker remote API. Otherwise they are ignored. - -`network_mode` is available since v1.11 and sets the Network mode for the -container ('bridge': creates a new network stack for the container on the -Docker bridge, 'none': no networking for this container, 'container:[name|id]': -reuses another container network stack), 'host': use the host network stack -inside the container. - -`restart_policy` is available since v1.2.0 and sets the RestartPolicy for how a -container should or should not be restarted on exit. By default the policy is -set to no meaning do not restart the container when it exits. The user may -specify the restart policy as a dictionary for example: -```python -{ - "MaximumRetryCount": 0, - "Name": "always" -} -``` - -For always restarting the container on exit or can specify to restart the -container to restart on failure and can limit number of restarts. For example: -```python -{ - "MaximumRetryCount": 5, - "Name": "on-failure" -} -``` - -`cap_add` and `cap_drop` are available since v1.2.0 and can be used to add or -drop certain capabilities. The user may specify the capabilities as an array -for example: -```python -[ - "SYS_ADMIN", - "MKNOD" -] -``` - -**Params**: - -* container (str): The container to start -* binds: Volumes to bind -* port_bindings (dict): Port bindings. See note above -* lxc_conf (dict): LXC config -* publish_all_ports (bool): Whether to publish all ports to the host -* links (dict or list of tuples): See note above -* privileged (bool): Give extended privileges to this container -* dns (list): Set custom DNS servers -* dns_search (list): DNS search domains -* volumes_from (str or list): List of container names or Ids to get volumes -from. Optionally a single string joining container id's with commas -* network_mode (str): One of `['bridge', None, 'container:', -'host']` -* restart_policy (dict): See note above. "Name" param must be one of -`['on-failure', 'always']` -* cap_add (list of str): See note above -* cap_drop (list of str): See note above -* extra_hosts (dict): custom host-to-IP mappings (host:ip) -* pid_mode (str): if set to "host", use the host PID namespace inside the - container -* security_opt (list): A list of string values to customize labels for MLS systems, such as SELinux. -* ulimits (list): A list of dicts or `docker.utils.Ulimit` objects. +**Deprecation warning:** For API version > 1.15, it is highly recommended to + provide host config options in the + [`host_config` parameter of `create_container`](#create_container) ```python >>> from docker import Client diff --git a/docs/host-devices.md b/docs/host-devices.md index ae1d32b1..f1ee3e1b 100644 --- a/docs/host-devices.md +++ b/docs/host-devices.md @@ -1,10 +1,15 @@ # Access to devices on the host If you need to directly expose some host devices to a container, you can use -the devices parameter in the `Client.start` method as shown below +the devices parameter in the `host_config` param in `Client.create_container` +as shown below: ```python -c.start(container_id, devices=['/dev/sda:/dev/xvda:rwm']) +c.create_container( + 'busybox', 'true', host_config=docker.utils.create_host_config(devices=[ + '/dev/sda:/dev/xvda:rwm' + ]) +) ``` Each string is a single mapping using the colon (':') as the separator. So the diff --git a/docs/hostconfig.md b/docs/hostconfig.md index 99ffe1c6..c9f94641 100644 --- a/docs/hostconfig.md +++ b/docs/hostconfig.md @@ -1,6 +1,8 @@ # HostConfig object -The Docker Remote API introduced [support for HostConfig in version 1.15](http://docs.docker.com/reference/api/docker_remote_api_v1.15/#create-a-container). This object contains all the parameters you can pass to `Client.start`. +The Docker Remote API introduced [support for HostConfig in version 1.15](http://docs.docker.com/reference/api/docker_remote_api_v1.15/#create-a-container). This object contains all the parameters you could previously pass to `Client.start`. +*It is highly recommended that users pass the HostConfig in the `host_config`* +*param of `Client.create_container` instead of `Client.start`* ## HostConfig helper diff --git a/docs/port-bindings.md b/docs/port-bindings.md index 90523f24..7456b86f 100644 --- a/docs/port-bindings.md +++ b/docs/port-bindings.md @@ -1,38 +1,39 @@ # Port bindings Port bindings is done in two parts. Firstly, by providing a list of ports to open inside the container in the `Client().create_container()` method. +Bindings are declared in the `host_config` parameter. ```python -container_id = c.create_container('busybox', 'ls', ports=[1111, 2222]) +container_id = c.create_container( + 'busybox', 'ls', ports=[1111, 2222], + host_config=docker.utils.create_host_config(port_bindings={ + 1111: 4567, + 2222: None + }) +) ``` -Bindings are then declared in the `Client.start` method. - -```python -c.start(container_id, port_bindings={1111: 4567, 2222: None}) -``` You can limit the host address on which the port will be exposed like such: ```python -c.start(container_id, port_bindings={1111: ('127.0.0.1', 4567)}) +docker.utils.create_host_config(port_bindings={1111: ('127.0.0.1', 4567)}) ``` Or without host port assignment: ```python -c.start(container_id, port_bindings={1111: ('127.0.0.1',)}) +docker.utils.create_host_config(port_bindings={1111: ('127.0.0.1',)}) ``` -If you wish to use UDP instead of TCP (default), you need to declare it -like such in both the `create_container()` and `start()` calls: +If you wish to use UDP instead of TCP (default), you need to declare ports +as such in both the config and host config: ```python container_id = c.create_container( - 'busybox', - 'ls', - ports=[(1111, 'udp'), 2222] + 'busybox', 'ls', ports=[(1111, 'udp'), 2222], + host_config=docker.utils.create_host_config(port_bindings={ + '1111/udp': 4567, 2222: None + }) ) -c.start(container_id, port_bindings={'1111/udp': 4567, 2222: None}) ``` - diff --git a/docs/volumes.md b/docs/volumes.md index 4441b829..de282140 100644 --- a/docs/volumes.md +++ b/docs/volumes.md @@ -1,25 +1,21 @@ # Using volumes -Volume declaration is done in two parts. First, you have to provide -a list of mountpoints to the `Client().create_container()` method. +Volume declaration is done in two parts. Provide a list of mountpoints to +the `Client().create_container()` method, and declare mappings in the +`host_config` section. ```python -container_id = c.create_container('busybox', 'ls', volumes=['/mnt/vol1', '/mnt/vol2']) -``` - -Volume mappings are then declared inside the `Client.start` method like this: - -```python -c.start(container_id, binds={ - '/home/user1/': - { +container_id = c.create_container( + 'busybox', 'ls', volumes=['/mnt/vol1', '/mnt/vol2'], + host_config=docker.utils.create_host_config(binds={ + '/home/user1/': { 'bind': '/mnt/vol2', 'ro': False }, - '/var/www': - { + '/var/www': { 'bind': '/mnt/vol1', 'ro': True } -}) + }) +) ```