minimal doc.

docs/apidoc/enoslib.infra.enos_chameleonbaremetal.rst

+enoslib\.infra\.enos\_chameleonbaremetal package
+================================================
+
+Submodules
+----------
+
+enoslib\.infra\.enos\_chameleonbaremetal\.provider module
+---------------------------------------------------------
+
+.. automodule:: enoslib.infra.enos_chameleonbaremetal.provider
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: enoslib.infra.enos_chameleonbaremetal
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/apidoc/enoslib.infra.enos_chameleonkvm.rst

+enoslib\.infra\.enos\_chameleonkvm package
+==========================================
+
+Submodules
+----------
+
+enoslib\.infra\.enos\_chameleonkvm\.provider module
+---------------------------------------------------
+
+.. automodule:: enoslib.infra.enos_chameleonkvm.provider
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: enoslib.infra.enos_chameleonkvm
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/apidoc/enoslib.infra.enos_openstack.rst

+enoslib\.infra\.enos\_openstack package
+=======================================
+
+Submodules
+----------
+
+enoslib\.infra\.enos\_openstack\.provider module
+------------------------------------------------
+
+.. automodule:: enoslib.infra.enos_openstack.provider
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: enoslib.infra.enos_openstack
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/apidoc/enoslib.infra.enos_static.rst

+enoslib\.infra\.enos\_static package
+====================================
+
+Submodules
+----------
+
+enoslib\.infra\.enos\_static\.provider module
+---------------------------------------------
+
+.. automodule:: enoslib.infra.enos_static.provider
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: enoslib.infra.enos_static
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/apidoc/enoslib.infra.rst

@@ -6,7 +6,11 @@ Subpackages
 
 .. toctree::
 
+    enoslib.infra.enos_chameleonbaremetal
+    enoslib.infra.enos_chameleonkvm
     enoslib.infra.enos_g5k
+    enoslib.infra.enos_openstack
+    enoslib.infra.enos_static
     enoslib.infra.enos_vagrant
 
 Submodules
@@ -20,6 +24,14 @@ enoslib\.infra\.provider module
     :undoc-members:
     :show-inheritance:
 
+enoslib\.infra\.utils module
+----------------------------
+
+.. automodule:: enoslib.infra.utils
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 
 Module contents
 ---------------

docs/conf.py

@@ -169,5 +169,6 @@ texinfo_documents = [
      'Miscellaneous'),
 ]
 
-
-
+rst_epilog = """
+.. |enoslib| replace:: EnOSlib
+"""

docs/getting-started.rst

@@ -3,9 +3,137 @@
 Getting Started
 ================
 
+Let's consider the following use case :
+
+- Get machines from vagrant
+- Apply some network constraints
+- Validate those network constraints
+
 Installation
 ------------
 
 .. code-block:: bash
 
     $ pip install enoslib
