Remote job execution via Receptor

Receptor is a system for remotely executing jobs and returning results, over a mesh overlay network that can easily be extended across complex underlying network. Receptor support within Ansible Runner enables running Ansible jobs remotely, via a Receptor network.

Command Line Interface

To run a job remotely, the new –via-receptor command-line parameter is used. For example, to run the demo job on a remote Receptor node named node1, the following command can be used:

$ ansible-runner run demo/ -p test.yml --via-receptor node1

By default, Ansible Runner will attempt to contact the Receptor mesh by connecting to a local Receptor node listening on the default port. This behavior can be controlled using the –receptor-peer option:

$ ansible-runner run demo/ -p test.yml --via-receptor node1 --receptor-peer receptor://host.example.com:1234

In this example, Ansible Runner will access the Receptor mesh by connecting to TCP port 1234 on host.example.com and sending a message addressed to the Receptor node-id node1. The Receptor instance on port 1234 does not need to be node1 - reaching node1 may involve additional hops on the Receptor overlay network.

In the current implementation, Ansible Runner communicates with a Receptor peer by launching a new, short-duration Receptor node within Ansible Runner’s local Python interpreter. Normally, this new node will be given a unique temporary node-id generated by the system. If it is necessary to use a specific node-id, this can be achieved as follows:

$ ansible-runner run demo/ -p test.yml --via-receptor node1 --receptor-node-id runner-node

In this example, Ansible Runner will connect to the default Receptor port on localhost, identifying itself as runner-node, and will then send the job to the Receptor node node1.

Python API

Jobs can be executed via Receptor by passing the via_receptor, receptor_peer and receptor_node_id parameters to receptor.run. The parameters work as described in the above section. Note that the Receptor interface does not yet support run_async.

Server Configuration

To receive jobs, all that is needed is an operational Receptor node, with Ansible Runner installed in the Python environment from which Receptor is running. Receptor will detect, via setuptools, that Ansible Runner is installed.