juju/model.py

   1 import asyncio
   2 import collections
   3 import json
   4 import logging
   5 import os
   6 import re
   7 import stat
   8 import tempfile
   9 import weakref
  10 import zipfile
  11 from concurrent.futures import CancelledError
  12 from functools import partial
  13 from pathlib import Path
  14
  15 import yaml
  16 from theblues import charmstore
  17
  18 from .client import client
  19 from .client import watcher
  20 from .client import connection
  21 from .constraints import parse as parse_constraints, normalize_key
  22 from .delta import get_entity_delta
  23 from .delta import get_entity_class
  24 from .exceptions import DeadEntityException
  25 from .errors import JujuError, JujuAPIError
  26
  27 log = logging.getLogger(__name__)
  28
  29
  30 class _Observer(object):
  31     """Wrapper around an observer callable.
  32
  33     This wrapper allows filter criteria to be associated with the
  34     callable so that it's only called for changes that meet the criteria.
  35
  36     """
  37     def __init__(self, callable_, entity_type, action, entity_id, predicate):
  38         self.callable_ = callable_
  39         self.entity_type = entity_type
  40         self.action = action
  41         self.entity_id = entity_id
  42         self.predicate = predicate
  43         if self.entity_id:
  44             self.entity_id = str(self.entity_id)
  45             if not self.entity_id.startswith('^'):
  46                 self.entity_id = '^' + self.entity_id
  47             if not self.entity_id.endswith('$'):
  48                 self.entity_id += '$'
  49
  50     async def __call__(self, delta, old, new, model):
  51         await self.callable_(delta, old, new, model)
  52
  53     def cares_about(self, delta):
  54         """Return True if this observer "cares about" (i.e. wants to be
  55         called) for a this delta.
  56
  57         """
  58         if (self.entity_id and delta.get_id() and
  59                 not re.match(self.entity_id, str(delta.get_id()))):
  60             return False
  61
  62         if self.entity_type and self.entity_type != delta.entity:
  63             return False
  64
  65         if self.action and self.action != delta.type:
  66             return False
  67
  68         if self.predicate and not self.predicate(delta):
  69             return False
  70
  71         return True
  72
  73
  74 class ModelObserver(object):
  75     async def __call__(self, delta, old, new, model):
  76         handler_name = 'on_{}_{}'.format(delta.entity, delta.type)
  77         method = getattr(self, handler_name, self.on_change)
  78         await method(delta, old, new, model)
  79
  80     async def on_change(self, delta, old, new, model):
  81         """Generic model-change handler.
  82
  83         :param delta: :class:`juju.client.overrides.Delta`
  84         :param old: :class:`juju.model.ModelEntity`
  85         :param new: :class:`juju.model.ModelEntity`
  86         :param model: :class:`juju.model.Model`
  87
  88         """
  89         pass
  90
  91
  92 class ModelState(object):
  93     """Holds the state of the model, including the delta history of all
  94     entities in the model.
  95
  96     """
  97     def __init__(self, model):
  98         self.model = model
  99         self.state = dict()
 100
 101     def _live_entity_map(self, entity_type):
 102         """Return an id:Entity map of all the living entities of
 103         type ``entity_type``.
 104
 105         """
 106         return {
 107             entity_id: self.get_entity(entity_type, entity_id)
 108             for entity_id, history in self.state.get(entity_type, {}).items()
 109             if history[-1] is not None
 110         }
 111
 112     @property
 113     def applications(self):
 114         """Return a map of application-name:Application for all applications
 115         currently in the model.
 116
 117         """
 118         return self._live_entity_map('application')
 119
 120     @property
 121     def machines(self):
 122         """Return a map of machine-id:Machine for all machines currently in
 123         the model.
 124
 125         """
 126         return self._live_entity_map('machine')
 127
 128     @property
 129     def units(self):
 130         """Return a map of unit-id:Unit for all units currently in
 131         the model.
 132
 133         """
 134         return self._live_entity_map('unit')
 135
 136     def entity_history(self, entity_type, entity_id):
 137         """Return the history deque for an entity.
 138
 139         """
 140         return self.state[entity_type][entity_id]
 141
 142     def entity_data(self, entity_type, entity_id, history_index):
 143         """Return the data dict for an entity at a specific index of its
 144         history.
 145
 146         """
 147         return self.entity_history(entity_type, entity_id)[history_index]
 148
 149     def apply_delta(self, delta):
 150         """Apply delta to our state and return a copy of the
 151         affected object as it was before and after the update, e.g.:
 152
 153             old_obj, new_obj = self.apply_delta(delta)
 154
 155         old_obj may be None if the delta is for the creation of a new object,
 156         e.g. a new application or unit is deployed.
 157
 158         new_obj will never be None, but may be dead (new_obj.dead == True)
 159         if the object was deleted as a result of the delta being applied.
 160
 161         """
 162         history = (
 163             self.state
 164             .setdefault(delta.entity, {})
 165             .setdefault(delta.get_id(), collections.deque())
 166         )
 167
 168         history.append(delta.data)
 169         if delta.type == 'remove':
 170             history.append(None)
 171
 172         entity = self.get_entity(delta.entity, delta.get_id())
 173         return entity.previous(), entity
 174
 175     def get_entity(
 176             self, entity_type, entity_id, history_index=-1, connected=True):
 177         """Return an object instance for the given entity_type and id.
 178
 179         By default the object state matches the most recent state from
 180         Juju. To get an instance of the object in an older state, pass
 181         history_index, an index into the history deque for the entity.
 182
 183         """
 184
 185         if history_index < 0 and history_index != -1:
 186             history_index += len(self.entity_history(entity_type, entity_id))
 187             if history_index < 0:
 188                 return None
 189
 190         try:
 191             self.entity_data(entity_type, entity_id, history_index)
 192         except IndexError:
 193             return None
 194
 195         entity_class = get_entity_class(entity_type)
 196         return entity_class(
 197             entity_id, self.model, history_index=history_index,
 198             connected=connected)
 199
 200
 201 class ModelEntity(object):
 202     """An object in the Model tree"""
 203
 204     def __init__(self, entity_id, model, history_index=-1, connected=True):
 205         """Initialize a new entity
 206
 207         :param entity_id str: The unique id of the object in the model
 208         :param model: The model instance in whose object tree this
 209             entity resides
 210         :history_index int: The index of this object's state in the model's
 211             history deque for this entity
 212         :connected bool: Flag indicating whether this object gets live updates
 213             from the model.
 214
 215         """
 216         self.entity_id = entity_id
 217         self.model = model
 218         self._history_index = history_index
 219         self.connected = connected
 220         self.connection = model.connection
 221
 222     def __repr__(self):
 223         return '<{} entity_id="{}">'.format(type(self).__name__,
 224                                             self.entity_id)
 225
 226     def __getattr__(self, name):
 227         """Fetch object attributes from the underlying data dict held in the
 228         model.
 229
 230         """
 231         return self.safe_data[name]
 232
 233     def __bool__(self):
 234         return bool(self.data)
 235
 236     def on_change(self, callable_):
 237         """Add a change observer to this entity.
 238
 239         """
 240         self.model.add_observer(
 241             callable_, self.entity_type, 'change', self.entity_id)
 242
 243     def on_remove(self, callable_):
 244         """Add a remove observer to this entity.
 245
 246         """
 247         self.model.add_observer(
 248             callable_, self.entity_type, 'remove', self.entity_id)
 249
 250     @property
 251     def entity_type(self):
 252         """A string identifying the entity type of this object, e.g.
 253         'application' or 'unit', etc.
 254
 255         """
 256         return self.__class__.__name__.lower()
 257
 258     @property
 259     def current(self):
 260         """Return True if this object represents the current state of the
 261         entity in the underlying model.
 262
 263         This will be True except when the object represents an entity at a
 264         non-latest state in history, e.g. if the object was obtained by calling
 265         .previous() on another object.
 266
 267         """
 268         return self._history_index == -1
 269
 270     @property
 271     def dead(self):
 272         """Returns True if this entity no longer exists in the underlying
 273         model.
 274
 275         """
 276         return (
 277             self.data is None or
 278             self.model.state.entity_data(
 279                 self.entity_type, self.entity_id, -1) is None
 280         )
 281
 282     @property
 283     def alive(self):
 284         """Returns True if this entity still exists in the underlying
 285         model.
 286
 287         """
 288         return not self.dead
 289
 290     @property
 291     def data(self):
 292         """The data dictionary for this entity.
 293
 294         """
 295         return self.model.state.entity_data(
 296             self.entity_type, self.entity_id, self._history_index)
 297
 298     @property
 299     def safe_data(self):
 300         """The data dictionary for this entity.
 301
 302         If this `ModelEntity` points to the dead state, it will
 303         raise `DeadEntityException`.
 304
 305         """
 306         if self.data is None:
 307             raise DeadEntityException(
 308                 "Entity {}:{} is dead - its attributes can no longer be "
 309                 "accessed. Use the .previous() method on this object to get "
 310                 "a copy of the object at its previous state.".format(
 311                     self.entity_type, self.entity_id))
 312         return self.data
 313
 314     def previous(self):
 315         """Return a copy of this object as was at its previous state in
 316         history.
 317
 318         Returns None if this object is new (and therefore has no history).
 319
 320         The returned object is always "disconnected", i.e. does not receive
 321         live updates.
 322
 323         """
 324         return self.model.state.get_entity(
 325             self.entity_type, self.entity_id, self._history_index - 1,
 326             connected=False)
 327
 328     def next(self):
 329         """Return a copy of this object at its next state in
 330         history.
 331
 332         Returns None if this object is already the latest.
 333
 334         The returned object is "disconnected", i.e. does not receive
 335         live updates, unless it is current (latest).
 336
 337         """
 338         if self._history_index == -1:
 339             return None
 340
 341         new_index = self._history_index + 1
 342         connected = (
 343             new_index == len(self.model.state.entity_history(
 344                 self.entity_type, self.entity_id)) - 1
 345         )
 346         return self.model.state.get_entity(
 347             self.entity_type, self.entity_id, self._history_index - 1,
 348             connected=connected)
 349
 350     def latest(self):
 351         """Return a copy of this object at its current state in the model.
 352
 353         Returns self if this object is already the latest.
 354
 355         The returned object is always "connected", i.e. receives
 356         live updates from the model.
 357
 358         """
 359         if self._history_index == -1:
 360             return self
 361
 362         return self.model.state.get_entity(self.entity_type, self.entity_id)
 363
 364
 365 class Model(object):
 366     def __init__(self, loop=None):
 367         """Instantiate a new connected Model.
 368
 369         :param loop: an asyncio event loop
 370
 371         """
 372         self.loop = loop or asyncio.get_event_loop()
 373         self.connection = None
 374         self.observers = weakref.WeakValueDictionary()
 375         self.state = ModelState(self)
 376         self.info = None
 377         self._watcher_task = None
 378         self._watch_shutdown = asyncio.Event(loop=loop)
 379         self._watch_received = asyncio.Event(loop=loop)
 380         self._charmstore = CharmStore(self.loop)
 381
 382     async def connect(self, *args, **kw):
 383         """Connect to an arbitrary Juju model.
 384
 385         args and kw are passed through to Connection.connect()
 386
 387         """
 388         self.connection = await connection.Connection.connect(*args, **kw)
 389         await self._after_connect()
 390
 391     async def connect_current(self):
 392         """Connect to the current Juju model.
 393
 394         """
 395         self.connection = await connection.Connection.connect_current()
 396         await self._after_connect()
 397
 398     async def connect_model(self, model_name):
 399         """Connect to a specific Juju model by name.
 400
 401         :param model_name:  Format [controller:][user/]model
 402
 403         """
 404         self.connection = await connection.Connection.connect_model(model_name)
 405         await self._after_connect()
 406
 407     async def _after_connect(self):
 408         """Run initialization steps after connecting to websocket.
 409
 410         """
 411         self._watch()
 412         await self._watch_received.wait()
 413         await self.get_info()
 414
 415     async def disconnect(self):
 416         """Shut down the watcher task and close websockets.
 417
 418         """
 419         self._stop_watching()
 420         if self.connection and self.connection.is_open:
 421             await self._watch_shutdown.wait()
 422             log.debug('Closing model connection')
 423             await self.connection.close()
 424             self.connection = None
 425
 426     async def add_local_charm_dir(self, charm_dir, series):
 427         """Upload a local charm to the model.
 428
 429         This will automatically generate an archive from
 430         the charm dir.
 431
 432         :param charm_dir: Path to the charm directory
 433         :param series: Charm series
 434
 435         """
 436         fh = tempfile.NamedTemporaryFile()
 437         CharmArchiveGenerator(charm_dir).make_archive(fh.name)
 438         with fh:
 439             func = partial(
 440                 self.add_local_charm, fh, series, os.stat(fh.name).st_size)
 441             charm_url = await self.loop.run_in_executor(None, func)
 442
 443         log.debug('Uploaded local charm: %s -> %s', charm_dir, charm_url)
 444         return charm_url
 445
 446     def add_local_charm(self, charm_file, series, size=None):
 447         """Upload a local charm archive to the model.
 448
 449         Returns the 'local:...' url that should be used to deploy the charm.
 450
 451         :param charm_file: Path to charm zip archive
 452         :param series: Charm series
 453         :param size: Size of the archive, in bytes
 454         :return str: 'local:...' url for deploying the charm
 455         :raises: :class:`JujuError` if the upload fails
 456
 457         Uses an https endpoint at the same host:port as the wss.
 458         Supports large file uploads.
 459
 460         .. warning::
 461
 462            This method will block. Consider using :meth:`add_local_charm_dir`
 463            instead.
 464
 465         """
 466         conn, headers, path_prefix = self.connection.https_connection()
 467         path = "%s/charms?series=%s" % (path_prefix, series)
 468         headers['Content-Type'] = 'application/zip'
 469         if size:
 470             headers['Content-Length'] = size
 471         conn.request("POST", path, charm_file, headers)
 472         response = conn.getresponse()
 473         result = response.read().decode()
 474         if not response.status == 200:
 475             raise JujuError(result)
 476         result = json.loads(result)
 477         return result['charm-url']
 478
 479     def all_units_idle(self):
 480         """Return True if all units are idle.
 481
 482         """
 483         for unit in self.units.values():
 484             unit_status = unit.data['agent-status']['current']
 485             if unit_status != 'idle':
 486                 return False
 487         return True
 488
 489     async def reset(self, force=False):
 490         """Reset the model to a clean state.
 491
 492         :param bool force: Force-terminate machines.
 493
 494         This returns only after the model has reached a clean state. "Clean"
 495         means no applications or machines exist in the model.
 496
 497         """
 498         log.debug('Resetting model')
 499         for app in self.applications.values():
 500             await app.destroy()
 501         for machine in self.machines.values():
 502             await machine.destroy(force=force)
 503         await self.block_until(
 504             lambda: len(self.machines) == 0
 505         )
 506
 507     async def block_until(self, *conditions, timeout=None, wait_period=0.5):
 508         """Return only after all conditions are true.
 509
 510         """
 511         async def _block():
 512             while not all(c() for c in conditions):
 513                 await asyncio.sleep(wait_period)
 514         await asyncio.wait_for(_block(), timeout)
 515
 516     @property
 517     def applications(self):
 518         """Return a map of application-name:Application for all applications
 519         currently in the model.
 520
 521         """
 522         return self.state.applications
 523
 524     @property
 525     def machines(self):
 526         """Return a map of machine-id:Machine for all machines currently in
 527         the model.
 528
 529         """
 530         return self.state.machines
 531
 532     @property
 533     def units(self):
 534         """Return a map of unit-id:Unit for all units currently in
 535         the model.
 536
 537         """
 538         return self.state.units
 539
 540     async def get_info(self):
 541         """Return a client.ModelInfo object for this Model.
 542
 543         Retrieves latest info for this Model from the api server. The
 544         return value is cached on the Model.info attribute so that the
 545         valued may be accessed again without another api call, if
 546         desired.
 547
 548         This method is called automatically when the Model is connected,
 549         resulting in Model.info being initialized without requiring an
 550         explicit call to this method.
 551
 552         """
 553         facade = client.ClientFacade()
 554         facade.connect(self.connection)
 555
 556         self.info = await facade.ModelInfo()
 557         log.debug('Got ModelInfo: %s', vars(self.info))
 558
 559         return self.info
 560
 561     def add_observer(
 562             self, callable_, entity_type=None, action=None, entity_id=None,
 563             predicate=None):
 564         """Register an "on-model-change" callback
 565
 566         Once the model is connected, ``callable_``
 567         will be called each time the model changes. ``callable_`` should
 568         be Awaitable and accept the following positional arguments:
 569
 570             delta - An instance of :class:`juju.delta.EntityDelta`
 571                 containing the raw delta data recv'd from the Juju
 572                 websocket.
 573
 574             old_obj - If the delta modifies an existing object in the model,
 575                 old_obj will be a copy of that object, as it was before the
 576                 delta was applied. Will be None if the delta creates a new
 577                 entity in the model.
 578
 579             new_obj - A copy of the new or updated object, after the delta
 580                 is applied. Will be None if the delta removes an entity
 581                 from the model.
 582
 583             model - The :class:`Model` itself.
 584
 585         Events for which ``callable_`` is called can be specified by passing
 586         entity_type, action, and/or entitiy_id filter criteria, e.g.::
 587
 588             add_observer(
 589                 myfunc,
 590                 entity_type='application', action='add', entity_id='ubuntu')
 591
 592         For more complex filtering conditions, pass a predicate function. It
 593         will be called with a delta as its only argument. If the predicate
 594         function returns True, the ``callable_`` will be called.
 595
 596         """
 597         observer = _Observer(
 598             callable_, entity_type, action, entity_id, predicate)
 599         self.observers[observer] = callable_
 600
 601     def _watch(self):
 602         """Start an asynchronous watch against this model.
 603
 604         See :meth:`add_observer` to register an onchange callback.
 605
 606         """
 607         async def _start_watch():
 608             self._watch_shutdown.clear()
 609             try:
 610                 allwatcher = watcher.AllWatcher()
 611                 self._watch_conn = await self.connection.clone()
 612                 allwatcher.connect(self._watch_conn)
 613                 while True:
 614                     results = await allwatcher.Next()
 615                     for delta in results.deltas:
 616                         delta = get_entity_delta(delta)
 617                         old_obj, new_obj = self.state.apply_delta(delta)
 618                         # XXX: Might not want to shield at this level
 619                         # We are shielding because when the watcher is
 620                         # canceled (on disconnect()), we don't want all of
 621                         # its children (every observer callback) to be
 622                         # canceled with it. So we shield them. But this means
 623                         # they can *never* be canceled.
 624                         await asyncio.shield(
 625                             self._notify_observers(delta, old_obj, new_obj))
 626                     self._watch_received.set()
 627             except CancelledError:
 628                 log.debug('Closing watcher connection')
 629                 await self._watch_conn.close()
 630                 self._watch_shutdown.set()
 631                 self._watch_conn = None
 632
 633         log.debug('Starting watcher task')
 634         self._watcher_task = self.loop.create_task(_start_watch())
 635
 636     def _stop_watching(self):
 637         """Stop the asynchronous watch against this model.
 638
 639         """
 640         log.debug('Stopping watcher task')
 641         if self._watcher_task:
 642             self._watcher_task.cancel()
 643
 644     async def _notify_observers(self, delta, old_obj, new_obj):
 645         """Call observing callbacks, notifying them of a change in model state
 646
 647         :param delta: The raw change from the watcher
 648             (:class:`juju.client.overrides.Delta`)
 649         :param old_obj: The object in the model that this delta updates.
 650             May be None.
 651         :param new_obj: The object in the model that is created or updated
 652             by applying this delta.
 653
 654         """
 655         if new_obj and not old_obj:
 656             delta.type = 'add'
 657
 658         log.debug(
 659             'Model changed: %s %s %s',
 660             delta.entity, delta.type, delta.get_id())
 661
 662         for o in self.observers:
 663             if o.cares_about(delta):
 664                 asyncio.ensure_future(o(delta, old_obj, new_obj, self))
 665
 666     async def _wait(self, entity_type, entity_id, action, predicate=None):
 667         """
 668         Block the calling routine until a given action has happened to the
 669         given entity
 670
 671         :param entity_type: The entity's type.
 672         :param entity_id: The entity's id.
 673         :param action: the type of action (e.g., 'add' or 'change')
 674         :param predicate: optional callable that must take as an
 675             argument a delta, and must return a boolean, indicating
 676             whether the delta contains the specific action we're looking
 677             for. For example, you might check to see whether a 'change'
 678             has a 'completed' status. See the _Observer class for details.
 679
 680         """
 681         q = asyncio.Queue(loop=self.loop)
 682
 683         async def callback(delta, old, new, model):
 684             await q.put(delta.get_id())
 685
 686         self.add_observer(callback, entity_type, action, entity_id, predicate)
 687         entity_id = await q.get()
 688         return self.state._live_entity_map(entity_type)[entity_id]
 689
 690     async def _wait_for_new(self, entity_type, entity_id=None, predicate=None):
 691         """Wait for a new object to appear in the Model and return it.
 692
 693         Waits for an object of type ``entity_type`` with id ``entity_id``.
 694         If ``entity_id`` is ``None``, it will wait for the first new entity
 695         of the correct type.
 696
 697         This coroutine blocks until the new object appears in the model.
 698
 699         """
 700         # if the entity is already in the model, just return it
 701         if entity_id in self.state._live_entity_map(entity_type):
 702             return self.state._live_entity_map(entity_type)[entity_id]
 703         # if we know the entity_id, we can trigger on any action that puts
 704         # the enitty into the model; otherwise, we have to watch for the
 705         # next "add" action on that entity_type
 706         action = 'add' if entity_id is None else None
 707         return await self._wait(entity_type, entity_id, action, predicate)
 708
 709     async def wait_for_action(self, action_id):
 710         """Given an action, wait for it to complete."""
 711
 712         if action_id.startswith("action-"):
 713             # if we've been passed action.tag, transform it into the
 714             # id that the api deltas will use.
 715             action_id = action_id[7:]
 716
 717         def predicate(delta):
 718             return delta.data['status'] in ('completed', 'failed')
 719
 720         return await self._wait('action', action_id, 'change', predicate)
 721
 722     def add_machine(
 723             self, spec=None, constraints=None, disks=None, series=None,
 724             count=1):
 725         """Start a new, empty machine and optionally a container, or add a
 726         container to a machine.
 727
 728         :param str spec: Machine specification
 729             Examples::
 730
 731                 (None) - starts a new machine
 732                 'lxc' - starts a new machine with on lxc container
 733                 'lxc:4' - starts a new lxc container on machine 4
 734                 'ssh:user@10.10.0.3' - manually provisions a machine with ssh
 735                 'zone=us-east-1a' - starts a machine in zone us-east-1s on AWS
 736                 'maas2.name' - acquire machine maas2.name on MAAS
 737         :param constraints: Machine constraints
 738         :type constraints: :class:`juju.Constraints`
 739         :param list disks: List of disk :class:`constraints <juju.Constraints>`
 740         :param str series: Series
 741         :param int count: Number of machines to deploy
 742
 743         Supported container types are: lxc, lxd, kvm
 744
 745         When deploying a container to an existing machine, constraints cannot
 746         be used.
 747
 748         """
 749         pass
 750     add_machines = add_machine
 751
 752     async def add_relation(self, relation1, relation2):
 753         """Add a relation between two applications.
 754
 755         :param str relation1: '<application>[:<relation_name>]'
 756         :param str relation2: '<application>[:<relation_name>]'
 757
 758         """
 759         app_facade = client.ApplicationFacade()
 760         app_facade.connect(self.connection)
 761
 762         log.debug(
 763             'Adding relation %s <-> %s', relation1, relation2)
 764
 765         try:
 766             result = await app_facade.AddRelation([relation1, relation2])
 767         except JujuAPIError as e:
 768             if 'relation already exists' not in e.message:
 769                 raise
 770             log.debug(
 771                 'Relation %s <-> %s already exists', relation1, relation2)
 772             # TODO: if relation already exists we should return the
 773             # Relation ModelEntity here
 774             return None
 775
 776         def predicate(delta):
 777             endpoints = {}
 778             for endpoint in delta.data['endpoints']:
 779                 endpoints[endpoint['application-name']] = endpoint['relation']
 780             return endpoints == result.endpoints
 781
 782         return await self._wait_for_new('relation', None, predicate)
 783
 784     def add_space(self, name, *cidrs):
 785         """Add a new network space.
 786
 787         Adds a new space with the given name and associates the given
 788         (optional) list of existing subnet CIDRs with it.
 789
 790         :param str name: Name of the space
 791         :param \*cidrs: Optional list of existing subnet CIDRs
 792
 793         """
 794         pass
 795
 796     def add_ssh_key(self, key):
 797         """Add a public SSH key to this model.
 798
 799         :param str key: The public ssh key
 800
 801         """
 802         pass
 803     add_ssh_keys = add_ssh_key
 804
 805     def add_subnet(self, cidr_or_id, space, *zones):
 806         """Add an existing subnet to this model.
 807
 808         :param str cidr_or_id: CIDR or provider ID of the existing subnet
 809         :param str space: Network space with which to associate
 810         :param str \*zones: Zone(s) in which the subnet resides
 811
 812         """
 813         pass
 814
 815     def get_backups(self):
 816         """Retrieve metadata for backups in this model.
 817
 818         """
 819         pass
 820
 821     def block(self, *commands):
 822         """Add a new block to this model.
 823
 824         :param str \*commands: The commands to block. Valid values are
 825             'all-changes', 'destroy-model', 'remove-object'
 826
 827         """
 828         pass
 829
 830     def get_blocks(self):
 831         """List blocks for this model.
 832
 833         """
 834         pass
 835
 836     def get_cached_images(self, arch=None, kind=None, series=None):
 837         """Return a list of cached OS images.
 838
 839         :param str arch: Filter by image architecture
 840         :param str kind: Filter by image kind, e.g. 'lxd'
 841         :param str series: Filter by image series, e.g. 'xenial'
 842
 843         """
 844         pass
 845
 846     def create_backup(self, note=None, no_download=False):
 847         """Create a backup of this model.
 848
 849         :param str note: A note to store with the backup
 850         :param bool no_download: Do not download the backup archive
 851         :return str: Path to downloaded archive
 852
 853         """
 854         pass
 855
 856     def create_storage_pool(self, name, provider_type, **pool_config):
 857         """Create or define a storage pool.
 858
 859         :param str name: Name to give the storage pool
 860         :param str provider_type: Pool provider type
 861         :param \*\*pool_config: key/value pool configuration pairs
 862
 863         """
 864         pass
 865
 866     def debug_log(
 867             self, no_tail=False, exclude_module=None, include_module=None,
 868             include=None, level=None, limit=0, lines=10, replay=False,
 869             exclude=None):
 870         """Get log messages for this model.
 871
 872         :param bool no_tail: Stop after returning existing log messages
 873         :param list exclude_module: Do not show log messages for these logging
 874             modules
 875         :param list include_module: Only show log messages for these logging
 876             modules
 877         :param list include: Only show log messages for these entities
 878         :param str level: Log level to show, valid options are 'TRACE',
 879             'DEBUG', 'INFO', 'WARNING', 'ERROR,
 880         :param int limit: Return this many of the most recent (possibly
 881             filtered) lines are shown
 882         :param int lines: Yield this many of the most recent lines, and keep
 883             yielding
 884         :param bool replay: Yield the entire log, and keep yielding
 885         :param list exclude: Do not show log messages for these entities
 886
 887         """
 888         pass
 889
 890     async def deploy(
 891             self, entity_url, application_name=None, bind=None, budget=None,
 892             channel=None, config=None, constraints=None, force=False,
 893             num_units=1, plan=None, resources=None, series=None, storage=None,
 894             to=None):
 895         """Deploy a new service or bundle.
 896
 897         :param str entity_url: Charm or bundle url
 898         :param str application_name: Name to give the service
 899         :param dict bind: <charm endpoint>:<network space> pairs
 900         :param dict budget: <budget name>:<limit> pairs
 901         :param str channel: Charm store channel from which to retrieve
 902             the charm or bundle, e.g. 'development'
 903         :param dict config: Charm configuration dictionary
 904         :param constraints: Service constraints
 905         :type constraints: :class:`juju.Constraints`
 906         :param bool force: Allow charm to be deployed to a machine running
 907             an unsupported series
 908         :param int num_units: Number of units to deploy
 909         :param str plan: Plan under which to deploy charm
 910         :param dict resources: <resource name>:<file path> pairs
 911         :param str series: Series on which to deploy
 912         :param dict storage: Storage constraints TODO how do these look?
 913         :param str to: Placement directive, e.g.::
 914
 915             '23' - machine 23
 916             'lxc:7' - new lxc container on machine 7
 917             '24/lxc/3' - lxc container 3 or machine 24
 918
 919             If None, a new machine is provisioned.
 920
 921
 922         TODO::
 923
 924             - application_name is required; fill this in automatically if not
 925               provided by caller
 926             - series is required; how do we pick a default?
 927
 928         """
 929         if to:
 930             placement = [
 931                 client.Placement(**p) for p in to
 932             ]
 933         else:
 934             placement = []
 935
 936         if storage:
 937             storage = {
 938                 k: client.Constraints(**v)
 939                 for k, v in storage.items()
 940             }
 941
 942         is_local = (
 943             entity_url.startswith('local:') or
 944             os.path.isdir(entity_url)
 945         )
 946         entity_id = await self.charmstore.entityId(entity_url) \
 947             if not is_local else entity_url
 948
 949         app_facade = client.ApplicationFacade()
 950         client_facade = client.ClientFacade()
 951         app_facade.connect(self.connection)
 952         client_facade.connect(self.connection)
 953
 954         is_bundle = ((is_local and
 955                       (Path(entity_id) / 'bundle.yaml').exists()) or
 956                      (not is_local and 'bundle/' in entity_id))
 957
 958         if is_bundle:
 959             handler = BundleHandler(self)
 960             await handler.fetch_plan(entity_id)
 961             await handler.execute_plan()
 962             extant_apps = {app for app in self.applications}
 963             pending_apps = set(handler.applications) - extant_apps
 964             if pending_apps:
 965                 # new apps will usually be in the model by now, but if some
 966                 # haven't made it yet we'll need to wait on them to be added
 967                 await asyncio.gather(*[
 968                     asyncio.ensure_future(
 969                         self._wait_for_new('application', app_name))
 970                     for app_name in pending_apps
 971                 ])
 972             return [app for name, app in self.applications.items()
 973                     if name in handler.applications]
 974         else:
 975             log.debug(
 976                 'Deploying %s', entity_id)
 977
 978             if not is_local:
 979                 await client_facade.AddCharm(channel, entity_id)
 980             app = client.ApplicationDeploy(
 981                 application=application_name,
 982                 channel=channel,
 983                 charm_url=entity_id,
 984                 config=config,
 985                 constraints=parse_constraints(constraints),
 986                 endpoint_bindings=bind,
 987                 num_units=num_units,
 988                 placement=placement,
 989                 resources=resources,
 990                 series=series,
 991                 storage=storage,
 992             )
 993
 994             result = await app_facade.Deploy([app])
 995             errors = [r.error.message for r in result.results if r.error]
 996             if errors:
 997                 raise JujuError('\n'.join(errors))
 998             return await self._wait_for_new('application', application_name)
 999