+
+.. note::
+
+  It's a good practice to use a virtualenv or python version manager like `pyenv`_.
+Using the API
+-------------
+
+The following ``enos.py`` implements the desired workflow.
+
+.. literalinclude:: getting-started/step1.py
+   :language: python
+   :linenos:
+
+- Lines 5-18 describe the wanted resources. Here we want two machines with roles
+  ``control`` and ``compute`` respectively. These two nodes will have one network card
+  configured using the same network whose role is ``n1``.
+
+  .. note::
+
+    Machine roles and network roles are transparent to the |enoslib|. The semantic is
+    left to the application using it.
+
+- Lines 19-23 describe some network constraints. Those constraints will be set
+  between the nodes of the two groups ``control`` and ``compute`` on the network
+  ``n1``.
+
+- Lines 27-34 enforce the wanted workflow.
+
+  .. note::
+
+    Under the hoods, |enoslib| leverages Ansible for many routine tasks and
+    thus an inventory must be generated. This is exactly the purpose of
+    :py:func:`enoslib.api.generate_inventory` function.  When
+    ``check_networks`` is set, |enoslib| will auto-discover the mapping between
+    the network roles and the available network interfaces. This is convenient
+    when it comes to deal with non uniform (or non deterministic) network cards
+    naming.
+
+
+- You can launch the script using :
+
+  .. code-block:: bash
+
+      $ python enos.py
+
+
+- The content of the generated inventory should looks like the following:
+
+  .. literalinclude:: getting-started/hosts
+     :language: python
+
+- You can check the generated reports by :py:func:`enoslib.api.validate_network` in ``_tmp_enos_``.
+
+
+  .. literalinclude:: getting-started/_tmp_enos_/enos-0.out
+     :language: python
+     :emphasize-lines: 2
+
+Using tasks
+-----------
+
+
+.. literalinclude:: getting-started/step2.py
+   :language: python
+   :emphasize-lines: 33,45,51
+   :lines: 33-65
+
+- Using Tasks is a neat way to organize your program into a workflow.
+
+- The environment (``env`` variable in the above) is a way to (1) store
+  information on the current execution and (2) pass information from one task
+  to another. It is automatically restored at the beginning of a task and saved
+  at the end.
+
+
+- You can launch the script using :
+
+  .. code-block:: bash
+
+    $ python enos.py
+
+
+Integrating with a command line parser
+--------------------------------------
+
+Let's integrate our tasks with a command line parser. Here we choose `click`_.
+First enusre that it is installed:
+
+.. code-block:: bash
+
+    $ pip install click
+
+- Change the content of ``enos.py`` to the following:
+
+  .. literalinclude:: getting-started/step3.py
+     :language: python
+     :lines: 32-75
+
+- For the sake of illustration, we added a flag (``--force``) to the command
+  line which allows to force the recreation of the virtual machines (see
+  :py:meth:`enoslib.infra.provider.Provider.init`).  Since every provider
+  supports this flag we pass its value to the ``ìnit`` method.
+
+- You will now have access to the command line interface :
+
+  .. code-block:: bash
+
+      $ python enos.py --help
+      Usage: enos.py [OPTIONS] COMMAND [ARGS]...
+
+      Options:
+        --help  Show this message and exit.
+
+      Commands:
+        emulate   Emulates the network.
+        up        Starts a new experiment using vagrant
+        validate  Validates the network constraints.
+
+.. references::
+
+.. _click: http://click.pocoo.org/
+.. _pyenv: https://github.com/pyenv/pyenv

docs/getting-started/.gitignore

+Vagrantfile
+.vagrant
+_tmp_enos_

docs/getting-started/_tmp_enos_/enos-0.out

+192.168.142.245 : 0.04 0.03 0.03 0.03 0.03
+192.168.142.244 : 41.91 41.80 41.46 42.16 41.14
+
+       2 targets
+       2 alive
+       0 unreachable
+       0 unknown addresses
+
+       0 timeouts (waiting for response)
+      10 ICMP Echos sent
+      10 ICMP Echo Replies received
+       0 other ICMP received
+
+ 0.03 ms (min round trip time)
+ 20.8 ms (avg round trip time)
+ 42.1 ms (max round trip time)
+        4.071 sec (elapsed real time)
+

docs/getting-started/hosts

+[control]
+enos-0 ansible_host=127.0.0.1 ansible_ssh_user=root ansible_port=2200 ansible_ssh_private_key_file=/Users/msimonin/sed/discovery/openstack/enoslib/docs/getting-started/.vagrant/machines/enos-0/virtualbox/private_key ansible_ssh_common_args='-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null' n1=eth1 enos_devices="['eth1']"
+[compute]
+enos-1 ansible_host=127.0.0.1 ansible_ssh_user=root ansible_port=2201 ansible_ssh_private_key_file=/Users/msimonin/sed/discovery/openstack/enoslib/docs/getting-started/.vagrant/machines/enos-1/virtualbox/private_key ansible_ssh_common_args='-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null' n1=eth1 enos_devices="['eth1']"
\ No newline at end of file

docs/getting-started/step1.py

