Release6/vca-async-api.md

   1 # Juju Asyncronous API #
   2
   3 ## Proposer ##
   4 - Adam Israel
   5
   6 ## Type ##
   7 **Feature**
   8
   9 ## Target MDG/TF ##
  10 SO
  11
  12 ## Description ##
  13
  14 As of R2, the SO is using the older syncronous Juju API. This can lead the SO
  15 to appear "frozen" while it blocks waiting for a Juju operation to complete.
  16
  17 To address this issue, we would like the SO to convert to using
  18 [libjuju](https://github.com/juju/python-libjuju) python library. It offers
  19 the following benefits:
  20 - Asynchronous, using the asyncio and async/await features of python 3.5+
  21 - Websocket-level bindings are programmatically generated (indirectly) from the
  22 Juju golang code, ensuring full api coverage
  23 - Provides an OO layer which encapsulates much of the websocket api and
  24 provides familiar nouns and verbs (e.g. Model.deploy(), Application.add_unit(),
  25 etc.)
  26
  27 ## Demo or definition of done ##
  28 Demos of using libjuju can be found in the
  29 [quickstart](https://github.com/juju/python-libjuju#quickstart) and in the
  30 [examples](https://github.com/juju/python-libjuju/tree/master/examples) folder.
  31
  32 Here is a simple implementation that deploys a charm:
  33 ```python
  34 #!/usr/bin/python3.5
  35
  36 import asyncio
  37 import logging
  38
  39 from juju import loop
  40 from juju.model import Model
  41
  42
  43 async def deploy():
  44     # Create a Model instance. We need to connect our Model to a Juju api
  45     # server before we can use it.
  46     model = Model()
  47
  48     # Connect to the currently active Juju model
  49     await model.connect_current()
  50
  51     # Deploy a single unit of the ubuntu charm, using revision 0 from the
  52     # stable channel of the Charm Store.
  53     ubuntu_app = await model.deploy(
  54         'ubuntu-0',
  55         application_name='ubuntu',
  56         series='xenial',
  57         channel='stable',
  58     )
  59
  60     # Disconnect from the api server and cleanup.
  61     model.disconnect()
  62
  63
  64 def main():
  65     # Set logging level to debug so we can see verbose output from the
  66     # juju library.
  67     logging.basicConfig(level=logging.DEBUG)
  68
  69     # Quiet logging from the websocket library. If you want to see
  70     # everything sent over the wire, set this to DEBUG.
  71     ws_logger = logging.getLogger('websockets.protocol')
  72     ws_logger.setLevel(logging.INFO)
  73
  74     # Run the deploy coroutine in an asyncio event loop, using a helper
  75     # that abstracts loop creation and teardown.
  76     loop.run(deploy())
  77
  78
  79 if __name__ == '__main__':
  80     main()
  81 ```