modules/libjuju/docs/narrative/controller.rst

   1 Controllers
   2 ===========
   3 A Juju controller provides websocket endpoints for itself and each of its
   4 models. In order to do anything useful, the juju lib must connect to one of
   5 these endpoints.
   6
   7 Connecting to the controller endpoint is useful if you want to programmatically
   8 create a new model. If the model you want to use already exists, you can
   9 connect directly to it (see py:doc:`model`).
  10
  11 For API docs, see py:class:`juju.controller.Controller`.
  12
  13
  14 Connecting to the Current Controller
  15 ------------------------------------
  16 Connect to the currently active Juju controller (the one returned by
  17 `juju switch`). This only works if you have the Juju CLI client installed.
  18
  19 .. code:: python
  20
  21   from juju.controller import Controller
  22
  23   controller = Controller()
  24   await controller.connect()
  25
  26
  27 Connecting to a Named Controller
  28 --------------------------------
  29 Connect to a controller by name.
  30
  31 .. code:: python
  32
  33   from juju.controller import Controller
  34
  35   controller = Controller()
  36   await controller.connect('mycontroller')
  37
  38
  39 Connecting with Authentication
  40 ------------------------------
  41 You can control what user you are connecting with by specifying either a
  42 username/password pair, or a macaroon or bakery client that can provide
  43 a macaroon.
  44
  45
  46 .. code:: python
  47
  48   controller = Controller()
  49   await controller.connect(username='admin',
  50                            password='f53f08cfc32a2e257fe5393271d89d62')
  51
  52   # or with a macaroon
  53   await controller.connect(macaroons=[
  54       {
  55           "Name": "macaroon-218d87053ad19626bcd5a0eef0bc9ba8bd4fbd80a968f52a5fd430b2aa8660df",
  56           "Value": "W3siY2F2ZWF0cyI6 ... jBkZiJ9XQ==",
  57           "Domain": "10.130.48.27",
  58           "Path": "/auth",
  59           "Secure": false,
  60           "HostOnly": true,
  61           "Expires": "2018-03-07T22:07:23Z",
  62       },
  63   ])
  64
  65   # or with a bakery client
  66   from macaroonbakery.httpbakery import Client
  67   from http.cookiejar import FileCookieJar
  68
  69   bakery_client=Client()
  70   bakery_client.cookies = FileCookieJar('cookies.txt')
  71   controller = Controller()
  72   await controller.connect(bakery_client=bakery_client)
  73
  74
  75
  76 Connecting with an Explicit Endpoint
  77 ------------------------------------
  78 The most flexible, but also most verbose, way to connect is using the API
  79 endpoint url and credentials directly. This method does NOT require the
  80 Juju CLI client to be installed.
  81
  82 .. code:: python
  83
  84   controller = Controller()
  85   await controller.connect(
  86       endpoint='10.0.4.171:17070',
  87       username='admin',
  88       password='f53f08cfc32a2e257fe5393271d89d62',
  89       cacert=None,  # Left out for brevity, but if you have a cert string you
  90                     # should pass it in. You can get the cert from the output
  91                     # of The `juju show-controller` command.
  92   )