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 to: Placement directive. Use placement.parse to generate it.
 914             For example:
 915
 916             from juju import placement
 917
 918             placement.parse('23') - place on machine 23
 919             placement.parse('lxc:7') - place in new lxc container on machine 7
 920             placement.parse('24/lxc/3') - place in container 3 on machine 24
 921
 922             If None, a new machine is provisioned.
 923
 924
 925         TODO::
 926
 927             - application_name is required; fill this in automatically if not
 928               provided by caller
 929             - series is required; how do we pick a default?
 930
 931         """
 932         if to:
 933             placement = [
 934                 client.Placement(**p) for p in to
 935             ]
 936         else:
 937             placement = []
 938
 939         if storage:
 940             storage = {
 941                 k: client.Constraints(**v)
 942                 for k, v in storage.items()
 943             }
 944
 945         is_local = (
 946             entity_url.startswith('local:') or
 947             os.path.isdir(entity_url)
 948         )
 949         entity_id = await self.charmstore.entityId(entity_url) \
 950             if not is_local else entity_url
 951
 952         app_facade = client.ApplicationFacade()
 953         client_facade = client.ClientFacade()
 954         app_facade.connect(self.connection)
 955         client_facade.connect(self.connection)
 956
 957         is_bundle = ((is_local and
 958                       (Path(entity_id) / 'bundle.yaml').exists()) or
 959                      (not is_local and 'bundle/' in entity_id))
 960
 961         if is_bundle:
 962             handler = BundleHandler(self)
 963             await handler.fetch_plan(entity_id)
 964             await handler.execute_plan()
 965             extant_apps = {app for app in self.applications}
 966             pending_apps = set(handler.applications) - extant_apps
 967             if pending_apps:
 968                 # new apps will usually be in the model by now, but if some
 969                 # haven't made it yet we'll need to wait on them to be added
 970                 await asyncio.gather(*[
 971                     asyncio.ensure_future(
 972                         self._wait_for_new('application', app_name))
 973                     for app_name in pending_apps
 974                 ])
 975             return [app for name, app in self.applications.items()
 976                     if name in handler.applications]
 977         else:
 978             log.debug(
 979                 'Deploying %s', entity_id)
 980
 981             if not is_local:
 982                 await client_facade.AddCharm(channel, entity_id)
 983             elif not entity_id.startswith('local:'):
 984                 # We have a local charm dir that needs to be uploaded
 985                 charm_dir = os.path.abspath(
 986                     os.path.expanduser(entity_id))
 987                 series = series or get_charm_series(charm_dir)
 988                 if not series:
 989                     raise JujuError(
 990                         "Couldn't determine series for charm at {}. "
 991                         "Pass a 'series' kwarg to Model.deploy().".format(
 992                             charm_dir))
 993                 entity_id = await self.add_local_charm_dir(charm_dir, series)
 994
 995             app = client.ApplicationDeploy(
 996                 application=application_name,
 997                 channel=channel,
 998                 charm_url=entity_id,
 999                 config=config,
1000                 constraints=parse_constraints(constraints),
1001                 endpoint_bindings=bind,
1002                 num_units=num_units,
1003                 placement=placement,
1004                 resources=resources,
1005                 series=series,
1006                 storage=storage,
1007             )
1008
1009             result = await app_facade.Deploy([app])
1010             errors = [r.error.message for r in result.results if r.error]
1011             if errors:
1012                 raise JujuError('\n'.join(errors))
1013             return await self._wait_for_new('application', application_name)
1014
1015     def destroy(self):
1016         """Terminate all machines and resources for this model.
1017
1018         """
1019         pass
1020
1021     async def destroy_unit(self, *unit_names):
1022         """Destroy units by name.
1023
1024         """
1025         app_facade = client.ApplicationFacade()
1026         app_facade.connect(self.connection)
1027
1028         log.debug(
1029             'Destroying unit%s %s',
1030             's' if len(unit_names) == 1 else '',
1031             ' '.join(unit_names))
1032
1033         return await app_facade.DestroyUnits(list(unit_names))
1034     destroy_units = destroy_unit
1035
1036     def get_backup(self, archive_id):
1037         """Download a backup archive file.
1038
1039         :param str archive_id: The id of the archive to download
1040         :return str: Path to the archive file
1041
1042         """
1043         pass
1044
1045     def enable_ha(
1046             self, num_controllers=0, constraints=None, series=None, to=None):
1047         """Ensure sufficient controllers exist to provide redundancy.
1048
1049         :param int num_controllers: Number of controllers to make available
1050         :param constraints: Constraints to apply to the controller machines
1051         :type constraints: :class:`juju.Constraints`
1052         :param str series: Series of the controller machines
1053         :param list to: Placement directives for controller machines, e.g.::
1054
1055             '23' - machine 23
1056             'lxc:7' - new lxc container on machine 7
1057             '24/lxc/3' - lxc container 3 or machine 24
1058
1059             If None, a new machine is provisioned.
1060
1061         """
1062         pass
1063
1064     def get_config(self):
1065         """Return the configuration settings for this model.
1066
1067         """
1068         pass
1069
1070     def get_constraints(self):
1071         """Return the machine constraints for this model.
1072
1073         """
1074         pass
1075
1076     def grant(self, username, acl='read'):
1077         """Grant a user access to this model.
1078
1079         :param str username: Username
1080         :param str acl: Access control ('read' or 'write')
1081
1082         """
1083         pass
1084
1085     def import_ssh_key(self, identity):
1086         """Add a public SSH key from a trusted indentity source to this model.
1087
1088         :param str identity: User identity in the form <lp|gh>:<username>
1089
1090         """
1091         pass
1092     import_ssh_keys = import_ssh_key
1093
1094     def get_machines(self, machine, utc=False):
1095         """Return list of machines in this model.
1096
1097         :param str machine: Machine id, e.g. '0'
1098         :param bool utc: Display time as UTC in RFC3339 format
1099
1100         """
1101         pass
1102
1103     def get_shares(self):
1104         """Return list of all users with access to this model.
1105
1106         """
1107         pass
1108
1109     def get_spaces(self):
1110         """Return list of all known spaces, including associated subnets.
1111
1112         """
1113         pass
1114
1115     def get_ssh_key(self):
1116         """Return known SSH keys for this model.
1117
1118         """
1119         pass
1120     get_ssh_keys = get_ssh_key
1121
1122     def get_storage(self, filesystem=False, volume=False):
1123         """Return details of storage instances.
1124
1125         :param bool filesystem: Include filesystem storage
1126         :param bool volume: Include volume storage
1127
1128         """
1129         pass
1130
1131     def get_storage_pools(self, names=None, providers=None):
1132         """Return list of storage pools.
1133
1134         :param list names: Only include pools with these names
1135         :param list providers: Only include pools for these providers
1136
1137         """
1138         pass
1139
1140     def get_subnets(self, space=None, zone=None):
1141         """Return list of known subnets.
1142
1143         :param str space: Only include subnets in this space
1144         :param str zone: Only include subnets in this zone
1145
1146         """
1147         pass
1148
1149     def remove_blocks(self):
1150         """Remove all blocks from this model.
1151
1152         """
1153         pass
1154
1155     def remove_backup(self, backup_id):
1156         """Delete a backup.
1157
1158         :param str backup_id: The id of the backup to remove
1159
1160         """
1161         pass
1162
1163     def remove_cached_images(self, arch=None, kind=None, series=None):
1164         """Remove cached OS images.
1165
1166         :param str arch: Architecture of the images to remove
1167         :param str kind: Image kind to remove, e.g. 'lxd'
1168         :param str series: Image series to remove, e.g. 'xenial'
1169
1170         """
1171         pass
1172
1173     def remove_machine(self, *machine_ids):
1174         """Remove a machine from this model.
1175
1176         :param str \*machine_ids: Ids of the machines to remove
1177
1178         """
1179         pass
1180     remove_machines = remove_machine
1181
1182     def remove_ssh_key(self, *keys):
1183         """Remove a public SSH key(s) from this model.
1184
1185         :param str \*keys: Keys to remove
1186
1187         """
1188         pass
1189     remove_ssh_keys = remove_ssh_key
1190
1191     def restore_backup(
1192             self, bootstrap=False, constraints=None, archive=None,
1193             backup_id=None, upload_tools=False):
1194         """Restore a backup archive to a new controller.
1195
1196         :param bool bootstrap: Bootstrap a new state machine
1197         :param constraints: Model constraints
1198         :type constraints: :class:`juju.Constraints`
1199         :param str archive: Path to backup archive to restore
1200         :param str backup_id: Id of backup to restore
1201         :param bool upload_tools: Upload tools if bootstrapping a new machine
1202
1203         """
1204         pass
1205
1206     def retry_provisioning(self):
1207         """Retry provisioning for failed machines.
1208
1209         """
1210         pass
1211
1212     def revoke(self, username, acl='read'):
1213         """Revoke a user's access to this model.
1214
1215         :param str username: Username to revoke
1216         :param str acl: Access control ('read' or 'write')
1217
1218         """
1219         pass
1220
1221     def run(self, command, timeout=None):
1222         """Run command on all machines in this model.
1223
1224         :param str command: The command to run
1225         :param int timeout: Time to wait before command is considered failed
1226
1227         """
1228         pass
1229
1230     def set_config(self, **config):
1231         """Set configuration keys on this model.
1232
1233         :param \*\*config: Config key/values
1234
1235         """
1236         pass
1237
1238     def set_constraints(self, constraints):
1239         """Set machine constraints on this model.
1240
1241         :param :class:`juju.Constraints` constraints: Machine constraints
1242
1243         """
1244         pass
1245
1246     def get_action_output(self, action_uuid, wait=-1):
1247         """Get the results of an action by ID.
1248
1249         :param str action_uuid: Id of the action
1250         :param int wait: Time in seconds to wait for action to complete
1251
1252         """
1253         pass
1254
1255     def get_action_status(self, uuid_or_prefix=None, name=None):
1256         """Get the status of all actions, filtered by ID, ID prefix, or action name.
1257
1258         :param str uuid_or_prefix: Filter by action uuid or prefix
1259         :param str name: Filter by action name
1260
1261         """
1262         pass
1263
1264     def get_budget(self, budget_name):
1265         """Get budget usage info.
1266
1267         :param str budget_name: Name of budget
1268
1269         """
1270         pass
1271
1272     def get_status(self, filter_=None, utc=False):
1273         """Return the status of the model.
1274
1275         :param str filter_: Service or unit name or wildcard ('*')
1276         :param bool utc: Display time as UTC in RFC3339 format
1277
1278         """
1279         pass
1280     status = get_status
1281
1282     def sync_tools(
1283             self, all_=False, destination=None, dry_run=False, public=False,
1284             source=None, stream=None, version=None):
1285         """Copy Juju tools into this model.
1286
1287         :param bool all_: Copy all versions, not just the latest
1288         :param str destination: Path to local destination directory
1289         :param bool dry_run: Don't do the actual copy
1290         :param bool public: Tools are for a public cloud, so generate mirrors
1291             information
1292         :param str source: Path to local source directory
1293         :param str stream: Simplestreams stream for which to sync metadata
1294         :param str version: Copy a specific major.minor version
1295
1296         """
1297         pass
1298
1299     def unblock(self, *commands):
1300         """Unblock an operation that would alter this model.
1301
1302         :param str \*commands: The commands to unblock. Valid values are
1303             'all-changes', 'destroy-model', 'remove-object'
1304
1305         """
1306         pass
1307
1308     def unset_config(self, *keys):
1309         """Unset configuration on this model.
1310
1311         :param str \*keys: The keys to unset
1312
1313         """
1314         pass
1315
1316     def upgrade_gui(self):
1317         """Upgrade the Juju GUI for this model.
1318
1319         """
1320         pass
1321
1322     def upgrade_juju(
1323             self, dry_run=False, reset_previous_upgrade=False,
1324             upload_tools=False, version=None):
1325         """Upgrade Juju on all machines in a model.
1326
1327         :param bool dry_run: Don't do the actual upgrade
1328         :param bool reset_previous_upgrade: Clear the previous (incomplete)
1329             upgrade status
1330         :param bool upload_tools: Upload local version of tools
1331         :param str version: Upgrade to a specific version
1332
1333         """
1334         pass
1335
1336     def upload_backup(self, archive_path):
1337         """Store a backup archive remotely in Juju.
1338
1339         :param str archive_path: Path to local archive
1340
1341         """
1342         pass
1343
1344     @property
1345     def charmstore(self):
1346         return self._charmstore
1347
1348     async def get_metrics(self, *tags):
1349         """Retrieve metrics.
1350
1351         :param str \*tags: Tags of entities from which to retrieve metrics.
1352             No tags retrieves the metrics of all units in the model.
1353         :return: Dictionary of unit_name:metrics
1354
1355         """
1356         log.debug("Retrieving metrics for %s",
1357                   ', '.join(tags) if tags else "all units")
1358
1359         metrics_facade = client.MetricsDebugFacade()
1360         metrics_facade.connect(self.connection)
1361
1362         entities = [client.Entity(tag) for tag in tags]
1363         metrics_result = await metrics_facade.GetMetrics(entities)
1364
1365         metrics = collections.defaultdict(list)
1366
1367         for entity_metrics in metrics_result.results:
1368             error = entity_metrics.error
1369             if error:
1370                 if "is not a valid tag" in error:
1371                     raise ValueError(error.message)
1372                 else:
1373                     raise Exception(error.message)
1374
1375             for metric in entity_metrics.metrics:
1376                 metrics[metric.unit].append(vars(metric))
1377
1378         return metrics
1379
1380
1381 def get_charm_series(path):
1382     """Inspects the charm directory at ``path`` and returns a default
1383     series from its metadata.yaml (the first item in the 'series' list).
1384
1385     Returns None if no series can be determined.
1386
1387     """
1388     md = Path(path) / "metadata.yaml"
1389     if not md.exists():
1390         return None
1391     data = yaml.load(md.open())
1392     series = data.get('series')
1393     return series[0] if series else None
1394
1395
1396 class BundleHandler(object):
1397     """
1398     Handle bundles by using the API to translate bundle YAML into a plan of
1399     steps and then dispatching each of those using the API.
1400     """
1401     def __init__(self, model):
1402         self.model = model
1403         self.charmstore = model.charmstore
1404         self.plan = []
1405         self.references = {}
1406         self._units_by_app = {}
1407         for unit_name, unit in model.units.items():
1408             app_units = self._units_by_app.setdefault(unit.application, [])
1409             app_units.append(unit_name)
1410         self.client_facade = client.ClientFacade()
1411         self.client_facade.connect(model.connection)
1412         self.app_facade = client.ApplicationFacade()
1413         self.app_facade.connect(model.connection)
1414         self.ann_facade = client.AnnotationsFacade()
1415         self.ann_facade.connect(model.connection)
1416
1417     async def _handle_local_charms(self, bundle):
1418         """Search for references to local charms (i.e. filesystem paths)
1419         in the bundle. Upload the local charms to the model, and replace
1420         the filesystem paths with appropriate 'local:' paths in the bundle.
1421
1422         Return the modified bundle.
1423
1424         :param dict bundle: Bundle dictionary
1425         :return: Modified bundle dictionary
1426
1427         """
1428         apps, args = [], []
1429
1430         default_series = bundle.get('series')
1431         for app_name in self.applications:
1432             app_dict = bundle['services'][app_name]
1433             charm_dir = os.path.abspath(os.path.expanduser(app_dict['charm']))
1434             if not os.path.isdir(charm_dir):
1435                 continue
1436             series = (
1437                 app_dict.get('series') or
1438                 default_series or
1439                 get_charm_series(charm_dir)
1440             )
1441             if not series:
1442                 raise JujuError(
1443                     "Couldn't determine series for charm at {}. "
1444                     "Add a 'series' key to the bundle.".format(charm_dir))
1445
1446             # Keep track of what we need to update. We keep a list of apps
1447             # that need to be updated, and a corresponding list of args
1448             # needed to update those apps.
1449             apps.append(app_name)
1450             args.append((charm_dir, series))
1451
1452         if apps:
1453             # If we have apps to update, spawn all the coroutines concurrently
1454             # and wait for them to finish.
1455             charm_urls = await asyncio.gather(*[
1456                 self.model.add_local_charm_dir(*params)
1457                 for params in args
1458             ])
1459             # Update the 'charm:' entry for each app with the new 'local:' url.
1460             for app_name, charm_url in zip(apps, charm_urls):
1461                 bundle['services'][app_name]['charm'] = charm_url
1462
1463         return bundle
1464
1465     async def fetch_plan(self, entity_id):
1466         is_local = not entity_id.startswith('cs:') and os.path.isdir(entity_id)
1467         if is_local:
1468             bundle_yaml = (Path(entity_id) / "bundle.yaml").read_text()
1469         else:
1470             bundle_yaml = await self.charmstore.files(entity_id,
1471                                                       filename='bundle.yaml',
1472                                                       read_file=True)
1473         self.bundle = yaml.safe_load(bundle_yaml)
1474         self.bundle = await self._handle_local_charms(self.bundle)
1475
1476         self.plan = await self.client_facade.GetBundleChanges(
1477             yaml.dump(self.bundle))
1478
1479         if self.plan.errors:
1480             raise JujuError('\n'.join(self.plan.errors))
1481
1482     async def execute_plan(self):
1483         for step in self.plan.changes:
1484             method = getattr(self, step.method)
1485             result = await method(*step.args)
1486             self.references[step.id_] = result
1487
1488     @property
1489     def applications(self):
1490         return list(self.bundle['services'].keys())
1491
1492     def resolve(self, reference):
1493         if reference and reference.startswith('$'):
1494             reference = self.references[reference[1:]]
1495         return reference
1496
1497     async def addCharm(self, charm, series):
1498         """
1499         :param charm string:
1500             Charm holds the URL of the charm to be added.
1501
1502         :param series string:
1503             Series holds the series of the charm to be added
1504             if the charm default is not sufficient.
1505         """
1506         # We don't add local charms because they've already been added
1507         # by self._handle_local_charms
1508         if charm.startswith('local:'):
1509             return charm
1510
1511         entity_id = await self.charmstore.entityId(charm)
1512         log.debug('Adding %s', entity_id)
1513         await self.client_facade.AddCharm(None, entity_id)
1514         return entity_id
1515
1516     async def addMachines(self, params=None):
1517         """
1518         :param params dict:
1519             Dictionary specifying the machine to add. All keys are optional.
1520             Keys include:
1521
1522             series: string specifying the machine OS series.
1523
1524             constraints: string holding machine constraints, if any. We'll
1525                 parse this into the json friendly dict that the juju api
1526                 expects.
1527
1528             container_type: string holding the type of the container (for
1529                 instance ""lxd" or kvm"). It is not specified for top level
1530                 machines.
1531
1532             parent_id: string holding a placeholder pointing to another
1533                 machine change or to a unit change. This value is only
1534                 specified in the case this machine is a container, in
1535                 which case also ContainerType is set.
1536
1537         """
1538         params = params or {}
1539
1540         # Normalize keys
1541         params = {normalize_key(k): params[k] for k in params.keys()}
1542
1543         # Fix up values, as necessary.
1544         if 'parent_id' in params:
1545             params['parent_id'] = self.resolve(params['parent_id'])
1546
1547         params['constraints'] = parse_constraints(
1548             params.get('constraints'))
1549         params['jobs'] = params.get('jobs', ['JobHostUnits'])
1550
1551         if params.get('container_type') == 'lxc':
1552             log.warning('Juju 2.0 does not support lxc containers. '
1553                         'Converting containers to lxd.')
1554             params['container_type'] = 'lxd'
1555
1556         # Submit the request.
1557         params = client.AddMachineParams(**params)
1558         results = await self.client_facade.AddMachines([params])
1559         error = results.machines[0].error
1560         if error:
1561             raise ValueError("Error adding machine: %s", error.message)
1562         machine = results.machines[0].machine
1563         log.debug('Added new machine %s', machine)
1564         return machine
1565
1566     async def addRelation(self, endpoint1, endpoint2):
1567         """
1568         :param endpoint1 string:
1569         :param endpoint2 string:
1570             Endpoint1 and Endpoint2 hold relation endpoints in the
1571             "application:interface" form, where the application is always a
1572             placeholder pointing to an application change, and the interface is
1573             optional. Examples are "$deploy-42:web" or just "$deploy-42".
1574         """
1575         endpoints = [endpoint1, endpoint2]
1576         # resolve indirect references
1577         for i in range(len(endpoints)):
1578             parts = endpoints[i].split(':')
1579             parts[0] = self.resolve(parts[0])
1580             endpoints[i] = ':'.join(parts)
1581
1582         log.info('Relating %s <-> %s', *endpoints)
1583         return await self.model.add_relation(*endpoints)
1584
1585     async def deploy(self, charm, series, application, options, constraints,
1586                      storage, endpoint_bindings, resources):
1587         """
1588         :param charm string:
1589             Charm holds the URL of the charm to be used to deploy this
1590             application.
1591
1592         :param series string:
1593             Series holds the series of the application to be deployed
1594             if the charm default is not sufficient.
1595
1596         :param application string:
1597             Application holds the application name.
1598
1599         :param options map[string]interface{}:
1600             Options holds application options.
1601
1602         :param constraints string:
1603             Constraints holds the optional application constraints.
1604
1605         :param storage map[string]string:
1606             Storage holds the optional storage constraints.
1607
1608         :param endpoint_bindings map[string]string:
1609             EndpointBindings holds the optional endpoint bindings
1610
1611         :param resources map[string]int:
1612             Resources identifies the revision to use for each resource
1613             of the application's charm.
1614         """
1615         # resolve indirect references
1616         charm = self.resolve(charm)
1617         # stringify all config values for API
1618         options = {k: str(v) for k, v in options.items()}
1619         # build param object
1620         app = client.ApplicationDeploy(
1621             charm_url=charm,
1622             series=series,
1623             application=application,
1624             config=options,
1625             constraints=parse_constraints(constraints),
1626             storage=storage,
1627             endpoint_bindings=endpoint_bindings,
1628             resources=resources,
1629         )
1630         # do the do
1631         log.info('Deploying %s', charm)
1632         await self.app_facade.Deploy([app])
1633         # ensure the app is in the model for future operations
1634         await self.model._wait_for_new('application', application)
1635         return application
1636
1637     async def addUnit(self, application, to):
1638         """
1639         :param application string:
1640             Application holds the application placeholder name for which a unit
1641             is added.
1642
1643         :param to string:
1644             To holds the optional location where to add the unit, as a
1645             placeholder pointing to another unit change or to a machine change.
1646         """
1647         application = self.resolve(application)
1648         placement = self.resolve(to)
1649         if self._units_by_app.get(application):
1650             # enough units for this application already exist;
1651             # claim one, and carry on
1652             # NB: this should probably honor placement, but the juju client
1653             # doesn't, so we're not bothering, either
1654             unit_name = self._units_by_app[application].pop()
1655             log.debug('Reusing unit %s for %s', unit_name, application)
1656             return self.model.units[unit_name]
1657
1658         log.debug('Adding new unit for %s%s', application,
1659                   ' to %s' % placement if placement else '')
1660         return await self.model.applications[application].add_unit(
1661             count=1,
1662             to=placement,
1663         )
1664
1665     async def expose(self, application):
1666         """
1667         :param application string:
1668             Application holds the placeholder name of the application that must
1669             be exposed.
1670         """
1671         application = self.resolve(application)
1672         log.info('Exposing %s', application)
1673         return await self.model.applications[application].expose()
1674
1675     async def setAnnotations(self, id_, entity_type, annotations):
1676         """
1677         :param id_ string:
1678             Id is the placeholder for the application or machine change
1679             corresponding to the entity to be annotated.
1680
1681         :param entity_type EntityType:
1682             EntityType holds the type of the entity, "application" or
1683             "machine".
1684
1685         :param annotations map[string]string:
1686             Annotations holds the annotations as key/value pairs.
1687         """
1688         entity_id = self.resolve(id_)
1689         try:
1690             entity = self.model.state.get_entity(entity_type, entity_id)
1691         except KeyError:
1692             entity = await self.model._wait_for_new(entity_type, entity_id)
1693         return await entity.set_annotations(annotations)
1694
1695
1696 class CharmStore(object):
1697     """
1698     Async wrapper around theblues.charmstore.CharmStore
1699     """
1700     def __init__(self, loop):
1701         self.loop = loop
1702         self._cs = charmstore.CharmStore()
1703
1704     def __getattr__(self, name):
1705         """
1706         Wrap method calls in coroutines that use run_in_executor to make them
1707         async.
1708         """
1709         attr = getattr(self._cs, name)
1710         if not callable(attr):
1711             wrapper = partial(getattr, self._cs, name)
1712             setattr(self, name, wrapper)
1713         else:
1714             async def coro(*args, **kwargs):
1715                 method = partial(attr, *args, **kwargs)
1716                 return await self.loop.run_in_executor(None, method)
1717             setattr(self, name, coro)
1718             wrapper = coro
1719         return wrapper
1720
1721
1722 class CharmArchiveGenerator(object):
1723     def __init__(self, path):
1724         self.path = os.path.abspath(os.path.expanduser(path))
1725
1726     def make_archive(self, path):
1727         """Create archive of directory and write to ``path``.
1728
1729         :param path: Path to archive
1730
1731         Ignored::
1732
1733             * build/\* - This is used for packing the charm itself and any
1734                           similar tasks.
1735             * \*/.\*    - Hidden files are all ignored for now.  This will most
1736                           likely be changed into a specific ignore list
1737                           (.bzr, etc)
1738
1739         """
1740         zf = zipfile.ZipFile(path, 'w', zipfile.ZIP_DEFLATED)
1741         for dirpath, dirnames, filenames in os.walk(self.path):
1742             relative_path = dirpath[len(self.path) + 1:]
1743             if relative_path and not self._ignore(relative_path):
1744                 zf.write(dirpath, relative_path)
1745             for name in filenames:
1746                 archive_name = os.path.join(relative_path, name)
1747                 if not self._ignore(archive_name):
1748                     real_path = os.path.join(dirpath, name)
1749                     self._check_type(real_path)
1750                     if os.path.islink(real_path):
1751                         self._check_link(real_path)
1752                         self._write_symlink(
1753                             zf, os.readlink(real_path), archive_name)
1754                     else:
1755                         zf.write(real_path, archive_name)
1756         zf.close()
1757         return path
1758
1759     def _check_type(self, path):
1760         """Check the path
1761         """
1762         s = os.stat(path)
1763         if stat.S_ISDIR(s.st_mode) or stat.S_ISREG(s.st_mode):
1764             return path
1765         raise ValueError("Invalid Charm at % %s" % (
1766             path, "Invalid file type for a charm"))
1767
1768     def _check_link(self, path):
1769         link_path = os.readlink(path)
1770         if link_path[0] == "/":
1771             raise ValueError(
1772                 "Invalid Charm at %s: %s" % (
1773                     path, "Absolute links are invalid"))
1774         path_dir = os.path.dirname(path)
1775         link_path = os.path.join(path_dir, link_path)
1776         if not link_path.startswith(os.path.abspath(self.path)):
1777             raise ValueError(
1778                 "Invalid charm at %s %s" % (
1779                     path, "Only internal symlinks are allowed"))
1780
1781     def _write_symlink(self, zf, link_target, link_path):
1782         """Package symlinks with appropriate zipfile metadata."""
1783         info = zipfile.ZipInfo()
1784         info.filename = link_path
1785         info.create_system = 3
1786         # Magic code for symlinks / py2/3 compat
1787         # 27166663808 = (stat.S_IFLNK | 0755) << 16
1788         info.external_attr = 2716663808
1789         zf.writestr(info, link_target)
1790
1791     def _ignore(self, path):
1792         if path == "build" or path.startswith("build/"):
1793             return True
1794         if path.startswith('.'):
1795             return True