From 04bb5881b6aa1c73aab2f945c09008ed43a995cb Mon Sep 17 00:00:00 2001 From: David Wilson Date: Tue, 6 Mar 2018 17:01:26 +0545 Subject: [PATCH] ansible: doc updates --- docs/ansible.rst | 76 +++++++++++++++++++++++++++++------------------- docs/index.rst | 17 +++++------ 2 files changed, 53 insertions(+), 40 deletions(-) diff --git a/docs/ansible.rst b/docs/ansible.rst index 408d14c6..6dabd15f 100644 --- a/docs/ansible.rst +++ b/docs/ansible.rst @@ -29,6 +29,12 @@ time spent by the target host already doing useful work. Mitogen cannot speed up a module once it is executing, it can only ensure the module executes as quickly as possible. +.. raw:: html + +
+ +
+ * **A single SSH connection is used for each target host**, in addition to one sudo invocation per distinct user account. Subsequent playbook steps always reuse the same connection. This is much better than SSH multiplexing combined @@ -54,6 +60,31 @@ quickly as possible. relating to those files in cross-account scenarios are entirely avoided. +Installation +------------ + +.. caution:: + + Thoroughly review the list of limitations before use, and **do not test the + prototype in a live environment until this notice is removed**. + +1. Verify Ansible 2.4 and Python 2.7 are listed in the output of ``ansible + --version`` +2. Download and extract http://github.com/dw/mitogen/archive/master.zip +3. Modify ``ansible.cfg``: + + .. code-block:: dosini + + [defaults] + strategy_plugins = /path/to/mitogen-master/ansible_mitogen/plugins/strategy + strategy = mitogen + + The ``strategy`` key is optional. If omitted, you can set the + ``ANSIBLE_STRATEGY=mitogen`` environment variable on a per-run basis. + +4. Cross your fingers and try it. + + Limitations ----------- @@ -70,6 +101,9 @@ High Risk `_ has received minimal testing. +* For now only **built-in Python command modules work**, however almost all + modules shipped with Ansible are Python-based. + * Transfer of large (i.e. GB-sized) files using certain Ansible-internal APIs, such as triggered via the ``copy`` module, will cause corresponding temporary memory and CPU spikes on both host and target machine, due to delivering the @@ -81,6 +115,10 @@ High Risk respected, however ``delegate_to``, ``connection: local``, ``become``, ``become_user``, and ``local_action`` have all been tested. +* Only Ansible 2.4 is being used for development, with occasional tests under + 2.3 and 2.2. It should be more than possible to fully support at least 2.3, + if not also 2.2. + Low Risk ~~~~~~~~ @@ -97,9 +135,6 @@ Low Risk * Interaction with modules employing special action plugins is minimally tested, except for the ``synchronize``, ``template`` and ``copy`` modules. -* For now only Python command modules work, however almost all modules shipped - with Ansible are Python-based. - * Uncaptured standard output of remotely executing modules and shell commands are logged to the console. This will be fixed in a later version. @@ -129,29 +164,8 @@ Behavioural Differences connection to host closed`` to appear in ``stderr`` output of every executed command. This never manifests with the Mitogen extension. -* Asynchronous jobs execute in a thread of the single target Python - interpreter. In future this will be replaced with subprocesses, as it's - likely some use cases spawn many asynchronous jobs. - - -Configuration -------------- - -.. warning:: - - Don't test the prototype in a live environment until this notice is removed. - -1. Ensure the host machine is using Python 2.x for Ansible by verifying the - output of ``ansible --version``. Ensure the ``python`` command starts a - Python 2.x interpreter. If not, substitute ``python`` for the correct - command in steps 2 and 3. -2. ``python -m pip install -U git+https://github.com/dw/mitogen.git`` **on the - host machine only**. -3. ``python -c 'import ansible_mitogen as a; print a.__path__'`` -4. Add ``strategy_plugins = /path/to/../ansible_mitogen/plugins/strategy`` using the - path from above to the ``[defaults]`` section of ``ansible.cfg``. -5. Add ``strategy = mitogen`` to the ``[defaults]`` section of ``ansible.cfg``. -6. Cross your fingers and try it out. +* Asynchronous support is very primitive, and jobs execute in a thread of the + target Python interpreter. This will fixed shortly. Demo @@ -232,8 +246,8 @@ The extension aggressively reuses the single target Python interpreter to execute every module. While this works well, it violates an unwritten assumption regarding Ansible modules, and so it is possible a buggy module could cause a run to fail, or for unrelated modules to interact with each other -due to bad hygiene. Mitigations will be added as necessary if problems of this -sort ever actually manfest. +due to bad hygiene. Mitigations (such as forking) will be added as necessary if +problems of this sort ever actually manfest. Patches ~~~~~~~ @@ -244,8 +258,8 @@ mechanism for selecting a connection plug-in. While it is hoped the patches can be avoided in future, for interesting versions of Ansible deployed today this simply is not possible, and so they continue to be required. -The patches are well defined, act conservatively including by disabling -themselves when non-Mitogen connections are in use, and additional third party +The patches are concise and behave conservatively, including by disabling +themselves when non-Mitogen connections are in use. Additional third party plug-ins are unlikely to attempt similar patches, so the risk to an established configuration should be minimal. @@ -260,6 +274,8 @@ equivalent semantics. This allows: such as forwarding SSH agents across ``sudo`` invocations, * reporting on conflicting flag combinations, * reporting on unsupported flag combinations, +* internally special-casing certain behaviour (like recursive agent forwarding) + without boring the user with the details, * avoiding opening the extension up to untestable scenarios where users can insert arbitrary garbage between Mitogen and the components it integrates with, diff --git a/docs/index.rst b/docs/index.rst index da108372..977f443e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,18 +12,15 @@ Mitogen is a Python library for writing distributed self-replicating programs. } -.. warning:: +.. caution:: - This is alpha-quality code. If you intend to use it, be aware of how little - real world testing it has received, the total absence of any systematic - tests, and the nightmare-level difficulty of debugging hangs in a tree of - processes running identical code straddling multiple thread and machine - boundaries! ``router.enable_debug()`` is your friend. + Be aware this is prerelease code, and that comprehensive automated tests + are presently absent. + :py:meth:`Router.enable_debug() ` is + your friend. If have a use for this software, please `drop an e-mail`_ so + expectations and bug fixes can be managed sensibly. - If you think you have a use for this software, please `drop me an e-mail`_ - so that expectations and bug fixes can be managed sensibly. - - .. _drop me an e-mail: dw@botanicus.net + .. _drop an e-mail: dw@botanicus.net .. image:: images/cell_division.png :align: right