diff --git a/docs/ansible.rst b/docs/ansible.rst index dc37cfd4..5d069a13 100644 --- a/docs/ansible.rst +++ b/docs/ansible.rst @@ -7,8 +7,8 @@ Ansible Extension An experimental extension to `Ansible`_ is included that implements host connections over Mitogen, replacing embedded shell invocations with pure-Python -equivalents invoked over SSH via highly efficient remote procedure calls. No -changes are required to the target hosts. +equivalents invoked via highly efficient remote procedure calls tunnelled over +SSH. No changes are required to the target hosts. The extension isn't nearly in a generally dependable state yet, however it already works well enough for testing against real-world playbooks. `Bug @@ -23,29 +23,30 @@ significant testing will prove the extension's soundness. Overview -------- -You should expect a general speedup ranging from 1.5x to 5x depending on -network conditions, the specific modules executed, and time spent by the target -host already doing useful work. Mitogen cannot speed up a module once it is +You should **expect a speedup between 1.5x and 5x** depending on network +conditions, the specific modules executed, and 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. -* 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 with - pipelining, as significant state can be maintained in RAM between steps, and - the system logs aren't filled with spam from repeat SSH and sudo invocations. +* **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 + with pipelining, as significant state can be maintained in RAM between steps, + and the system logs aren't filled with spam from repeat SSH and sudo + invocations. -* A single Python interpreter is used per host and sudo account combination for - the duration of the run, avoiding the repeat cost of invoking multiple +* **A single Python interpreter is used** per host and sudo account combination + for the duration of the run, avoiding the repeat cost of invoking multiple interpreters and recompiling imports, saving 300-1000 ms for every playbook step. * Remote interpreters reuse Mitogen's module import mechanism, caching uploaded dependencies between steps at the host and user account level. As a - consequence, bandwidth usage is consistently an order of magnitude lower + consequence, **bandwidth usage is consistently an order of magnitude lower** compared to SSH pipelining, and around 5x fewer frames are required to traverse the wire for a run to complete successfully. -* No writes to the target host's filesystem occur, unless explicitly +* **No writes to the target host's filesystem occur**, unless explicitly triggered by a playbook step. In all typical configurations, Ansible repeatedly rewrites and extracts ZIP files to multiple temporary directories on the target host. Since no temporary files are used, security issues @@ -104,7 +105,8 @@ Local VM connection This demonstrates Mitogen vs. connection pipelining to a local VM, executing the 100 simple repeated steps of ``run_hostname_100_times.yml`` from the -examples directory. Mitogen uses 43x less bandwidth and 4.25x less time. +examples directory. Mitogen requires **43x less bandwidth and 4.25x less +time**. .. image:: images/ansible/run_hostname_100_times.png