+from enoslib.api import generate_inventory, emulate_network, validate_network
+from enoslib.infra.enos_vagrant.provider import Enos_vagrant
+
+import os
+
+provider_conf = {
+    "backend": "virtualbox",
+    "user": "root",
+    "box": "debian/jessie64",
+    "resources": {
+        "machines": [{
+            "role": "control",
+            "flavor": "tiny",
+            "number": 1,
+            "networks": ["n1"]
+        },{
+            "role": "compute",
+            "flavor": "tiny",
+            "number": 1,
+            "networks": ["n1"]
+        }]
+    }
+}
+
+tc = {
+    "enable": True,
+    "default_delay": "20ms",
+    "default_rate": "1gbit",
+}
+
+# path to the inventory
+inventory = os.path.join(os.getcwd(), "hosts")
+
+# claim the resources
+provider = Enos_vagrant(provider_conf)
+roles, networks = provider.init()
+generate_inventory(roles, networks, inventory, check_networks=True)
+
+# apply network constraints
+emulate_network(roles, inventory, tc)
+
+# validate network constraints
+validate_network(roles, inventory)

docs/getting-started/step2.py

+from enoslib.api import generate_inventory, emulate_network, validate_network
+from enoslib.task import enostask
+from enoslib.infra.enos_vagrant.provider import Enos_vagrant
+
+import click
+import os
+
+provider_conf = {
+    "backend": "virtualbox",
+    "user": "root",
+    "box": "debian/jessie64",
+    "resources": {
+        "machines": [{
+            "role": "control",
+            "flavor": "tiny",
+            "number": 1,
+            "networks": ["n1"]
+        },{
+            "role": "compute",
+            "flavor": "tiny",
+            "number": 1,
+            "networks": ["n1"]
+        }]
+    }
+}
+
+tc = {
+    "enable": True,
+    "default_delay": "20ms",
+    "default_rate": "1gbit",
+}
+
+
+@enostask(new=True)
+def up(force, env=None, **kwargs):
+    "Starts a new experiment"
+    import ipdb; ipdb.set_trace()
+    inventory = os.path.join(os.getcwd(), "hosts")
+    provider = Enos_vagrant(provider_conf)
+    roles, networks = provider.init()
+    generate_inventory(roles, networks, inventory, check_networks=True)
+    env["roles"] = roles
+    env["networks"] = networks
+    env["inventory"] = inventory
+
+
+@enostask()
+def emulate(env=None, **kwargs):
+    inventory = env["inventory"]
+    roles = env["roles"]
+    emulate_network(roles, inventory, tc)
+
+
+@enostask()
+def validate(env=None, **kwargs):
+    inventory = env["inventory"]
+    roles = env["roles"]
+    validate_network(roles, inventory)
+
+up()
+emulate()
+validate()

docs/getting-started/step3.py

+from enoslib.api import generate_inventory, emulate_network, validate_network
+from enoslib.task import enostask
+from enoslib.infra.enos_vagrant.provider import Enos_vagrant
+
+import os
+
+provider_conf = {
+    "backend": "virtualbox",
+    "user": "root",
+    "box": "debian/jessie64",
+    "resources": {
+        "machines": [{
+            "role": "control",
+            "flavor": "tiny",
+            "number": 1,
+            "networks": ["n1", "n2"]
+        },{
+            "role": "compute",
+            "flavor": "tiny",
+            "number": 1,
+            "networks": ["n1", "n3"]
+        }]
+    }
+}
+
+tc = {
+    "enable": True,
+    "default_delay": "20ms",
+    "default_rate": "1gbit",
+}
+
+
+import click
+@click.group()
+def cli():
+    pass
+
+
+@cli.command()
+@click.option("--force",is_flag=True, help="vagrant destroy and up")
+@enostask(new=True)
+def up(force, env=None, **kwargs):
+    """Starts a new experiment using vagrant"""
+    inventory = os.path.join(os.getcwd(), "hosts")
+    provider = Enos_vagrant(provider_conf)
+    roles, networks = provider.init(force_deploy=force)
+    generate_inventory(roles, networks, inventory, check_networks=True)
+    env["roles"] = roles
+    env["networks"] = networks
+    env["inventory"] = inventory
+
+
+@cli.command()
+@enostask()
+def emulate(env=None, **kwargs):
+    """Emulates the network."""
+    inventory = env["inventory"]
+    roles = env["roles"]
+    emulate_network(roles, inventory, tc)
+
+
+@cli.command()
+@enostask()
+def validate(env=None, **kwargs):
+    """Validates the network constraints."""
+    inventory = env["inventory"]
+    roles = env["roles"]
+    validate_network(roles, inventory)
+
+
+if __name__ == '__main__':
+    cli()