doc: add a tuto about sync_info

changelog.rst

 Changelog
 ===========
 
-6.0.0 (the IPv6 release !)
-----------------------
+6.0.0 (the IPv6 release and plenty other stuffs)
+------------------------------------------------
 
 - Beware this versions has breaking changes in various places
 - Networks from the various providers deserved a true abstraction: it's done.

docs/tutorials/index.rst

@@ -14,6 +14,7 @@ Patterns for the experimenters
     static
     iotlab
     using-tasks
+    sync-info
     docker
     ansible-integration
     network_emulation

docs/tutorials/sync-info.rst

+***************************
+Syncing Hosts' informations
+***************************
+
+.. contents::
+   :depth: 2
+
+Currently syncing the hosts' informations will update all of the Host
+datastructures with some specific data about them (e.g network IPs, processor
+information). This let's the user code to take decisions based on those
+informations.
+
+.. note::
+
+   The synchronisation is based on Ansible facts gathering and it somehow
+   makes the Ansible facts available to the experimenter's python code. It comes
+   at the cost of making a connection to every single host (which can be
+   heavy when managing thousands of hosts).
+
+   Also, in the future, we expect some providers to fill an initial version of
+   the updated attribute to avoid a full sync. For instance, on Grid'5000
+   many informations can be retrieved from the REST API.
+
+
+Examples
+--------
+
+.. literalinclude:: sync-info/tuto_sync_info.py
+   :language: python
+   :linenos:

docs/tutorials/sync-info/tuto_sync_info.py

+from pathlib import Path
+
+import enoslib as en
+
+
+job_name = Path(__file__).name
+
+# claim the resources
+network = en.G5kNetworkConf(
+    id="n1", type="prod", roles=["my_network"], site="rennes"
+)
+
+conf = (
+    en.G5kConf.from_settings(
+        job_type="allow_classic_ssh", job_name=job_name
+    )
+    .add_network_conf(network)
+    .add_machine(
+        roles=["control"], cluster="paravance", nodes=1, primary_network=network
+    )
+    .finalize()
+)
+
+provider = en.G5k(conf)
+roles, networks = provider.init()
+
+roles_synced = en.sync_info(roles, networks)
+
+# some info has been populated
+h = roles_synced["control"][0]
+assert len(h.net_devices) > 0
+assert h.processor is not None
+
+# we can filter addresses based on a given network (one ipv4 address here)
+assert len(h.filter_addresses(networks["my_network"])) >= 1
+
+# add an ipv6 (if not already there)
+en.run_command("dhclient -6 br0", roles=roles)
+
+# resync
+roles_synced = en.sync_info(roles, networks)
+h = roles_synced["control"][0]
+
+# we now have two addresses in the network my_network (one ipv4, one ipv6)
+assert len(h.filter_addresses(networks["my_network"])) == 2
+

enoslib/api.py

@@ -829,7 +829,7 @@ def run_ansible(
 def sync_info(roles: Roles, networks: Networks, **kwargs) -> Roles:
     """Sync each host network information with their actual configuration
 
-    If the command is successful each host extra_devices attribute will be
+    If the command is successful some of the host attributes will be
     populated. This allows to resync the enoslib Host representation with the
     remote configuration.
 
@@ -844,8 +844,9 @@ def sync_info(roles: Roles, networks: Networks, **kwargs) -> Roles:
         kwargs: keyword arguments passed to :py:fun:`enoslib.api.run_ansible`
 
     Returns:
-        A copy of the original roles where each hosts.extra_addresses has
-        been modified."""
+        A copy of the original roles where some new attributes have been
+        populated.
+    """
 
     wait_for(roles, **kwargs)
     tmpdir = os.path.join(os.getcwd(), TMP_DIRNAME)