diff --git a/changelogs/fragments/64635-docker_container-network_mode.yml b/changelogs/fragments/64635-docker_container-network_mode.yml new file mode 100644 index 0000000000..f0cbfeb3d7 --- /dev/null +++ b/changelogs/fragments/64635-docker_container-network_mode.yml @@ -0,0 +1,2 @@ +deprecated_features: +- "docker_container - the default value for ``network_mode`` will change in Ansible 2.14, provided at least one network is specified and ``networks_cli_compatible`` is ``true``. See porting guide, module documentation or deprecation warning for more details." diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.10.rst b/docs/docsite/rst/porting_guides/porting_guide_2.10.rst index 5199503837..e62dc037c4 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.10.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.10.rst @@ -75,6 +75,7 @@ The following functionality will be removed in Ansible 2.14. Please update updat The following functionality will change in Ansible 2.14. Please update update your playbooks accordingly. * The :ref:`docker_container ` module has a new option, ``container_default_behavior``, whose default value will change from ``compatibility`` to ``no_defaults``. Set to an explicit value to avoid deprecation warnings. +* The :ref:`docker_container ` module's ``network_mode`` option will be set by default to the name of the first network in ``networks`` if at least one network is given and ``networks_cli_compatible`` is ``true`` (will be default from Ansible 2.12 on). Set to an explicit value to avoid deprecation warnings if you specify networks and set ``networks_cli_compatible`` to ``true``. The current default (not specifying it) is equivalent to the value ``default``. * :ref:`iam_policy `: the default value for the ``skip_duplicates`` option will change from ``true`` to ``false``. To maintain the existing behavior explicitly set it to ``true``. * :ref:`iam_role `: the ``purge_policies`` option (also know as ``purge_policy``) default value will change from ``true`` to ``false`` diff --git a/lib/ansible/modules/cloud/docker/docker_container.py b/lib/ansible/modules/cloud/docker/docker_container.py index d7ef9f0027..f6304cdb7e 100644 --- a/lib/ansible/modules/cloud/docker/docker_container.py +++ b/lib/ansible/modules/cloud/docker/docker_container.py @@ -527,7 +527,11 @@ options: required: yes network_mode: description: - - Connect the container to a network. Choices are C(bridge), C(host), C(none) or C(container:). + - Connect the container to a network. Choices are C(bridge), C(host), C(none), C(container:), C() or C(default). + - "*Note* that from Ansible 2.14 on, if I(networks_cli_compatible) is C(true) and I(networks) contains at least one network, + the default value for I(network_mode) will be the name of the first network in the I(networks) list. You can prevent this + by explicitly specifying a value for I(network_mode), like the default value C(default) which will be used by Docker if + I(network_mode) is not specified." type: str userns_mode: description: @@ -582,10 +586,13 @@ options: - "If I(networks_cli_compatible) is set to C(yes), this module will behave as C(docker run --network) and will *not* add the default network if I(networks) is specified. If I(networks) is not specified, the default network will be attached." - - "Note that docker CLI also sets I(network_mode) to the name of the first network + - "*Note* that docker CLI also sets I(network_mode) to the name of the first network added if C(--network) is specified. For more compatibility with docker CLI, you explicitly have to set I(network_mode) to the name of the first network you're - adding." + adding. This behavior will change for Ansible 2.14: then I(network_mode) will + automatically be set to the first network name in I(networks) if I(network_mode) + is not specified, I(networks) has at least one entry and I(networks_cli_compatible) + is C(true)." - Current value is C(no). A new default of C(yes) will be set in Ansible 2.12. type: bool version_added: "2.8" @@ -3364,6 +3371,18 @@ def main(): 'it to `no`', version='2.12' ) + if client.module.params['networks_cli_compatible'] is True and client.module.params['networks'] and client.module.params['network_mode'] is None: + client.module.deprecate( + 'Please note that the default value for `network_mode` will change from not specified ' + '(which is equal to `default`) to the name of the first network in `networks` if ' + '`networks` has at least one entry and `networks_cli_compatible` is `true`. You can ' + 'change the behavior now by explicitly setting `network_mode` to the name of the first ' + 'network in `networks`, and remove this warning by setting `network_mode` to `default`. ' + 'Please make sure that the value you set to `network_mode` equals the inspection result ' + 'for existing containers, otherwise the module will recreate them. You can find out the ' + 'correct value by running "docker inspect --format \'{{.HostConfig.NetworkMode}}\' "', + version='2.14' + ) try: cm = ContainerManager(client)