1000     def destroy(self):
1001         """Terminate all machines and resources for this model.
1002
1003         """
1004         pass
1005
1006     async def destroy_unit(self, *unit_names):
1007         """Destroy units by name.
1008
1009         """
1010         app_facade = client.ApplicationFacade()
1011         app_facade.connect(self.connection)
1012
1013         log.debug(
1014             'Destroying unit%s %s',
1015             's' if len(unit_names) == 1 else '',
1016             ' '.join(unit_names))
1017
1018         return await app_facade.DestroyUnits(list(unit_names))
1019     destroy_units = destroy_unit
1020
1021     def get_backup(self, archive_id):
1022         """Download a backup archive file.
1023
1024         :param str archive_id: The id of the archive to download
1025         :return str: Path to the archive file
1026
1027         """
1028         pass
1029
1030     def enable_ha(
1031             self, num_controllers=0, constraints=None, series=None, to=None):
1032         """Ensure sufficient controllers exist to provide redundancy.
1033
1034         :param int num_controllers: Number of controllers to make available
1035         :param constraints: Constraints to apply to the controller machines
1036         :type constraints: :class:`juju.Constraints`
1037         :param str series: Series of the controller machines
1038         :param list to: Placement directives for controller machines, e.g.::
1039
1040             '23' - machine 23
1041             'lxc:7' - new lxc container on machine 7
1042             '24/lxc/3' - lxc container 3 or machine 24
1043
1044             If None, a new machine is provisioned.
1045
1046         """
1047         pass
1048
1049     def get_config(self):
1050         """Return the configuration settings for this model.
1051
1052         """
1053         pass
1054
1055     def get_constraints(self):
1056         """Return the machine constraints for this model.
1057
1058         """
1059         pass
1060
1061     def grant(self, username, acl='read'):
1062         """Grant a user access to this model.
1063
1064         :param str username: Username
1065         :param str acl: Access control ('read' or 'write')
1066
1067         """
1068         pass
1069
1070     def import_ssh_key(self, identity):
1071         """Add a public SSH key from a trusted indentity source to this model.
1072
1073         :param str identity: User identity in the form <lp|gh>:<username>
1074
1075         """
1076         pass
1077     import_ssh_keys = import_ssh_key
1078
1079     def get_machines(self, machine, utc=False):
1080         """Return list of machines in this model.
1081
1082         :param str machine: Machine id, e.g. '0'
1083         :param bool utc: Display time as UTC in RFC3339 format
1084
1085         """
1086         pass
1087
1088     def get_shares(self):
1089         """Return list of all users with access to this model.
1090
1091         """
1092         pass
1093
1094     def get_spaces(self):
1095         """Return list of all known spaces, including associated subnets.
1096
1097         """
1098         pass
1099
1100     def get_ssh_key(self):
1101         """Return known SSH keys for this model.
1102
1103         """
1104         pass
1105     get_ssh_keys = get_ssh_key
1106
1107     def get_storage(self, filesystem=False, volume=False):
1108         """Return details of storage instances.
1109
1110         :param bool filesystem: Include filesystem storage
1111         :param bool volume: Include volume storage
1112
1113         """
1114         pass
1115
1116     def get_storage_pools(self, names=None, providers=None):
1117         """Return list of storage pools.
1118
1119         :param list names: Only include pools with these names
1120         :param list providers: Only include pools for these providers
1121
1122         """
1123         pass
1124
1125     def get_subnets(self, space=None, zone=None):
1126         """Return list of known subnets.
1127
1128         :param str space: Only include subnets in this space
1129         :param str zone: Only include subnets in this zone
1130
1131         """
1132         pass
1133
1134     def remove_blocks(self):
1135         """Remove all blocks from this model.
1136
1137         """
1138         pass
1139
1140     def remove_backup(self, backup_id):
1141         """Delete a backup.
1142
1143         :param str backup_id: The id of the backup to remove
1144
1145         """
1146         pass
1147
1148     def remove_cached_images(self, arch=None, kind=None, series=None):
1149         """Remove cached OS images.
1150
1151         :param str arch: Architecture of the images to remove
1152         :param str kind: Image kind to remove, e.g. 'lxd'
1153         :param str series: Image series to remove, e.g. 'xenial'
1154
1155         """
1156         pass
1157
1158     def remove_machine(self, *machine_ids):
1159         """Remove a machine from this model.
1160
1161         :param str \*machine_ids: Ids of the machines to remove
1162
1163         """
1164         pass
1165     remove_machines = remove_machine
1166
1167     def remove_ssh_key(self, *keys):
1168         """Remove a public SSH key(s) from this model.
1169
1170         :param str \*keys: Keys to remove
1171
1172         """
1173         pass
1174     remove_ssh_keys = remove_ssh_key
1175
1176     def restore_backup(
1177             self, bootstrap=False, constraints=None, archive=None,
1178             backup_id=None, upload_tools=False):
1179         """Restore a backup archive to a new controller.
1180
1181         :param bool bootstrap: Bootstrap a new state machine
1182         :param constraints: Model constraints
1183         :type constraints: :class:`juju.Constraints`
1184         :param str archive: Path to backup archive to restore
1185         :param str backup_id: Id of backup to restore
1186         :param bool upload_tools: Upload tools if bootstrapping a new machine
1187
1188         """
1189         pass
1190
1191     def retry_provisioning(self):
1192         """Retry provisioning for failed machines.
1193
1194         """
1195         pass
1196
1197     def revoke(self, username, acl='read'):
1198         """Revoke a user's access to this model.
1199
1200         :param str username: Username to revoke
1201         :param str acl: Access control ('read' or 'write')
1202
1203         """
1204         pass
1205
1206     def run(self, command, timeout=None):
1207         """Run command on all machines in this model.
1208
1209         :param str command: The command to run
1210         :param int timeout: Time to wait before command is considered failed
1211
1212         """
1213         pass
1214
1215     def set_config(self, **config):
1216         """Set configuration keys on this model.
1217
1218         :param \*\*config: Config key/values
1219
1220         """
1221         pass
1222
1223     def set_constraints(self, constraints):
1224         """Set machine constraints on this model.
1225
1226         :param :class:`juju.Constraints` constraints: Machine constraints
1227
1228         """
1229         pass
1230
1231     def get_action_output(self, action_uuid, wait=-1):
1232         """Get the results of an action by ID.
1233
1234         :param str action_uuid: Id of the action
1235         :param int wait: Time in seconds to wait for action to complete
1236
1237         """
1238         pass
1239
1240     def get_action_status(self, uuid_or_prefix=None, name=None):
1241         """Get the status of all actions, filtered by ID, ID prefix, or action name.
1242
1243         :param str uuid_or_prefix: Filter by action uuid or prefix
1244         :param str name: Filter by action name
1245
1246         """
1247         pass
1248
1249     def get_budget(self, budget_name):
1250         """Get budget usage info.
1251
1252         :param str budget_name: Name of budget
1253
1254         """
1255         pass
1256
1257     def get_status(self, filter_=None, utc=False):
1258         """Return the status of the model.
1259
1260         :param str filter_: Service or unit name or wildcard ('*')
1261         :param bool utc: Display time as UTC in RFC3339 format
1262
1263         """
1264         pass
1265     status = get_status
1266
1267     def sync_tools(
1268             self, all_=False, destination=None, dry_run=False, public=False,
1269             source=None, stream=None, version=None):
1270         """Copy Juju tools into this model.
1271
1272         :param bool all_: Copy all versions, not just the latest
1273         :param str destination: Path to local destination directory
1274         :param bool dry_run: Don't do the actual copy
1275         :param bool public: Tools are for a public cloud, so generate mirrors
1276             information
1277         :param str source: Path to local source directory
1278         :param str stream: Simplestreams stream for which to sync metadata
1279         :param str version: Copy a specific major.minor version
1280
1281         """
1282         pass
1283
1284     def unblock(self, *commands):
1285         """Unblock an operation that would alter this model.
1286
1287         :param str \*commands: The commands to unblock. Valid values are
1288             'all-changes', 'destroy-model', 'remove-object'
1289
1290         """
1291         pass
1292
1293     def unset_config(self, *keys):
1294         """Unset configuration on this model.
1295
1296         :param str \*keys: The keys to unset
1297
1298         """
1299         pass
1300
1301     def upgrade_gui(self):
1302         """Upgrade the Juju GUI for this model.
1303
1304         """
1305         pass
1306
1307     def upgrade_juju(
1308             self, dry_run=False, reset_previous_upgrade=False,
1309             upload_tools=False, version=None):
1310         """Upgrade Juju on all machines in a model.
1311
1312         :param bool dry_run: Don't do the actual upgrade
1313         :param bool reset_previous_upgrade: Clear the previous (incomplete)
1314             upgrade status
1315         :param bool upload_tools: Upload local version of tools
1316         :param str version: Upgrade to a specific version
1317
1318         """
1319         pass
1320
1321     def upload_backup(self, archive_path):
1322         """Store a backup archive remotely in Juju.
1323
1324         :param str archive_path: Path to local archive
1325
1326         """
1327         pass
1328
1329     @property
1330     def charmstore(self):
1331         return self._charmstore
1332
1333     async def get_metrics(self, *tags):
1334         """Retrieve metrics.
1335
1336         :param str \*tags: Tags of entities from which to retrieve metrics.
1337             No tags retrieves the metrics of all units in the model.
1338         :return: Dictionary of unit_name:metrics
1339
1340         """
1341         log.debug("Retrieving metrics for %s",
1342                   ', '.join(tags) if tags else "all units")
1343
1344         metrics_facade = client.MetricsDebugFacade()
1345         metrics_facade.connect(self.connection)
1346
1347         entities = [client.Entity(tag) for tag in tags]
1348         metrics_result = await metrics_facade.GetMetrics(entities)
1349
1350         metrics = collections.defaultdict(list)
1351
1352         for entity_metrics in metrics_result.results:
1353             error = entity_metrics.error
1354             if error:
1355                 if "is not a valid tag" in error:
1356                     raise ValueError(error.message)
1357                 else:
1358                     raise Exception(error.message)
1359
1360             for metric in entity_metrics.metrics:
1361                 metrics[metric.unit].append(vars(metric))
1362
1363         return metrics
1364
1365
1366 def get_charm_series(path):
1367     """Inspects the charm directory at ``path`` and returns a default
1368     series from its metadata.yaml (the first item in the 'series' list).
1369
1370     Returns None if no series can be determined.
1371
1372     """
1373     md = Path(path) / "metadata.yaml"
1374     if not md.exists():
1375         return None
1376     data = yaml.load(md.open())
1377     series = data.get('series')
1378     return series[0] if series else None
1379
1380
1381 class BundleHandler(object):
1382     """
1383     Handle bundles by using the API to translate bundle YAML into a plan of
1384     steps and then dispatching each of those using the API.
1385     """
1386     def __init__(self, model):
1387         self.model = model
1388         self.charmstore = model.charmstore
1389         self.plan = []
1390         self.references = {}
1391         self._units_by_app = {}
1392         for unit_name, unit in model.units.items():
1393             app_units = self._units_by_app.setdefault(unit.application, [])
1394             app_units.append(unit_name)
1395         self.client_facade = client.ClientFacade()
1396         self.client_facade.connect(model.connection)
1397         self.app_facade = client.ApplicationFacade()
1398         self.app_facade.connect(model.connection)
1399         self.ann_facade = client.AnnotationsFacade()
1400         self.ann_facade.connect(model.connection)
1401
1402     async def _handle_local_charms(self, bundle):
1403         """Search for references to local charms (i.e. filesystem paths)
1404         in the bundle. Upload the local charms to the model, and replace
1405         the filesystem paths with appropriate 'local:' paths in the bundle.
1406
1407         Return the modified bundle.
1408
1409         :param dict bundle: Bundle dictionary
1410         :return: Modified bundle dictionary
1411
1412         """
1413         apps, args = [], []
1414
1415         default_series = bundle.get('series')
1416         for app_name in self.applications:
1417             app_dict = bundle['services'][app_name]
1418             charm_dir = os.path.abspath(os.path.expanduser(app_dict['charm']))
1419             if not os.path.isdir(charm_dir):
1420                 continue
1421             series = (
1422                 app_dict.get('series') or
1423                 default_series or
1424                 get_charm_series(charm_dir)
1425             )
1426             if not series:
1427                 raise JujuError(
1428                     "Couldn't determine series for charm at {}. "
1429                     "Add a 'series' key to the bundle.".format(charm_dir))
1430
1431             # Keep track of what we need to update. We keep a list of apps
1432             # that need to be updated, and a corresponding list of args
1433             # needed to update those apps.
1434             apps.append(app_name)
1435             args.append((charm_dir, series))
1436
1437         if apps:
1438             # If we have apps to update, spawn all the coroutines concurrently
1439             # and wait for them to finish.
1440             charm_urls = await asyncio.gather(*[
1441                 asyncio.ensure_future(self.model.add_local_charm_dir(*params))
1442                 for params in args
1443             ])
1444             # Update the 'charm:' entry for each app with the new 'local:' url.
1445             for app_name, charm_url in zip(apps, charm_urls):
1446                 bundle['services'][app_name]['charm'] = charm_url
1447
1448         return bundle
1449
1450     async def fetch_plan(self, entity_id):
1451         is_local = not entity_id.startswith('cs:') and os.path.isdir(entity_id)
1452         if is_local:
1453             bundle_yaml = (Path(entity_id) / "bundle.yaml").read_text()
1454         else:
1455             bundle_yaml = await self.charmstore.files(entity_id,
1456                                                       filename='bundle.yaml',
1457                                                       read_file=True)
1458         self.bundle = yaml.safe_load(bundle_yaml)
1459         self.bundle = await self._handle_local_charms(self.bundle)
1460
1461         self.plan = await self.client_facade.GetBundleChanges(
1462             yaml.dump(self.bundle))
1463
1464         if self.plan.errors:
1465             raise JujuError('\n'.join(self.plan.errors))
1466
1467     async def execute_plan(self):
1468         for step in self.plan.changes:
1469             method = getattr(self, step.method)
1470             result = await method(*step.args)
1471             self.references[step.id_] = result
1472
1473     @property
1474     def applications(self):
1475         return list(self.bundle['services'].keys())
1476
1477     def resolve(self, reference):
1478         if reference and reference.startswith('$'):
1479             reference = self.references[reference[1:]]
1480         return reference
1481
1482     async def addCharm(self, charm, series):
1483         """
1484         :param charm string:
1485             Charm holds the URL of the charm to be added.
1486
1487         :param series string:
1488             Series holds the series of the charm to be added
1489             if the charm default is not sufficient.
1490         """
1491         # We don't add local charms because they've already been added
1492         # by self._handle_local_charms
1493         if charm.startswith('local:'):
1494             return charm
1495
1496         entity_id = await self.charmstore.entityId(charm)
1497         log.debug('Adding %s', entity_id)
1498         await self.client_facade.AddCharm(None, entity_id)
1499         return entity_id
1500
1501     async def addMachines(self, params=None):
1502         """
1503         :param params dict:
1504             Dictionary specifying the machine to add. All keys are optional.
1505             Keys include:
1506
1507             series: string specifying the machine OS series.
1508
1509             constraints: string holding machine constraints, if any. We'll
1510                 parse this into the json friendly dict that the juju api
1511                 expects.
1512
1513             container_type: string holding the type of the container (for
1514                 instance ""lxd" or kvm"). It is not specified for top level
1515                 machines.
1516
1517             parent_id: string holding a placeholder pointing to another
1518                 machine change or to a unit change. This value is only
1519                 specified in the case this machine is a container, in
1520                 which case also ContainerType is set.
1521
1522         """
1523         params = params or {}
1524
1525         # Normalize keys
1526         params = {normalize_key(k): params[k] for k in params.keys()}
1527
1528         # Fix up values, as necessary.
1529         if 'parent_id' in params:
1530             params['parent_id'] = self.resolve(params['parent_id'])
1531
1532         params['constraints'] = parse_constraints(
1533             params.get('constraints'))
1534         params['jobs'] = params.get('jobs', ['JobHostUnits'])
1535
1536         if params.get('container_type') == 'lxc':
1537             log.warning('Juju 2.0 does not support lxc containers. '
1538                         'Converting containers to lxd.')
1539             params['container_type'] = 'lxd'
1540
1541         # Submit the request.
1542         params = client.AddMachineParams(**params)
1543         results = await self.client_facade.AddMachines([params])
1544         error = results.machines[0].error
1545         if error:
1546             raise ValueError("Error adding machine: %s", error.message)
1547         machine = results.machines[0].machine
1548         log.debug('Added new machine %s', machine)
1549         return machine
1550
1551     async def addRelation(self, endpoint1, endpoint2):
1552         """
1553         :param endpoint1 string:
1554         :param endpoint2 string:
1555             Endpoint1 and Endpoint2 hold relation endpoints in the
1556             "application:interface" form, where the application is always a
1557             placeholder pointing to an application change, and the interface is
1558             optional. Examples are "$deploy-42:web" or just "$deploy-42".
1559         """
1560         endpoints = [endpoint1, endpoint2]
1561         # resolve indirect references
1562         for i in range(len(endpoints)):
1563             parts = endpoints[i].split(':')
1564             parts[0] = self.resolve(parts[0])
1565             endpoints[i] = ':'.join(parts)
1566
1567         log.info('Relating %s <-> %s', *endpoints)
1568         return await self.model.add_relation(*endpoints)
1569
1570     async def deploy(self, charm, series, application, options, constraints,
1571                      storage, endpoint_bindings, resources):
1572         """
1573         :param charm string:
1574             Charm holds the URL of the charm to be used to deploy this
1575             application.
1576
1577         :param series string:
1578             Series holds the series of the application to be deployed
1579             if the charm default is not sufficient.
1580
1581         :param application string:
1582             Application holds the application name.
1583
1584         :param options map[string]interface{}:
1585             Options holds application options.
1586
1587         :param constraints string:
1588             Constraints holds the optional application constraints.
1589
1590         :param storage map[string]string:
1591             Storage holds the optional storage constraints.
1592
1593         :param endpoint_bindings map[string]string:
1594             EndpointBindings holds the optional endpoint bindings
1595
1596         :param resources map[string]int:
1597             Resources identifies the revision to use for each resource
1598             of the application's charm.
1599         """
1600         # resolve indirect references
1601         charm = self.resolve(charm)
1602         # stringify all config values for API
1603         options = {k: str(v) for k, v in options.items()}
1604         # build param object
1605         app = client.ApplicationDeploy(
1606             charm_url=charm,
1607             series=series,
1608             application=application,
1609             config=options,
1610             constraints=parse_constraints(constraints),
1611             storage=storage,
1612             endpoint_bindings=endpoint_bindings,
1613             resources=resources,
1614         )
1615         # do the do
1616         log.info('Deploying %s', charm)
1617         await self.app_facade.Deploy([app])
1618         # ensure the app is in the model for future operations
1619         await self.model._wait_for_new('application', application)
1620         return application
1621
1622     async def addUnit(self, application, to):
1623         """
1624         :param application string:
1625             Application holds the application placeholder name for which a unit
1626             is added.
1627
1628         :param to string:
1629             To holds the optional location where to add the unit, as a
1630             placeholder pointing to another unit change or to a machine change.
1631         """
1632         application = self.resolve(application)
1633         placement = self.resolve(to)
1634         if self._units_by_app.get(application):
1635             # enough units for this application already exist;
1636             # claim one, and carry on
1637             # NB: this should probably honor placement, but the juju client
1638             # doesn't, so we're not bothering, either
1639             unit_name = self._units_by_app[application].pop()
1640             log.debug('Reusing unit %s for %s', unit_name, application)
1641             return self.model.units[unit_name]
1642
1643         log.debug('Adding new unit for %s%s', application,
1644                   ' to %s' % placement if placement else '')
1645         return await self.model.applications[application].add_unit(
1646             count=1,
1647             to=placement,
1648         )
1649
1650     async def expose(self, application):
1651         """
1652         :param application string:
1653             Application holds the placeholder name of the application that must
1654             be exposed.
1655         """
1656         application = self.resolve(application)
1657         log.info('Exposing %s', application)
1658         return await self.model.applications[application].expose()
1659
1660     async def setAnnotations(self, id_, entity_type, annotations):
1661         """
1662         :param id_ string:
1663             Id is the placeholder for the application or machine change
1664             corresponding to the entity to be annotated.
1665
1666         :param entity_type EntityType:
1667             EntityType holds the type of the entity, "application" or
1668             "machine".
1669
1670         :param annotations map[string]string:
1671             Annotations holds the annotations as key/value pairs.
1672         """
1673         entity_id = self.resolve(id_)
1674         try:
1675             entity = self.model.state.get_entity(entity_type, entity_id)
1676         except KeyError:
1677             entity = await self.model._wait_for_new(entity_type, entity_id)
1678         return await entity.set_annotations(annotations)
1679
1680
1681 class CharmStore(object):
1682     """
1683     Async wrapper around theblues.charmstore.CharmStore
1684     """
1685     def __init__(self, loop):
1686         self.loop = loop
1687         self._cs = charmstore.CharmStore()
1688
1689     def __getattr__(self, name):
1690         """
1691         Wrap method calls in coroutines that use run_in_executor to make them
1692         async.
1693         """
1694         attr = getattr(self._cs, name)
1695         if not callable(attr):
1696             wrapper = partial(getattr, self._cs, name)
1697             setattr(self, name, wrapper)
1698         else:
1699             async def coro(*args, **kwargs):
1700                 method = partial(attr, *args, **kwargs)
1701                 return await self.loop.run_in_executor(None, method)
1702             setattr(self, name, coro)
1703             wrapper = coro
1704         return wrapper
1705
1706
1707 class CharmArchiveGenerator(object):
1708     def __init__(self, path):
1709         self.path = os.path.abspath(os.path.expanduser(path))
1710
1711     def make_archive(self, path):
1712         """Create archive of directory and write to ``path``.
1713
1714         :param path: Path to archive
1715
1716         Ignored::
1717
1718             * build/\* - This is used for packing the charm itself and any
1719                           similar tasks.
1720             * \*/.\*    - Hidden files are all ignored for now.  This will most
1721                           likely be changed into a specific ignore list
1722                           (.bzr, etc)
1723
1724         """
1725         zf = zipfile.ZipFile(path, 'w', zipfile.ZIP_DEFLATED)
1726         for dirpath, dirnames, filenames in os.walk(self.path):
1727             relative_path = dirpath[len(self.path) + 1:]
1728             if relative_path and not self._ignore(relative_path):
1729                 zf.write(dirpath, relative_path)
1730             for name in filenames:
1731                 archive_name = os.path.join(relative_path, name)
1732                 if not self._ignore(archive_name):
1733                     real_path = os.path.join(dirpath, name)
1734                     self._check_type(real_path)
1735                     if os.path.islink(real_path):
1736                         self._check_link(real_path)
1737                         self._write_symlink(
1738                             zf, os.readlink(real_path), archive_name)
1739                     else:
1740                         zf.write(real_path, archive_name)
1741         zf.close()
1742         return path
1743
1744     def _check_type(self, path):
1745         """Check the path
1746         """
1747         s = os.stat(path)
1748         if stat.S_ISDIR(s.st_mode) or stat.S_ISREG(s.st_mode):
1749             return path
1750         raise ValueError("Invalid Charm at % %s" % (
1751             path, "Invalid file type for a charm"))
1752
1753     def _check_link(self, path):
1754         link_path = os.readlink(path)
1755         if link_path[0] == "/":
1756             raise ValueError(
1757                 "Invalid Charm at %s: %s" % (
1758                     path, "Absolute links are invalid"))
1759         path_dir = os.path.dirname(path)
1760         link_path = os.path.join(path_dir, link_path)
1761         if not link_path.startswith(os.path.abspath(self.path)):
1762             raise ValueError(
1763                 "Invalid charm at %s %s" % (
1764                     path, "Only internal symlinks are allowed"))
1765
1766     def _write_symlink(self, zf, link_target, link_path):
1767         """Package symlinks with appropriate zipfile metadata."""
1768         info = zipfile.ZipInfo()
1769         info.filename = link_path
1770         info.create_system = 3
1771         # Magic code for symlinks / py2/3 compat
1772         # 27166663808 = (stat.S_IFLNK | 0755) << 16
1773         info.external_attr = 2716663808
1774         zf.writestr(info, link_target)
1775
1776     def _ignore(self, path):
1777         if path == "build" or path.startswith("build/"):
1778             return True
1779         if path.startswith('.'):
1780             return True