--- /dev/null
+Models
+======
+A Juju controller provides websocket endpoints for each of its
+models. In order to do anything useful with a model, the juju lib must
+connect to one of these endpoints. There are several ways to do this.
+
+For api docs, see py:class:`juju.model.Model`.
+
+
+Connecting to the Current Model
+-------------------------------
+Connect to the currently active Juju model (the one returned by
+`juju switch`). This only works if you have the Juju CLI client installed.
+
+.. code:: python
+
+ model = Model()
+ await model.connect()
+
+
+Connecting to a Named Model
+---------------------------
+Connect to a model by name, using the same format as that returned from the
+`juju switch` command. The accepted format is '[controller:][user/]model'.
+This only works if you have the Juju CLI client installed.
+
+.. code:: python
+
+ model = Model()
+ await model.connect('juju-2.0.1:admin/libjuju')
+
+
+Connecting with Authentication
+------------------------------
+You can control what user you are connecting with by specifying either a
+username/password pair, or a macaroon or bakery client that can provide
+a macaroon.
+
+
+.. code:: python
+
+ model = Model()
+ await model.connect(username='admin',
+ password='f53f08cfc32a2e257fe5393271d89d62')
+
+ # or with a macaroon
+ await model.connect(macaroons=[
+ {
+ "Name": "macaroon-218d87053ad19626bcd5a0eef0bc9ba8bd4fbd80a968f52a5fd430b2aa8660df",
+ "Value": "W3siY2F2ZWF0cyI6 ... jBkZiJ9XQ==",
+ "Domain": "10.130.48.27",
+ "Path": "/auth",
+ "Secure": false,
+ "HostOnly": true,
+ "Expires": "2018-03-07T22:07:23Z",
+ },
+ ])
+
+ # or with a bakery client
+ from macaroonbakery.httpbakery import Client
+ from http.cookiejar import FileCookieJar
+
+ bakery_client=Client()
+ bakery_client.cookies = FileCookieJar('cookies.txt')
+ model = Model()
+ await model.connect(bakery_client=bakery_client)
+
+
+
+Connecting with an Explicit Endpoint
+------------------------------------
+The most flexible, but also most verbose, way to connect is using the API
+endpoint url, model UUID, and credentials directly. This method does NOT
+require the Juju CLI client to be installed.
+
+.. code:: python
+
+ from juju.model import Model
+
+ model = Model()
+ await model.connect(
+ endpoint='10.0.4.171:17070',
+ uuid='e8399ac7-078c-4817-8e5e-32316d55b083',
+ username='admin',
+ password='f53f08cfc32a2e257fe5393271d89d62',
+ cacert=None, # Left out for brevity, but if you have a cert string you
+ # should pass it in. You can get the cert from the output
+ # of The `juju show-controller` command.
+ )
+
+
+Creating and Destroying a Model
+-------------------------------
+Example of creating a new model and then destroying it. See
+py:method:`juju.controller.Controller.add_model` and
+py:method:`juju.controller.Controller.destroy_model` for more info.
+
+.. code:: python
+
+ from juju.controller import Controller
+
+ controller = Controller()
+ await controller.connect_current()
+
+ # Create our new model
+ model = await controller.add_model(
+ 'mymodel', # name of your new model
+ )
+
+ # Do stuff with our model...
+
+ # Destroy the model
+ await model.disconnect()
+ await controller.destroy_model(model.info.uuid)
+ model = None
+
+
+Adding Machines and Containers
+------------------------------
+To add a machine or container, connect to a model and then call its
+py:method:`~juju.model.Model.add_machine` method. A
+py: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
+model. The easiest way to do this is by creating a
+py:class:`juju.model.ModelObserver` subclass.
+
+.. code:: python
+
+ from juju.model import Model, ModelObserver
+
+ class MyModelObserver(ModelObserver):
+ async def on_change(self, delta, old, new, model):
+ # The raw change data (dict) from the websocket.
+ print(delta.data)
+
+ # The entity type (str) affected by this change.
+ # One of ('action', 'application', 'annotation', 'machine',
+ # 'unit', 'relation')
+ print(delta.entity)
+
+ # The type (str) of change.
+ # One of ('add', 'change', 'remove')
+ print(delta.type)
+
+ # The 'old' and 'new' parameters are juju.model.ModelEntity
+ # instances which represent an entity in the model both before
+ # this change was applied (old) and after (new).
+
+ # If an entity is being added to the model, the 'old' param
+ # will be None.
+ if delta.type == 'add':
+ assert(old is None)
+
+ # If an entity is being removed from the model, the 'new' param
+ # will be None.
+ if delta.type == 'remove':
+ assert(new is None)
+
+ # The 'old' and 'new' parameters, when not None, will be instances
+ # of a juju.model.ModelEntity subclass. The type of the subclass
+ # depends on the value of 'delta.entity', for example:
+ #
+ # delta.entity type
+ # ------------ ----
+ # 'action' -> juju.action.Action
+ # 'application' -> juju.application.Application
+ # 'annotation' -> juju.annotation.Annotation
+ # 'machine' -> juju.machine.Machine
+ # 'unit' -> juju.unit.Unit
+ # 'relation' -> juju.relation.Relation
+
+ # Finally, the 'model' parameter is a reference to the
+ # juju.model.Model instance to which this observer is attached.
+ print(id(model))
+
+
+ model = Model()
+ await model.connect_current()
+
+ model.add_observer(MyModelObserver())
+
+
+Every change in the model will result in a call to the `on_change()`
+method of your observer(s).
+
+To target your code more precisely, define method names that correspond
+to the entity and type of change that you wish to handle.
+
+.. code:: python
+
+ from juju.model import Model, ModelObserver
+
+ class MyModelObserver(ModelObserver):
+ async def on_application_change(self, delta, old, new, model):
+ # Both 'old' and 'new' params will be instances of
+ # juju.application.Application
+ pass
+
+ async def on_unit_remove(self, delta, old, new, model):
+ # Since a unit is being removed, the 'new' param will always
+ # be None in this handler. The 'old' param will be an instance
+ # of juju.unit.Unit - the state of the unit before it was removed.
+ pass
+
+ async def on_machine_add(self, delta, old, new, model):
+ # Since a machine is being added, the 'old' param will always be
+ # None in this handler. The 'new' param will be an instance of
+ # juju.machine.Machine.
+ pass
+
+ 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 py: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)
projects / osm / N2VC.git / blobdiff