docs/narrative/model.rst

   1 Models
   2 ======
   3 A Juju controller provides websocket endpoints for each of its
   4 models. In order to do anything useful with a model, the juju lib must
   5 connect to one of these endpoints. There are several ways to do this.
   6
   7
   8 Connecting 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 Connecting 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 Connecting 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 Connecting 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   )
 104
 105
 106 Creating and Destroying a Model
 107 -------------------------------
 108 Example of creating a new model and then destroying it. See
 109 :meth:`juju.controller.Controller.add_model` and
 110 :meth:`juju.controller.Controller.destroy_model` for more info.
 111
 112 .. code:: python
 113
 114   from juju.controller import Controller
 115
 116   controller = Controller()
 117   await controller.connect_current()
 118
 119   # Create our new model
 120   model = await controller.add_model(
 121       'mymodel',  # name of your new model
 122   )
 123
 124   # Do stuff with our model...
 125
 126   # Destroy the model
 127   await model.disconnect()
 128   await controller.destroy_model(model.info.uuid)
 129   model = None