From 843e6a04a7f92cc7efdcc75ae0bb4be3fb0ca027 Mon Sep 17 00:00:00 2001 From: Tim Van Steenburgh Date: Tue, 13 Dec 2016 10:32:06 -0500 Subject: [PATCH] Docs --- docs/narrative/application.rst | 72 +++++++++++++++++++ ...{connect-controller.rst => controller.rst} | 22 +++--- docs/narrative/create-model.rst | 23 ------ docs/narrative/index.rst | 4 +- .../{connect-model.rst => model.rst} | 52 ++++++++++---- 5 files changed, 125 insertions(+), 48 deletions(-) create mode 100644 docs/narrative/application.rst rename docs/narrative/{connect-controller.rst => controller.rst} (84%) delete mode 100644 docs/narrative/create-model.rst rename docs/narrative/{connect-model.rst => model.rst} (66%) diff --git a/docs/narrative/application.rst b/docs/narrative/application.rst new file mode 100644 index 0000000..c255a37 --- /dev/null +++ b/docs/narrative/application.rst @@ -0,0 +1,72 @@ +Applications +============ + + +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, + }, + ) + + +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) diff --git a/docs/narrative/connect-controller.rst b/docs/narrative/controller.rst similarity index 84% rename from docs/narrative/connect-controller.rst rename to docs/narrative/controller.rst index ac62c1a..c6f4e0a 100644 --- a/docs/narrative/connect-controller.rst +++ b/docs/narrative/controller.rst @@ -1,16 +1,16 @@ -Connecting to a Controller -========================== +Controllers +=========== A Juju controller provides websocket endpoints for itself and each of its models. In order to do anything useful, the juju lib must connect to one of these endpoints. Connecting to the controller endpoint is useful if you want to programmatically create a new model. If the model you want to use already exists, you can -connect directly to it (see :doc:`connect-model`). +connect directly to it (see :doc:`model`). -To the Current Controller -------------------------- +Connecting to the Current Controller +------------------------------------ Connect to the currently active Juju controller (the one returned by `juju switch`). This only works if you have the Juju CLI client installed. @@ -22,8 +22,8 @@ Connect to the currently active Juju controller (the one returned by await controller.connect_current() -To a Named Controller ---------------------- +Connecting to a Named Controller +-------------------------------- Connect to a controller by name. .. code:: python @@ -34,8 +34,8 @@ Connect to a controller by name. await controller.connect_controller('mycontroller') -To an API Endpoint with Username/Password Authentication --------------------------------------------------------- +Connecting with Username/Password Authentication +------------------------------------------------ The most flexible, but also most verbose, way to connect is using the API endpoint url and credentials directly. This method does NOT require the Juju CLI client to be installed. @@ -63,8 +63,8 @@ CLI client to be installed. ) -To an API Endpoint with Macaroon Authentication ------------------------------------------------ +Connecting with Macaroon Authentication +--------------------------------------- To connect to a shared controller, you'll need to use macaroon authentication. The simplest example is shown below, and uses already-discharged macaroons from the local filesystem. This will work if you diff --git a/docs/narrative/create-model.rst b/docs/narrative/create-model.rst deleted file mode 100644 index b0cdbe7..0000000 --- a/docs/narrative/create-model.rst +++ /dev/null @@ -1,23 +0,0 @@ -Creating and Destroying a Model -=============================== -Example of creating a new model and then destroying it. See -:meth:`juju.controller.Controller.add_model` and -:meth:`juju.controller.Controller.destroy_model` for more info. - -.. code:: python - - from juju.controller import Controller - - controller = Controller() - await controller.connect_current() - - # Create our new model - model = await controller.add_model( - 'mymodel', # name of your new model - ) - - # Do stuff with our model... - - # Destroy the model - await model.disconnect() - await controller.destroy_model(model.info.uuid) diff --git a/docs/narrative/index.rst b/docs/narrative/index.rst index 47c2695..ac5b816 100644 --- a/docs/narrative/index.rst +++ b/docs/narrative/index.rst @@ -5,4 +5,6 @@ Narrative Docs :glob: :maxdepth: 2 - * + controller + model + application diff --git a/docs/narrative/connect-model.rst b/docs/narrative/model.rst similarity index 66% rename from docs/narrative/connect-model.rst rename to docs/narrative/model.rst index c9eea2c..c27179d 100644 --- a/docs/narrative/connect-model.rst +++ b/docs/narrative/model.rst @@ -1,12 +1,12 @@ -Connecting to a Model -===================== -A Juju controller provides websocket endpoints for itself and each of its -models. In order to do anything useful, the juju lib must connect to one of -these endpoints. There are several ways to do this. +Models +====== +A Juju controller provides websocket endpoints for each of its +models. In order to do anything useful with a model, the juju lib must +connect to one of these endpoints. There are several ways to do this. -To the Current Model --------------------- +Connecting to the Current Model +------------------------------- Connect to the currently active Juju model (the one returned by `juju switch`). This only works if you have the Juju CLI client installed. @@ -18,8 +18,8 @@ Connect to the currently active Juju model (the one returned by await model.connect_current() -To a Named Model ----------------- +Connecting to a Named Model +--------------------------- Connect to a model by name, using the same format as that returned from the `juju switch` command. The accepted format is '[controller:][user/]model'. This only works if you have the Juju CLI client installed. @@ -35,8 +35,8 @@ This only works if you have the Juju CLI client installed. await model.connect_model('juju-2.0.1:admin/libjuju') -To an API Endpoint with Username/Password Authentication --------------------------------------------------------- +Connecting with Username/Password Authentication +------------------------------------------------ The most flexible, but also most verbose, way to connect is using the API endpoint url and credentials directly. This method does NOT require the Juju CLI client to be installed. @@ -66,8 +66,8 @@ CLI client to be installed. ) -To an API Endpoint with Macaroon Authentication ------------------------------------------------ +Connecting with Macaroon Authentication +--------------------------------------- To connect to a shared model, or a model an a shared controller, you'll need to use macaroon authentication. The simplest example is shown below, and uses already-discharged macaroons from the local filesystem. This will work if you @@ -101,3 +101,29 @@ have the Juju CLI installed. cacert, macaroons, ) + + +Creating and Destroying a Model +------------------------------- +Example of creating a new model and then destroying it. See +:meth:`juju.controller.Controller.add_model` and +:meth:`juju.controller.Controller.destroy_model` for more info. + +.. code:: python + + from juju.controller import Controller + + controller = Controller() + await controller.connect_current() + + # Create our new model + model = await controller.add_model( + 'mymodel', # name of your new model + ) + + # Do stuff with our model... + + # Destroy the model + await model.disconnect() + await controller.destroy_model(model.info.uuid) + model = None -- 2.25.1