diff --git a/docs/ansible.rst b/docs/ansible.rst index 0918b2f1..c30fffc2 100644 --- a/docs/ansible.rst +++ b/docs/ansible.rst @@ -57,7 +57,7 @@ write files. Installation ------------ -1. Thoroughly review :ref:`noteworthy_differences` and :ref:`changelog`. +1. Thoroughly review :ref:`noteworthy_differences` and :ref:`known_issues`. 2. Download and extract |mitogen_url|. 3. Modify ``ansible.cfg``: diff --git a/docs/changelog.rst b/docs/changelog.rst index b7c41808..632274b6 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -15,6 +15,116 @@ Release Notes +.. _known_issues: + +Known Issues +------------ + +Mitogen For Ansible +~~~~~~~~~~~~~~~~~~~ + +* The Ansible 2.7 `reboot + `_ module + may require a ``pre_reboot_delay`` on systemd hosts, as insufficient time + exists for the reboot command's exit status to be reported before necessary + processes are torn down. + +* On OS X when a SSH password is specified and the default connection type of + ``smart`` is used, Ansible may select the Paramiko plug-in rather than + Mitogen. If you specify a password on OS X, ensure ``connection: ssh`` + appears in your playbook, ``ansible.cfg``, or as ``-c ssh`` on the + command-line. + +* The ``raw`` action executes as a regular Mitogen connection, which requires + Python on the target, precluding its use for installing Python. This will be + addressed in a future 0.2 release. For now, simply mix Mitogen and vanilla + Ansible strategies in your playbook: + + .. code-block:: yaml + + - hosts: web-servers + strategy: linear + tasks: + - name: Install Python if necessary. + raw: test -e /usr/bin/python || apt install -y python-minimal + + - hosts: web-servers + strategy: mitogen_linear + roles: + - nginx + - initech_app + - y2k_fix + +.. * When running with ``-vvv``, log messages will be printed to the console + *after* the Ansible run completes, as connection multiplexer shutdown only + begins after Ansible exits. This is due to a lack of suitable shutdown hook + in Ansible, and is fairly harmless, albeit cosmetically annoying. A future + release may include a solution. + +.. * Configurations will break that rely on the `hashbang argument splitting + behaviour `_ of the + ``ansible_python_interpreter`` setting, contrary to the Ansible + documentation. This will be addressed in a future 0.2 release. + +* Performance does not scale linearly with target count. This requires + significant additional work, as major bottlenecks exist in the surrounding + Ansible code. Performance-related bug reports for any scenario remain + welcome with open arms. + +* Performance on Python 3 is significantly worse than on Python 2. While this + has not yet been investigated, at least some of the regression appears to be + part of the core library, and should therefore be straightforward to fix as + part of 0.2.x. + +* *Module Replacer* style Ansible modules are not supported. + +* Actions are single-threaded for each `(host, user account)` combination, + including actions that execute on the local machine. Playbooks may experience + slowdown compared to vanilla Ansible if they employ long-running + ``local_action`` or ``delegate_to`` tasks delegating many target hosts to a + single machine and user account. + +* Connection Delegation remains in preview and has bugs around how it infers + connections. Connection establishment will remain single-threaded for the 0.2 + series, however connection inference bugs will be addressed in a future 0.2 + release. + +* Connection Delegation does not support automatic tunnelling of SSH-dependent + actions, such as the ``synchronize`` module. This will be addressed in the + 0.3 series. + + +Core Library +~~~~~~~~~~~~ + +* Serialization is still based on :mod:`pickle`. While there is high confidence + remote code execution is impossible in Mitogen's configuration, an untrusted + context may at least trigger disproportionately high memory usage injecting + small messages (*"billion laughs attack"*). Replacement is an important + future priority, but not critical for an initial release. + +* Child processes are not reliably reaped, leading to a pileup of zombie + processes when a program makes many short-lived connections in a single + invocation. This does not impact Mitogen for Ansible, however it limits the + usefulness of the core library. A future 0.2 release will address it. + +* Some races remain around :class:`mitogen.core.Broker ` destruction, + disconnection and corresponding file descriptor closure. These are only + problematic in situations where child process reaping is also problematic. + +* The `fakessh` component does not shut down correctly and requires flow + control added to the design. While minimal fixes are possible, due to the + absence of flow control the original design is functionally incomplete. + +* The multi-threaded :ref:`service` remains in a state of design flux and + should be considered obsolete, despite heavy use in Mitogen for Ansible. A + future replacement may be integrated more tightly with, or entirely replace + the RPC dispatcher on the main thread. + +* Documentation is in a state of disrepair. This will be improved over the 0.2 + series. + + v0.2.4 (2018-??-??) ------------------ @@ -502,75 +612,6 @@ Mitogen for Ansible * Built-in file transfer compatible with connection delegation. -**Known Issues** - -* On OS X when a SSH password is specified and the default connection type of - ``smart`` is used, Ansible may select the Paramiko plug-in rather than - Mitogen. If you specify a password on OS X, ensure ``connection: ssh`` - appears in your playbook, ``ansible.cfg``, or as ``-c ssh`` on the - command-line. - -* The ``raw`` action executes as a regular Mitogen connection, which requires - Python on the target, precluding its use for installing Python. This will be - addressed in a future 0.2 release. For now, simply mix Mitogen and vanilla - Ansible strategies in your playbook: - - .. code-block:: yaml - - - hosts: web-servers - strategy: linear - tasks: - - name: Install Python if necessary. - raw: test -e /usr/bin/python || apt install -y python-minimal - - - hosts: web-servers - strategy: mitogen_linear - roles: - - nginx - - initech_app - - y2k_fix - -.. * When running with ``-vvv``, log messages will be printed to the console - *after* the Ansible run completes, as connection multiplexer shutdown only - begins after Ansible exits. This is due to a lack of suitable shutdown hook - in Ansible, and is fairly harmless, albeit cosmetically annoying. A future - release may include a solution. - -.. * Configurations will break that rely on the `hashbang argument splitting - behaviour `_ of the - ``ansible_python_interpreter`` setting, contrary to the Ansible - documentation. This will be addressed in a future 0.2 release. - -* The Ansible 2.7 ``reboot`` module is not yet supported. - -* Performance does not scale linearly with target count. This requires - significant additional work, as major bottlenecks exist in the surrounding - Ansible code. Performance-related bug reports for any scenario remain - welcome with open arms. - -* Performance on Python 3 is significantly worse than on Python 2. While this - has not yet been investigated, at least some of the regression appears to be - part of the core library, and should therefore be straightforward to fix as - part of 0.2.x. - -* *Module Replacer* style Ansible modules are not supported. - -* Actions are single-threaded for each `(host, user account)` combination, - including actions that execute on the local machine. Playbooks may experience - slowdown compared to vanilla Ansible if they employ long-running - ``local_action`` or ``delegate_to`` tasks delegating many target hosts to a - single machine and user account. - -* Connection Delegation remains in preview and has bugs around how it infers - connections. Connection establishment will remain single-threaded for the 0.2 - series, however connection inference bugs will be addressed in a future 0.2 - release. - -* Connection Delegation does not support automatic tunnelling of SSH-dependent - actions, such as the ``synchronize`` module. This will be addressed in the - 0.3 series. - - Core Library ~~~~~~~~~~~~ @@ -583,33 +624,3 @@ Core Library Windows Subsystem for Linux explicitly supported. * Automatic tests covering Python 2.6, 2.7 and 3.6 on Linux only. - - -**Known Issues** - -* Serialization is still based on :mod:`pickle`. While there is high confidence - remote code execution is impossible in Mitogen's configuration, an untrusted - context may at least trigger disproportionately high memory usage injecting - small messages (*"billion laughs attack"*). Replacement is an important - future priority, but not critical for an initial release. - -* Child processes are not reliably reaped, leading to a pileup of zombie - processes when a program makes many short-lived connections in a single - invocation. This does not impact Mitogen for Ansible, however it limits the - usefulness of the core library. A future 0.2 release will address it. - -* Some races remain around :class:`mitogen.core.Broker ` destruction, - disconnection and corresponding file descriptor closure. These are only - problematic in situations where child process reaping is also problematic. - -* The `fakessh` component does not shut down correctly and requires flow - control added to the design. While minimal fixes are possible, due to the - absence of flow control the original design is functionally incomplete. - -* The multi-threaded :ref:`service` remains in a state of design flux and - should be considered obsolete, despite heavy use in Mitogen for Ansible. A - future replacement may be integrated more tightly with, or entirely replace - the RPC dispatcher on the main thread. - -* Documentation is in a state of disrepair. This will be improved over the 0.2 - series.