Revert "Remove vendored libjuju"

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

diff --git a/modules/libjuju/docs/narrative/controller.rst b/modules/libjuju/docs/narrative/controller.rst
new file mode 100644 (file)
index 0000000..1d86321
--- /dev/null
+++ b/modules/libjuju/docs/narrative/controller.rst
@@ -0,0 +1,92 @@
+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 py:doc:`model`).
+
+For API docs, see py:class:`juju.controller.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.
+
+.. code:: python
+
+  from juju.controller import Controller
+
+  controller = Controller()
+  await controller.connect()
+
+
+Connecting to a Named Controller
+--------------------------------
+Connect to a controller by name.
+
+.. code:: python
+
+  from juju.controller import Controller
+
+  controller = Controller()
+  await controller.connect('mycontroller')
+
+
+Connecting with Authentication
+------------------------------
+You can control what user you are connecting with by specifying either a
+username/password pair, or a macaroon or bakery client that can provide
+a macaroon.
+
+
+.. code:: python
+
+  controller = Controller()
+  await controller.connect(username='admin',
+                           password='f53f08cfc32a2e257fe5393271d89d62')
+
+  # or with a macaroon
+  await controller.connect(macaroons=[
+      {
+          "Name": "macaroon-218d87053ad19626bcd5a0eef0bc9ba8bd4fbd80a968f52a5fd430b2aa8660df",
+          "Value": "W3siY2F2ZWF0cyI6 ... jBkZiJ9XQ==",
+          "Domain": "10.130.48.27",
+          "Path": "/auth",
+          "Secure": false,
+          "HostOnly": true,
+          "Expires": "2018-03-07T22:07:23Z",
+      },
+  ])
+
+  # or with a bakery client
+  from macaroonbakery.httpbakery import Client
+  from http.cookiejar import FileCookieJar
+
+  bakery_client=Client()
+  bakery_client.cookies = FileCookieJar('cookies.txt')
+  controller = Controller()
+  await controller.connect(bakery_client=bakery_client)
+  
+
+
+Connecting with an Explicit Endpoint
+------------------------------------
+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.
+
+.. code:: python
+
+  controller = Controller()
+  await controller.connect(
+      endpoint='10.0.4.171:17070',
+      username='admin',
+      password='f53f08cfc32a2e257fe5393271d89d62',
+      cacert=None,  # Left out for brevity, but if you have a cert string you
+                    # should pass it in. You can get the cert from the output
+                    # of The `juju show-controller` command.
+  )