archive
/
mitogen
mirror of https://github.com/mitogen-hq/mitogen.git
1
0
Fork 0
Code Releases Activity

ansible: doc updates

Browse Source
wip-fakessh-exit-status
David Wilson 7 years ago
parent 95ea75907d
commit 04bb5881b6
2 changed files with 53 additions and 40 deletions
Show Stats Download Patch File Download Diff File

76
docs/ansible.rst
Unescape Escape View File

@ -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
<div style="float:right; border:1px solid silver;margin-left: 16px;">
<iframe src="https://www.kickstarter.com/projects/548438714/mitogen-extension-for-ansible/widget/card.html?v=2" width="220" height="420" frameborder="0" scrolling="no" target="_blank"></iframe>
</div>
* **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
<http://docs.ansible.com/ansible/latest/playbooks_async.html>`_ 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,

17
docs/index.rst
Unescape Escape View File

@ -12,18 +12,15 @@ Mitogen is a Python library for writing distributed self-replicating programs.
}
</style>
.. 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() <mitogen.master.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

Write Preview
Loading…
Cancel
Save