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 :doc:`model`).
  10
  11
  12 Connecting to the Current Controller
  13 ------------------------------------
  14 Connect to the currently active Juju controller (the one returned by
  15 `juju switch`). This only works if you have the Juju CLI client installed.
  16
  17 .. code:: python
  18
  19   from juju.controller import Controller
  20
  21   controller = Controller()
  22   await controller.connect_current()
  23
  24
  25 Connecting to a Named Controller
  26 --------------------------------
  27 Connect to a controller by name.
  28
  29 .. code:: python
  30
  31   from juju.controller import Controller
  32
  33   controller = Controller()
  34   await controller.connect_controller('mycontroller')
  35
  36
  37 Connecting with Username/Password Authentication
  38 ------------------------------------------------
  39 The most flexible, but also most verbose, way to connect is using the API
  40 endpoint url and credentials directly. This method does NOT require the Juju
  41 CLI client to be installed.
  42
  43 .. code:: python
  44
  45   from juju.controller import Controller
  46
  47   controller = Controller()
  48
  49   controller_endpoint = '10.0.4.171:17070'
  50   username = 'admin'
  51   password = 'f53f08cfc32a2e257fe5393271d89d62'
  52
  53   # Left out for brevity, but if you have a cert string you should pass it in.
  54   # You can copy the cert from the output of The `juju show-controller`
  55   # command.
  56   cacert = None
  57
  58   await controller.connect(
  59       controller_endpoint,
  60       username,
  61       password,
  62       cacert,
  63   )
  64
  65
  66 Connecting with Macaroon Authentication
  67 ---------------------------------------
  68 To connect to a shared controller, you'll need
  69 to use macaroon authentication. The simplest example is shown below, and uses
  70 already-discharged macaroons from the local filesystem. This will work if you
  71 have the Juju CLI installed.
  72
  73 .. note::
  74
  75   The library does not yet contain support for fetching and discharging
  76   macaroons. Until it does, if you want to use macaroon auth, you'll need
  77   to supply already-discharged macaroons yourself.
  78
  79 .. code:: python
  80
  81   from juju.client.connection import get_macaroons()
  82   from juju.controller import Controller
  83
  84   controller = Controller()
  85
  86   controller_endpoint = '10.0.4.171:17070'
  87   username = None
  88   password = None
  89   cacert = None
  90   macaroons = get_macaroons()
  91
  92   await controller.connect(
  93       controller_endpoint,
  94       username,
  95       password,
  96       cacert,
  97       macaroons,
  98   )