docs/narrative/connecting.rst

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