| Adam Israel | dcdf82b | 2017-08-15 15:26:43 -0400 | [diff] [blame] | 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 | For api docs, see :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_current() |
| 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_controller('mycontroller') |
| 37 | |
| 38 | |
| 39 | Connecting with Username/Password Authentication |
| 40 | ------------------------------------------------ |
| 41 | The most flexible, but also most verbose, way to connect is using the API |
| 42 | endpoint url and credentials directly. This method does NOT require the Juju |
| 43 | CLI client to be installed. |
| 44 | |
| 45 | .. code:: python |
| 46 | |
| 47 | from juju.controller import Controller |
| 48 | |
| 49 | controller = Controller() |
| 50 | |
| 51 | controller_endpoint = '10.0.4.171:17070' |
| 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 controller.connect( |
| 61 | controller_endpoint, |
| 62 | username, |
| 63 | password, |
| 64 | cacert, |
| 65 | ) |
| 66 | |
| 67 | |
| 68 | Connecting with Macaroon Authentication |
| 69 | --------------------------------------- |
| 70 | To connect to a shared controller, you'll need |
| 71 | to use macaroon authentication. The simplest example is shown below, and uses |
| 72 | already-discharged macaroons from the local filesystem. This will work if you |
| 73 | have the Juju CLI installed. |
| 74 | |
| 75 | .. note:: |
| 76 | |
| 77 | The library does not yet contain support for fetching and discharging |
| 78 | macaroons. Until it does, if you want to use macaroon auth, you'll need |
| 79 | to supply already-discharged macaroons yourself. |
| 80 | |
| 81 | .. code:: python |
| 82 | |
| 83 | from juju.client.connection import get_macaroons() |
| 84 | from juju.controller import Controller |
| 85 | |
| 86 | controller = Controller() |
| 87 | |
| 88 | controller_endpoint = '10.0.4.171:17070' |
| 89 | username = None |
| 90 | password = None |
| 91 | cacert = None |
| 92 | macaroons = get_macaroons() |
| 93 | |
| 94 | await controller.connect( |
| 95 | controller_endpoint, |
| 96 | username, |
| 97 | password, |
| 98 | cacert, |
| 99 | macaroons, |
| 100 | ) |