Ansible Integration

EnOSlib uses internally Ansible to perform some predefined tasks (e.g remote commands ). But in EnOSlib we prefer not leaving the Python world :) so we’ve exposed some convenient functions that use Ansible behind the scene like:

• run a single command on a subset of the nodes and gather the outputs (and errors)

• or run a set of actions (Ansible Modules) programmatically

Hint

The presented methods are provider agnostic.

Run a single command on nodes and gather results

Let’s consider the following script :

import enoslib as en

en.init_logging()

provider_conf = {
    "backend": "libvirt",
    "resources": {
        "machines": [
            {
                "roles": ["control1"],
                "flavour": "tiny",
                "number": 1,
            },
            {
                "roles": ["control2"],
                "flavour": "tiny",
                "number": 1,
            },
        ],
        "networks": [{"roles": ["rn1"], "cidr": "172.16.0.1/16"}],
    },
}

conf = en.VagrantConf.from_dictionary(provider_conf)
provider = en.Vagrant(conf)
roles, networks = provider.init()
roles = en.sync_info(roles, networks)


result = en.run_command("date", roles=roles)
print(result)

# use a list of Hosts
result = en.run_command("date", roles=roles["control1"])
print(result)

# use a single Hosts
result = en.run_command("date", roles=roles["control1"][0])
print(result)

# filter hosts using a pattern
result = en.run_command("date", pattern_hosts="control*", roles=roles)
print(result)

# async tasks / will run in detached mode
result = en.run_command("date", roles=roles, background=True)
print(result)

• run_command() takes at least 2 parameters :

  • the actual command to run

  • the Roles (as returned by the provider init method), or an iterable of Host, or a single Host

• A Results object is returned and allow for further filtering.

Run a set of actions on nodes

Using python exclusively

Let’s consider the following script:

import logging

import enoslib as en

en.init_logging(level=logging.INFO)

# The conf let us define the resources wanted.
# This is provider specific
conf = (
    en.VagrantConf()
    .from_settings(backend="libvirt")
    .add_machine(roles=["server"], flavour="tiny", number=1)
    .add_machine(roles=["client"], flavour="tiny", number=1)
    .add_network(roles=["mynetwork"], cidr="192.168.42.0/24")
)

provider = en.Vagrant(conf)

# The code below is intended to be provider-agnostic

# Start the resources
roles, networks = provider.init()


# Experimentation logic starts here
with en.actions(roles=roles) as p:
    p.apt_repository(
        repo="deb http://deb.debian.org/debian stretch main contrib non-free",
        state="present",
    )
    p.apt(
        name=["flent", "netperf", "python3-setuptools", "python3-matplotlib"],
        state="present",
    )

with en.actions(pattern_hosts="server", roles=roles) as p:
    p.shell("nohup netperf &")

with en.actions(pattern_hosts="client", roles=roles) as p:
    # get the address of server
    server_address = roles["server"][0].address
    p.shell(
        "flent rrul -p all_scaled "
        + "-l 60 "
        + f"-H { server_address } "
        + "-t 'bufferbloat test' "
        + "-o result.png"
    )
    p.fetch(src="result.png", dest="result")

flent_on.py

In this example each actions block run a playbook generated from the ansible module calls made. Any ansible module can be called here, the exact keyword arguments to pass depend on each module and you’ll need to refer to the ansible modules documentation (e.g https://docs.ansible.com/ansible/latest/modules/apt_module.html).

Re-using results from a previous task

To access results from previous tasks, you need to start a new actions block. Here is an example with Garage:

import logging
from pathlib import Path

import enoslib as en

en.init_logging(level=logging.INFO)
en.check()

GARAGE_URL = (
    "https://garagehq.deuxfleurs.fr/_releases/v0.7.3/"
    "x86_64-unknown-linux-musl/garage"
)
job_name = Path(__file__).name

conf = (
    en.G5kConf()
    .from_settings(job_name=job_name, walltime="0:40:00")
    .add_machine(roles=["garage"], cluster="ecotype", nodes=2)
)

provider = en.G5k(conf)

roles, networks = provider.init()

with en.actions(roles=roles["garage"], gather_facts=True) as p:
    p.get_url(
        task_name="Download garage",
        url=GARAGE_URL,
        dest="/tmp/garage",
        mode="755",
    )
    p.template(
        task_name="Create config",
        src=str(Path(__file__).parent / "garage.toml.j2"),
        dest="/tmp/garage.toml",
    )
    p.command(
        task_name="Kill garage if already running",
        cmd="killall garage",
        ignore_errors=True,
    )
    p.command(
        task_name="Run garage in the background",
        cmd="/tmp/garage -c /tmp/garage.toml server",
        background=True,
    )
    p.command(
        task_name="Get node ID",
        cmd="/tmp/garage -c /tmp/garage.toml node id -q",
    )

# Collect Garage nodes ID in a dictionary
results = p.results
nodes_id = {r.host: r.stdout for r in results.filter(task="Get node ID")}

with en.actions(roles=roles["garage"], gather_facts=False) as p:
    for remote_node, remote_id in nodes_id.items():
        p.command(
            task_name=f"Connect to remote node {remote_node}",
            cmd=f"/tmp/garage -c /tmp/garage.toml node connect {remote_id}",
        )


# Release all Grid'5000 resources
provider.destroy()

garage.py

garage.toml.j2

Using a yaml playbook

In addition to run custom command on nodes, EnOSlib can trigger predefined playbook stored in your filesystem. This lets you use the native Ansible syntax to describe your tasks or launch an existing playbook.

Let’s consider the following script:

import enoslib as en

en.init_logging()


provider_conf = {
    "resources": {
        "machines": [
            {
                "roles": ["control1"],
                "flavour": "tiny",
                "number": 1,
            },
            {
                "roles": ["control2"],
                "flavour": "tiny",
                "number": 1,
            },
        ],
        "networks": [{"roles": ["rn1"], "cidr": "172.16.0.1/16"}],
    }
}

conf = en.VagrantConf.from_dictionary(provider_conf)
provider = en.Vagrant(conf)
roles, networks = provider.init()

result = en.run_ansible(["site.yml"], roles=roles)
print(result)

run_ansible.py

And the corresponding minimal playbook site.yml:

---
- name: This is a play
  hosts: control*
  tasks:
    - name: One task
      debug:
        msg: "I'm running on {{ inventory_hostname }}"

site.yml

What’s next ?

If you aren’t familiar with Ansible, we encourage you to go through the Ansible documentation, write your own playbooks, or integrate one existing from ansible galaxy.