A Juju controller provides websocket endpoints for itself and each of its models. In order to do anything useful, the juju lib must connect to one of these endpoints.

Connecting to the controller endpoint is useful if you want to programmatically create a new model. If the model you want to use already exists, you can connect directly to it (see py:doc:model).

For API docs, see py:class:juju.controller.Controller.

Connecting to the Current Controller

Connect to the currently active Juju controller (the one returned by juju switch). This only works if you have the Juju CLI client installed.

from juju.controller import Controller

controller = Controller()
await controller.connect()

Connecting to a Named Controller

Connect to a controller by name.

from juju.controller import Controller

controller = Controller()
await controller.connect('mycontroller')

Connecting with Authentication

You can control what user you are connecting with by specifying either a username/password pair, or a macaroon or bakery client that can provide a macaroon.

controller = Controller()
await controller.connect(username='admin',

# or with a macaroon
await controller.connect(macaroons=[
        "Name": "macaroon-218d87053ad19626bcd5a0eef0bc9ba8bd4fbd80a968f52a5fd430b2aa8660df",
        "Value": "W3siY2F2ZWF0cyI6 ... jBkZiJ9XQ==",
        "Domain": "",
        "Path": "/auth",
        "Secure": false,
        "HostOnly": true,
        "Expires": "2018-03-07T22:07:23Z",

# or with a bakery client
from macaroonbakery.httpbakery import Client
from http.cookiejar import FileCookieJar

bakery_client.cookies = FileCookieJar('cookies.txt')
controller = Controller()
await controller.connect(bakery_client=bakery_client)

Connecting with an Explicit Endpoint

The most flexible, but also most verbose, way to connect is using the API endpoint url and credentials directly. This method does NOT require the Juju CLI client to be installed.

controller = Controller()
await controller.connect(
    cacert=None,  # Left out for brevity, but if you have a cert string you
                  # should pass it in. You can get the cert from the output
                  # of The `juju show-controller` command.