X-Git-Url: https://osm.etsi.org/gitweb/?a=blobdiff_plain;f=docs%2Fnarrative%2Fmodel.rst;h=57dbc810f07aab33b339f418b05d6b2a57ea4b80;hb=adc6e51ff00d513cd68d4a046e87b25adf2021be;hp=036f43faa9a11572f66245acbb4b23d254b07d92;hpb=19077c2754a4296a87a80679e876e67cfed57c5c;p=osm%2FN2VC.git

diff --git a/docs/narrative/model.rst b/docs/narrative/model.rst
index 036f43f..57dbc81 100644
--- a/docs/narrative/model.rst
+++ b/docs/narrative/model.rst
@@ -131,6 +131,63 @@ Example of creating a new model and then destroying it. See
   model = None
 
 
+Adding Machines and Containers
+------------------------------
+To add a machine or container, connect to a model and then call its
+:meth:`~juju.model.Model.add_machine` method. A
+:class:`~juju.machine.Machine` instance is returned. The machine id
+can be used to deploy a charm to a specific machine or container.
+
+.. code:: python
+
+  from juju.model import Model
+
+  MB = 1
+  GB = 1024
+
+
+  model = Model()
+  await model.connect_current()
+
+  # add a new default machine
+  machine1 = await model.add_machine()
+
+  # add a machine with constraints, disks, and series specified
+  machine2 = await model.add_machine(
+      constraints={
+          'mem': 256 * MB,
+      },
+      disks=[{
+          'pool': 'rootfs',
+          'size': 10 * GB,
+          'count': 1,
+      }],
+      series='xenial',
+  )
+
+  # add a lxd container to machine2
+  machine3 = await model.add_machine(
+      'lxd:{}'.format(machine2.id))
+
+  # deploy charm to the lxd container
+  application = await model.deploy(
+      'ubuntu-10',
+      application_name='ubuntu',
+      series='xenial',
+      channel='stable',
+      to=machine3.id
+  )
+
+  # remove application
+  await application.remove()
+
+  # destroy machines - note that machine3 must be destroyed before machine2
+  # since it's a container on machine2
+  await machine3.destroy(force=True)
+  await machine2.destroy(force=True)
+  await machine1.destroy(force=True)
+
+
 Reacting to Changes in a Model
 ------------------------------
 To watch for and respond to changes in a model, register an observer with the
@@ -224,3 +281,26 @@ to the entity and type of change that you wish to handle.
       async def on_change(self, delta, old, new, model):
           # The catch-all handler - will be called whenever a more
           # specific handler method is not defined.
+
+
+Any :class:`juju.model.ModelEntity` object can be observed directly by
+registering callbacks on the object itself.
+
+.. code:: python
+
+  import logging
+
+  async def on_app_change(delta, old, new, model):
+      logging.debug('App changed: %r', new)
+
+  async def on_app_remove(delta, old, new, model):
+      logging.debug('App removed: %r', old)
+
+  ubuntu_app = await model.deploy(
+      'ubuntu',
+      application_name='ubuntu',
+      series='trusty',
+      channel='stable',
+  )
+  ubuntu_app.on_change(on_app_change)
+  ubuntu_app.on_remove(on_app_remove)