Revert "Remove vendored libjuju"

[osm/N2VC.git] / modules / libjuju / docs / narrative / application.rst

diff --git a/modules/libjuju/docs/narrative/application.rst b/modules/libjuju/docs/narrative/application.rst
new file mode 100644 (file)
index 0000000..1565e5f
--- /dev/null
+++ b/modules/libjuju/docs/narrative/application.rst
@@ -0,0 +1,136 @@
+Applications
+============
+For api docs, see :class:`juju.application.Application`.
+
+
+Deploying
+---------
+To deploy a new application, connect a model and then call its
+:meth:`~juju.model.Model.deploy` method. An
+:class:`~juju.application.Application` instance is returned.
+
+.. code:: python
+
+  from juju.model import Model
+
+  model = Model()
+  await model.connect_current()
+
+  mysql_app = await model.deploy(
+      # If a revision number is not included in the charm url,
+      # the latest revision from the Charm Store will be used.
+      'cs:mysql-55',
+      application_name='mysql',
+      series='trusty',
+      channel='stable',
+      config={
+          'tuning-level': 'safest',
+      },
+      constraints={
+          'mem': 256 * MB,
+      },
+  )
+
+
+Deploying a Local Charm
+-----------------------
+To deploy a local charm, pass the charm directory path to
+`Model.deploy()`.
+
+.. code:: python
+
+  from juju.model import Model
+
+  model = Model()
+  await model.connect_current()
+
+  # Deploy a local charm using a path to the charm directory
+  await model.deploy(
+      '/home/tvansteenburgh/src/charms/ubuntu',
+      application_name='ubuntu',
+      series='trusty',
+  )
+
+
+Adding Units
+------------
+To add units to a deployed application, use the
+:meth:`juju.application.Application.add_units` method. A list of the newly
+added units (:class:`~juju.unit.Unit` objects) is returned.
+
+.. code:: python
+
+  ubuntu_app = await model.deploy(
+      'ubuntu',
+      application_name='ubuntu',
+      series='trusty',
+      channel='stable',
+  )
+
+  unit_a, unit_b = await ubuntu_app.add_units(count=2)
+
+
+Updating Config and Constraints
+-------------------------------
+Example showing how to update configuration and constraints on a deployed
+application. The `mysql_app` object is an instance of
+:class:`juju.application.Application`.
+
+.. code:: python
+
+  MB = 1024 * 1024
+
+  # Update and check app config
+  await mysql_app.set_config({'tuning-level': 'fast'})
+  config = await mysql_app.get_config()
+
+  assert(config['tuning-level']['value'] == 'fast')
+
+  # update and check app constraints
+  await mysql_app.set_constraints({'mem': 512 * MB})
+  constraints = await mysql_app.get_constraints()
+
+  assert(constraints['mem'] == 512 * MB)
+
+
+Adding and Removing Relations
+-----------------------------
+The :meth:`juju.application.Application.add_relation` method returns a
+:class:`juju.relation.Relation` instance.
+
+.. code:: python
+
+  from juju.model import Model
+
+  model = Model()
+  await model.connect_current()
+
+  # Deploy mysql-master application
+  mysql_master = await model.deploy(
+      'cs:mysql-55',
+      application_name='mysql-master',
+      series='trusty',
+      channel='stable',
+  )
+
+  # Deploy mysql-slave application
+  mysql_slave = await model.deploy(
+      'cs:mysql-55',
+      application_name='mysql-slave',
+      series='trusty',
+      channel='stable',
+  )
+
+  # Add the master-slave relation
+  relation = await mysql_master.add_relation(
+      # Name of the relation on the local (mysql-master) side
+      'master',
+      # Name of the app:relation on the remote side
+      'mysql-slave:slave',
+  )
+
+  # Remove the relation
+  await mysql_master.remove_relation(
+      'master',
+      'mysql-slave:slave',
+  )