Merge lp:~frankban/juju-quickstart/new-auth-api-endpoint into lp:juju-quickstart

[Francesco Banconi]

Add support for new Juju WebSocket API endpoints.

Recent Juju versions introduced a new API endpoint
path. In essence, instead of the usual
"wss://<address>:17070", the new
"wss://<address>:17070/environment/<env-uuid>/api"
is used to connect to the API.
This allows for connecting to a specific environment
in a multi-environment state server scenario.

In this branch the new API endpoint is used if a recent
Juju version is in use, and if it is possible to retrieve
the environment UUID from the jenv file.

Also, when connecting to the GUI server (for creating
the auth token or for deploying bundles), use the new
GUI server API endpoints when possible, i.e. when the
charm is recent enough to support redirecting requests
to the new Juju endpoints.
Note that this feature is assumed to land in the next
juju-gui charm release (see settings.py). If that's
not the case, we'll need to increase the charm revisions
in settings.MINIMUM_REVISIONS_FOR_NEW_API_ENDPOINT
before releasing the new Quickstart.

Tests: `make check`

QA:
- bootstrap quickstart as usual: `devenv/bin/juju-quickstart`;
- check that, if you are using juju devel (1.22beta), quickstart
  properly connect to the new API endpoint;
- run quickstart again to deploy a bundle, e.g.:
  `devenv/bin/juju-quickstart bundle:mediawiki/single`;
- ensure that the deployment request succeeds;
- if possible, do the above with and older version of Juju,
  to ensure backward compatibility.

Done, thank you!

https://codereview.appspot.com/199490043/

[Francesco Banconi (frankban)]

Reviewers: mp+249102_code.launchpad.net,

Message:
Please take a look.

Description:
Add support for new Juju WebSocket API endpoints.

Recent Juju versions introduced a new API endpoint
path. In essence, instead of the usual
"wss://<address>:17070", the new
"wss://<address>:17070/environment/<env-uuid>/api"
is used to connect to the API.
This allows for connecting to a specific environment
in a multi-environment state server scenario.

In this branch the new API endpoint is used if a recent
Juju version is in use, and if it is possible to retrieve
the environment UUID from the jenv file.

Also, when connecting to the GUI server (for creating
the auth token or for deploying bundles), use the new
GUI server API endpoints when possible, i.e. when the
charm is recent enough to support redirecting requests
to the new Juju endpoints.
Note that this feature is assumed to land in the next
juju-gui charm release (see settings.py). If that's
not the case, we'll need to increase the charm revisions
in settings.MINIMUM_REVISIONS_FOR_NEW_API_ENDPOINT
before releasing the new Quickstart.

Tests: `make check`

QA:
- bootstrap quickstart as usual: `devenv/bin/juju-quickstart`;
- check that, if you are using juju devel (1.22beta), quickstart
   properly connect to the new API endpoint;
- run quickstart again to deploy a bundle, e.g.:
   `devenv/bin/juju-quickstart bundle:mediawiki/single`;
- ensure that the deployment request succeeds;
- if possible, do the above with and older version of Juju,
   to ensure backward compatibility.

Done, thank you!

https://code.launchpad.net/~frankban/juju-quickstart/new-auth-api-endpoint/+merge/249102

(do not edit description out of merge proposal)

Please review this at https://codereview.appspot.com/199490043/

Affected files (+443, -91 lines):
   A [revision details]
   M quickstart/app.py
   M quickstart/jujutools.py
   M quickstart/manage.py
   M quickstart/models/charms.py
   M quickstart/models/jenv.py
   M quickstart/settings.py
   M quickstart/tests/helpers.py
   M quickstart/tests/models/test_charms.py
   M quickstart/tests/models/test_jenv.py
   M quickstart/tests/test_app.py
   M quickstart/tests/test_jujutools.py
   M quickstart/tests/test_manage.py

[Martin Hilton (martin-hilton)]

LGTM: No QA

https://codereview.appspot.com/199490043/diff/1/quickstart/app.py
File quickstart/app.py (right):

https://codereview.appspot.com/199490043/diff/1/quickstart/app.py#newcode283
quickstart/app.py:283: def get_env_uuid_or_none(env_name):
Is it really necessary to have or_none in the name of this function?

https://codereview.appspot.com/199490043/

[Jeff Pihach (hatch)]

LGTM with some possible cleanups.
QA OK!

https://codereview.appspot.com/199490043/diff/1/quickstart/app.py
File quickstart/app.py (right):

https://codereview.appspot.com/199490043/diff/1/quickstart/app.py#newcode283
quickstart/app.py:283: def get_env_uuid_or_none(env_name):
On 2015/02/10 10:47:32, martin.hilton wrote:
> Is it really necessary to have or_none in the name of this function?

+1

https://codereview.appspot.com/199490043/diff/1/quickstart/models/jenv.py
File quickstart/models/jenv.py (right):

https://codereview.appspot.com/199490043/diff/1/quickstart/models/jenv.py#newcode134
quickstart/models/jenv.py:134: data =
serializers.yaml_load_from_path(jenv_path)
I believe there are other places in the code which require information
from the jenv file so I figured that this would already be abstracted
out into a utility method already so you could just fetch the value.

https://codereview.appspot.com/199490043/

[Francesco Banconi (frankban)]

Thanks for the reviews!

https://codereview.appspot.com/199490043/diff/1/quickstart/app.py
File quickstart/app.py (right):

https://codereview.appspot.com/199490043/diff/1/quickstart/app.py#newcode283
quickstart/app.py:283: def get_env_uuid_or_none(env_name):
On 2015/02/10 10:47:32, martin.hilton wrote:
> Is it really necessary to have or_none in the name of this function?

Not strictly necessary, but in the caller context this can help: while
most of the times app functions return values, this can also return
none, i.e. do not rely on the fact the env uuid is always known.

https://codereview.appspot.com/199490043/diff/1/quickstart/models/jenv.py
File quickstart/models/jenv.py (right):

https://codereview.appspot.com/199490043/diff/1/quickstart/models/jenv.py#newcode134
quickstart/models/jenv.py:134: data =
serializers.yaml_load_from_path(jenv_path)
On 2015/02/10 15:12:09, jeff.pihach wrote:
> I believe there are other places in the code which require information
from the
> jenv file so I figured that this would already be abstracted out into
a utility
> method already so you could just fetch the value.

A slight refactor of the code in the jenv models can help, I agree.
On the other hand, the repeated code is still just two lines, so perhaps
not something for this branch.

https://codereview.appspot.com/199490043/

[Francesco Banconi (frankban)]

*** Submitted:

Add support for new Juju WebSocket API endpoints.

Recent Juju versions introduced a new API endpoint
path. In essence, instead of the usual
"wss://<address>:17070", the new
"wss://<address>:17070/environment/<env-uuid>/api"
is used to connect to the API.
This allows for connecting to a specific environment
in a multi-environment state server scenario.

In this branch the new API endpoint is used if a recent
Juju version is in use, and if it is possible to retrieve
the environment UUID from the jenv file.

Also, when connecting to the GUI server (for creating
the auth token or for deploying bundles), use the new
GUI server API endpoints when possible, i.e. when the
charm is recent enough to support redirecting requests
to the new Juju endpoints.
Note that this feature is assumed to land in the next
juju-gui charm release (see settings.py). If that's
not the case, we'll need to increase the charm revisions
in settings.MINIMUM_REVISIONS_FOR_NEW_API_ENDPOINT
before releasing the new Quickstart.

Tests: `make check`

QA:
- bootstrap quickstart as usual: `devenv/bin/juju-quickstart`;
- check that, if you are using juju devel (1.22beta), quickstart
   properly connect to the new API endpoint;
- run quickstart again to deploy a bundle, e.g.:
   `devenv/bin/juju-quickstart bundle:mediawiki/single`;
- ensure that the deployment request succeeds;
- if possible, do the above with and older version of Juju,
   to ensure backward compatibility.

Done, thank you!

R=martin.hilton, jeff.pihach
CC=
https://codereview.appspot.com/199490043

https://codereview.appspot.com/199490043/

=== modified file 'quickstart/app.py'
--- quickstart/app.py	2015-02-09 12:34:33 +0000
+++ quickstart/app.py	2015-02-09 18:28:10 +0000
@@ -180,9 +180,9 @@
 def check_bootstrapped(env_name):
     """Check if the environment named env_name is already bootstrapped.
 
-    If so, return the environment API URL to be used to connect to the Juju API
-    server. If not already bootstrapped, or if the API URL cannot be retrieved,
-    return None.
+    If so, return the environment API address to be used to connect to the Juju
+    API server. If not already bootstrapped, or if the API address cannot be
+    retrieved, return None.
     """
     if not jenv.exists(env_name):
         return None
@@ -190,20 +190,21 @@
     try:
         candidates = jenv.get_value(env_name, 'state-servers')
     except ValueError as err:
-        logging.warn(b'cannot retrieve the Juju API URL: {}'.format(err))
+        logging.warn(b'cannot retrieve the Juju API address: {}'.format(err))
         return None
-    # Look for a reachable API URL.
+    # Look for a reachable API address.
     if not candidates:
-        logging.warn('cannot retrieve the Juju API URL: no addresses found')
+        logging.warn(
+            'cannot retrieve the Juju API address: no addresses found')
         return None
     for candidate in candidates:
         error = netutils.check_listening(candidate)
         if error is None:
-            # Juju API URL found.
-            return 'wss://{}'.format(candidate)
+            # Juju API address found.
+            return candidate
         logging.debug(error)
     logging.warn(
-        'cannot retrieve the Juju API URL: cannot connect to any of the '
+        'cannot retrieve the Juju API address: cannot connect to any of the '
         'following addresses: {}'.format(', '.join(candidates)))
     return None
 
@@ -279,6 +280,21 @@
     raise ProgramExit('the state server is not ready:\n{}'.format(details))
 
 
+def get_env_uuid_or_none(env_name):
+    """Return the Juju environment unique id for the given environment name.
+
+    Parse the jenv file to retrieve the environment UUID.
+
+    Return None if the environment UUID is not present in the jenv file.
+    Raise a ProgramExit if the jenv file is not valid.
+    """
+    try:
+        return jenv.get_env_uuid(env_name)
+    except ValueError as err:
+        msg = b'cannot retrieve environment unique identifier: {}'.format(err)
+        raise ProgramExit(msg)
+
+
 def get_credentials(env_name):
     """Return the Juju credentials for the given environment name.
 
@@ -292,11 +308,13 @@
         raise ProgramExit(msg)
 
 
-def get_api_url(env_name, juju_command):
-    """Return a Juju API URL for the given environment name.
+def get_api_address(env_name, juju_command):
+    """Return a Juju API address for the given environment name.
+
+    Only the address is returned, without the schema or the path. For instance:
+    "api.example.com:17070".
 
     Use the Juju CLI in a subprocess in order to retrieve the API addresses.
-    Return the complete URL, e.g. "wss://api.example.com:17070".
     Raise a ProgramExit if any error occurs.
     """
     retcode, output, error = utils.call(
@@ -305,8 +323,7 @@
         raise ProgramExit(error)
     # Assuming there is always at least one API address, grab the first one
     # from the JSON output.
-    api_address = json.loads(output)[0]
-    return 'wss://{}'.format(api_address)
+    return json.loads(output)[0]
 
 
 def connect(api_url, username, password):
@@ -391,7 +408,8 @@
     default charm URL is used if the charm store service is not available.
 
     Return a tuple including the following values:
-        - charm_url: the charm URL that will be used to deploy the service;
+        - charm: the charm that will be used to deploy the service, as an
+          instance of "quickstart.models.charms.Charm";
         - machine: the machine where to deploy to (e.g. "0") or None if a new
           machine must be created;
         - service_data: the service info as returned by the mega-watcher for
@@ -442,7 +460,7 @@
         (charm.series == bootstrap_node_series)
     ):
         machine = '0'
-    return charm_url, machine, service_data, unit_data
+    return charm, machine, service_data, unit_data
 
 
 def deploy_gui(env, service_name, charm_url, machine, service_data, unit_data):
@@ -572,9 +590,8 @@
 def deploy_bundle(env, bundle_yaml, bundle_name, bundle_id):
     """Deploy a bundle.
 
-    Receive an API URL to a WebSocket server supporting bundle deployments, the
-    admin_secret to use in the authentication process, the bundle YAML encoded
-    contents and the bundle name to be imported.
+    Receive the environment connection to use for deploying the bundle, the
+    bundle YAML encoded contents, the bundle name to be imported and its id.
 
     Raise a ProgramExit if the API server returns an error response.
     """

=== modified file 'quickstart/jujutools.py'
--- quickstart/jujutools.py	2015-02-09 12:58:04 +0000
+++ quickstart/jujutools.py	2015-02-09 18:28:10 +0000
@@ -30,6 +30,47 @@
 from quickstart.models import charms
 
 
+def get_api_url(api_address, juju_version, env_uuid, prefix='', charm=None):
+    """Return the Juju WebSocket API endpoint.
+
+    Receives the Juju API server address, the Juju version and the unique
+    identifier of the current environment.
+
+    Optionally receive a prefix to be used in the path.
+
+    Optionally also receive the Juju GUI charm object as an instance of
+    "quickstart.models.charms.Charm". If provided, the function checks that
+    the specified Juju GUI charm supports the new Juju API endpoint.
+    If not supported, the old endpoint is returned.
+
+    The environment UUID can be None, in which case the old-style API URL
+    (not including the environment UUID) is returned.
+    """
+    base_url = 'wss://{}'.format(api_address)
+    prefix = prefix.strip('/')
+    if prefix:
+        base_url = '{}/{}'.format(base_url, prefix)
+    if (env_uuid is None) or (juju_version < (1, 22, 0)):
+        return base_url
+    complete_url = '{}/environment/{}/api'.format(base_url, env_uuid)
+    if charm is None:
+        return complete_url
+    # If a customized Juju GUI charm is in use, there is no way to check if the
+    # GUI server is recent enough to support the new Juju API endpoints.
+    # In these cases, assume the customized charm is recent enough.
+    if (
+        charm.name != settings.JUJU_GUI_CHARM_NAME or
+        charm.user or
+        charm.is_local()
+    ):
+        return complete_url
+    # This is the promulgated Juju GUI charm. Check if it supports new APIs.
+    revision, series = charm.revision, charm.series
+    if revision < settings.MINIMUM_REVISIONS_FOR_NEW_API_ENDPOINT[series]:
+        return base_url
+    return complete_url
+
+
 def get_service_info(status, service_name):
     """Retrieve information on the given service and on its first alive unit.
 
@@ -62,7 +103,7 @@
     Print (to stdout or to logs) info and warnings about the charm URL.
 
     Return the parsed charm object as an instance of
-    quickstart.models.charms.Charm.
+    "quickstart.models.charms.Charm".
     """
     print('charm URL: {}'.format(charm_url))
     charm = charms.Charm.from_url(charm_url)

=== modified file 'quickstart/manage.py'
--- quickstart/manage.py	2015-02-09 12:58:04 +0000
+++ quickstart/manage.py	2015-02-09 18:28:10 +0000
@@ -32,6 +32,7 @@
 import quickstart
 from quickstart import (
     app,
+    jujutools,
     netutils,
     packaging,
     platform_support,
@@ -526,8 +527,8 @@
     # Bootstrap the Juju environment or reuse an already bootstrapped one.
     already_bootstrapped = True
     env_type = options.env_type
-    api_url = app.check_bootstrapped(options.env_name)
-    if api_url is None:
+    api_address = app.check_bootstrapped(options.env_name)
+    if api_address is None:
         print('bootstrapping the {} environment'.format(options.env_name))
         if env_type == 'local':
             # If this is a local environment, notify the user that "sudo" will
@@ -551,9 +552,15 @@
 
     # If the environment was not already bootstrapped, we need to retrieve
     # the API address.
-    if api_url is None:
+    if api_address is None:
         print('retrieving the Juju API address')
-        api_url = app.get_api_url(options.env_name, juju_command)
+        api_address = app.get_api_address(options.env_name, juju_command)
+
+    # Retrieve the Juju environment unique identifier.
+    env_uuid = app.get_env_uuid_or_none(options.env_name)
+
+    # Build the Juju API endpoint based on the Juju version and environment id.
+    api_url = jujutools.get_api_url(api_address, juju_version, env_uuid)
 
     # Retrieve the admin-secret for the current environment.
     print('retrieving the Juju environment credentials')
@@ -571,21 +578,26 @@
     print('environment type: {}'.format(env_type))
 
     # Inspect the environment and deploy the charm if required.
-    charm_url, machine, service_data, unit_data = app.check_environment(
+    charm, machine, service_data, unit_data = app.check_environment(
         env, settings.JUJU_GUI_SERVICE_NAME, options.charm_url,
         env_type, bootstrap_node_series, already_bootstrapped)
     unit_name = app.deploy_gui(
-        env, settings.JUJU_GUI_SERVICE_NAME, charm_url, machine,
+        env, settings.JUJU_GUI_SERVICE_NAME, charm.url(), machine,
         service_data, unit_data)
 
     # Observe the deployment progress.
     address = app.watch(env, unit_name)
     env.close()
+
+    # Print out Juju GUI unit and credential information.
     url = 'https://{}'.format(address)
     print('\nJuju GUI URL: {}\nusername: {}\npassword: {}\n'.format(
         url, username, password))
-    gui_api_url = 'wss://{}:443/ws'.format(address)
+
+    # Connect to the GUI server WebSocket API.
     print('connecting to the Juju GUI server')
+    gui_api_url = jujutools.get_api_url(
+        address + ':443', juju_version, env_uuid, prefix='ws', charm=charm)
     gui_env = app.connect(gui_api_url, username, password)
 
     # Handle bundle deployment.

=== modified file 'quickstart/models/charms.py'
--- quickstart/models/charms.py	2013-12-06 17:17:19 +0000
+++ quickstart/models/charms.py	2015-02-09 18:28:10 +0000
@@ -118,6 +118,10 @@
     def __repr__(self):
         return b'<Charm: {}>'.format(bytes(self))
 
+    def __eq__(self, other):
+        """Two charms are equal if they have the same URL."""
+        return isinstance(other, self.__class__) and self.url() == other.url()
+
     def url(self):
         """Return the charm URL."""
         user_part = '~{}/'.format(self.user) if self.user else ''

=== modified file 'quickstart/models/jenv.py'
--- quickstart/models/jenv.py	2015-01-12 12:10:38 +0000
+++ quickstart/models/jenv.py	2015-02-09 18:28:10 +0000
@@ -122,6 +122,23 @@
     return username, password
 
 
+def get_env_uuid(env_name):
+    """Return the Juju environment unique identifier.
+
+    Return None if the environment UUID is not included in the jenv file.
+    Raise a ValueError if:
+        - the environment file is not found;
+        - the environment file contents are not parsable by YAML.
+    """
+    jenv_path = _get_jenv_path(env_name)
+    data = serializers.yaml_load_from_path(jenv_path)
+    try:
+        return _get_value_from_yaml(data, 'environ-uuid')
+    except ValueError:
+        # This is probably an old version of Juju.
+        return None
+
+
 def get_env_db():
     """Return an environment database parsing the existing jenv files.
 

=== modified file 'quickstart/settings.py'
--- quickstart/settings.py	2015-01-12 15:07:51 +0000
+++ quickstart/settings.py	2015-02-09 18:28:10 +0000
@@ -40,8 +40,8 @@
 # temporary connection/charm store errors.
 # Keep this list sorted by release date (older first).
 DEFAULT_CHARM_URLS = collections.OrderedDict((
-    ('precise', 'cs:precise/juju-gui-104'),
-    ('trusty', 'cs:trusty/juju-gui-16'),
+    ('precise', 'cs:precise/juju-gui-106'),
+    ('trusty', 'cs:trusty/juju-gui-18'),
 ))
 
 # The quickstart app short description.
@@ -88,3 +88,9 @@
 # supported series. Assume not listed series to always support bundles.
 MINIMUM_REVISIONS_FOR_BUNDLES = collections.defaultdict(
     lambda: 0, {'precise': 80})
+
+# The minimum Juju GUI charm revision supporting the new Juju API endpoints
+# including the environment UUID. Assume not listed series to always support
+# new endpoints.
+MINIMUM_REVISIONS_FOR_NEW_API_ENDPOINT = collections.defaultdict(
+    lambda: 0, {'precise': 107, 'trusty': 19})

=== modified file 'quickstart/tests/helpers.py'
--- quickstart/tests/helpers.py	2014-12-17 11:47:43 +0000
+++ quickstart/tests/helpers.py	2015-02-09 18:28:10 +0000
@@ -143,6 +143,7 @@
     jenv_data = {
         'user': 'admin',
         'password': 'Secret!',
+        'environ-uuid': '__unique_identifier__',
         'state-servers': ['localhost:17070', '10.0.3.1:17070'],
         'bootstrap-config': {
             'admin-secret': 'Secret!',

=== modified file 'quickstart/tests/models/test_charms.py'
--- quickstart/tests/models/test_charms.py	2013-12-06 17:17:19 +0000
+++ quickstart/tests/models/test_charms.py	2015-02-09 18:28:10 +0000
@@ -205,3 +205,31 @@
         # The is_local method returns True for local charms.
         charm = self.make_charm(schema='local')
         self.assertTrue(charm.is_local())
+
+    def test_equality(self):
+        # Two charms are equal if they have the same URL.
+        self.assertEqual(self.make_charm(), self.make_charm())
+
+    def test_equality_different_name(self):
+        # Two charms with different names are not equal.
+        self.assertNotEqual(
+            self.make_charm(name='django'),
+            self.make_charm(name='rails'))
+
+    def test_equality_different_revision(self):
+        # Two charms with different revisions are not equal.
+        self.assertNotEqual(
+            self.make_charm(revision=0),
+            self.make_charm(revision=1))
+
+    def test_equality_different_user(self):
+        # Two charms with different users are not equal.
+        self.assertNotEqual(
+            self.make_charm(user=''),
+            self.make_charm(user='who'))
+
+    def test_equality_different_types(self):
+        # A charm never equals a non-charm object.
+        self.assertNotEqual(self.make_charm(), 42)
+        self.assertNotEqual(self.make_charm(), True)
+        self.assertNotEqual(self.make_charm(), 'oranges')

=== modified file 'quickstart/tests/models/test_jenv.py'
--- quickstart/tests/models/test_jenv.py	2015-01-13 11:46:06 +0000
+++ quickstart/tests/models/test_jenv.py	2015-02-09 18:28:10 +0000
@@ -168,6 +168,30 @@
                 jenv.get_credentials('local')
 
 
+class TestGetEnvUuid(helpers.JenvFileTestsMixin, unittest.TestCase):
+
+    def test_uuid_found(self):
+        # The environment UUID is correctly returned when included in the jenv.
+        with self.make_jenv('local', yaml.safe_dump(self.jenv_data)):
+            env_uuid = jenv.get_env_uuid('local')
+        self.assertEqual('__unique_identifier__', env_uuid)
+
+    def test_uuid_not_found(self):
+        # None is returned if the environment UUID is not present in the jenv.
+        data = {'user': 'jean-luc', 'password': 'Secret!'}
+        with self.make_jenv('local', yaml.safe_dump(data)):
+            env_uuid = jenv.get_env_uuid('local')
+        self.assertIsNone(env_uuid)
+
+    def test_invalid_jenv(self):
+        # A ValueError is raised if there are errors parsing the jenv file.
+        expected_error = 'unable to parse file'
+        with self.make_jenv('ec2', ':'):
+            with self.assertRaises(ValueError) as context_manager:
+                jenv.get_env_uuid('ec2')
+        self.assertIn(expected_error, bytes(context_manager.exception))
+
+
 class TestGetEnvDb(helpers.JenvFileTestsMixin, unittest.TestCase):
 
     def test_no_juju_home(self):

=== modified file 'quickstart/tests/test_app.py'
--- quickstart/tests/test_app.py	2015-01-12 15:00:52 +0000
+++ quickstart/tests/test_app.py	2015-02-09 18:28:10 +0000
@@ -20,6 +20,7 @@
 
 from contextlib import contextmanager
 import json
+import os
 import unittest
 
 import jujuclient
@@ -31,6 +32,7 @@
     platform_support,
     settings,
 )
+from quickstart.models import charms
 from quickstart.tests import helpers
 
 
@@ -457,56 +459,56 @@
 class TestCheckBootstrapped(helpers.JenvFileTestsMixin, unittest.TestCase):
 
     def test_no_jenv_file(self):
-        # A None API URL is returned if the jenv file is not present.
+        # A None API address is returned if the jenv file is not present.
         with self.make_jenv('ec2', ''):
             with helpers.assert_logs([], level='warn'):
-                api_url = app.check_bootstrapped('hp')
-        self.assertIsNone(api_url)
+                api_address = app.check_bootstrapped('hp')
+        self.assertIsNone(api_address)
 
     def test_invalid_jenv_file(self):
-        # A None API URL is returned if the list of API addresses cannot be
+        # A None API address is returned if the list of API addresses cannot be
         # retrieved from the jenv file.
         with self.make_jenv('ec2', '') as path:
             logs = [
-                'cannot retrieve the Juju API URL: '
+                'cannot retrieve the Juju API address: '
                 'cannot read {}: invalid YAML contents: '
                 'state-servers key not found in the root section'.format(path)
             ]
             with helpers.assert_logs(logs, level='warn'):
-                api_url = app.check_bootstrapped('ec2')
-        self.assertIsNone(api_url)
+                api_address = app.check_bootstrapped('ec2')
+        self.assertIsNone(api_address)
 
     def test_no_api_addresses(self):
-        # A None API URL is returned if the list of API addresses is empty.
+        # A None API address is returned if the list of API addresses is empty.
         jenv_data = {'state-servers': []}
-        logs = ['cannot retrieve the Juju API URL: no addresses found']
+        logs = ['cannot retrieve the Juju API address: no addresses found']
         with self.make_jenv('local', yaml.safe_dump(jenv_data)):
             with helpers.assert_logs(logs, level='warn'):
-                api_url = app.check_bootstrapped('local')
-        self.assertIsNone(api_url)
+                api_address = app.check_bootstrapped('local')
+        self.assertIsNone(api_address)
 
     def test_api_address_not_listening(self):
-        # A None API URL is returned if there is no reachable API address.
+        # A None API address is returned if there is no reachable API address.
         logs = [
-            'cannot retrieve the Juju API URL: '
+            'cannot retrieve the Juju API address: '
             'cannot connect to any of the following addresses: '
             'localhost:17070, 10.0.3.1:17070'
         ]
         with self.make_jenv('local', yaml.safe_dump(self.jenv_data)):
             with helpers.assert_logs(logs, level='warn'):
                 with helpers.patch_socket_create_connection('bad wolf'):
-                    api_url = app.check_bootstrapped('local')
-        self.assertIsNone(api_url)
+                    api_address = app.check_bootstrapped('local')
+        self.assertIsNone(api_address)
 
     def test_bootstrapped(self):
-        # The first listening API URL is returned if the environment is already
-        # bootstrapped.
+        # The first listening API address is returned if the environment is
+        # already bootstrapped.
         with self.make_jenv('hp', yaml.safe_dump(self.jenv_data)):
             with helpers.assert_logs([], level='warn'):
                 with helpers.patch_socket_create_connection():
-                    api_url = app.check_bootstrapped('hp')
+                    api_address = app.check_bootstrapped('hp')
         # The first API address is returned.
-        self.assertEqual('wss://localhost:17070', api_url)
+        self.assertEqual('localhost:17070', api_address)
 
 
 class TestBootstrap(
@@ -700,6 +702,34 @@
         mock_call.assert_has_calls(expected_calls)
 
 
+class TestGetEnvUuidOrNone(
+        helpers.JenvFileTestsMixin, ProgramExitTestsMixin, unittest.TestCase):
+
+    def test_success(self):
+        # The environment UUID is successfully retrieved.
+        with self.make_jenv('ec2', yaml.safe_dump(self.jenv_data)):
+            env_uuid = app.get_env_uuid_or_none('ec2')
+        self.assertEqual('__unique_identifier__', env_uuid)
+
+    def test_no_uuid(self):
+        # None is returned if the environment UUID is not found.
+        data = {'user': 'jean-luc', 'password': 'Secret!'}
+        with self.make_jenv('ec2', yaml.safe_dump(data)):
+            env_uuid = app.get_env_uuid_or_none('ec2')
+        self.assertIsNone(env_uuid)
+
+    def test_error(self):
+        # A ProgramExit is raised if the environment UUID cannot be retrieved.
+        with self.make_jenv('ec2', '') as path:
+            os.remove(path)
+            expected_error = (
+                'cannot retrieve environment unique identifier: unable to '
+                "open file {}: [Errno 2] No such file or directory: '{}'"
+                ''.format(path, path))
+            with self.assert_program_exit(expected_error):
+                app.get_env_uuid_or_none('ec2')
+
+
 class TestGetCredentials(
         helpers.JenvFileTestsMixin, ProgramExitTestsMixin, unittest.TestCase):
 
@@ -722,27 +752,27 @@
                 app.get_credentials('ec2')
 
 
-class TestGetApiUrl(
+class TestGetApiAddress(
         helpers.CallTestsMixin, ProgramExitTestsMixin, unittest.TestCase):
 
     env_name = 'ec2'
     juju_command = settings.JUJU_CMD_PATHS['default']
 
     def test_success(self):
-        # The API URL is correctly returned.
+        # The API address is correctly returned.
         api_addresses = json.dumps(['api.example.com:17070', 'not-today'])
         with self.patch_call(retcode=0, output=api_addresses) as mock_call:
-            api_url = app.get_api_url(self.env_name, self.juju_command)
-        self.assertEqual('wss://api.example.com:17070', api_url)
+            api_address = app.get_api_address(self.env_name, self.juju_command)
+        self.assertEqual('api.example.com:17070', api_address)
         mock_call.assert_called_once_with(
             self.juju_command, 'api-endpoints', '-e', self.env_name,
             '--format', 'json')
 
     def test_failure(self):
-        # A ProgramExit is raised if an error occurs retrieving the API URL.
+        # A ProgramExit is raised if an error occurs retrieving the address.
         with self.patch_call(retcode=1, error='bad wolf') as mock_call:
             with self.assert_program_exit('bad wolf'):
-                app.get_api_url(self.env_name, self.juju_command)
+                app.get_api_address(self.env_name, self.juju_command)
         mock_call.assert_called_once_with(
             self.juju_command, 'api-endpoints', '-e', self.env_name,
             '--format', 'json')
@@ -904,6 +934,11 @@
         return mock.patch(
             'quickstart.netutils.get_charm_url', mock_get_charm_url)
 
+    def assert_charm_equal(self, expected_url, charm):
+        """Ensure the given charm has the expected URL."""
+        expected_charm = charms.Charm.from_url(expected_url)
+        self.assertEqual(expected_charm, charm)
+
     def test_environment_just_bootstrapped(self, mock_print):
         # The function correctly retrieves the charm URL and machine, and
         # handles the case when the charm URL is not provided by the user.
@@ -917,14 +952,14 @@
         check_preexisting = False
         with self.patch_get_charm_url(
                 return_value='cs:trusty/juju-gui-42') as mock_get_charm_url:
-            url, machine, service_data, unit_data = app.check_environment(
+            charm, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # There is no need to call status if the environment was just created.
         self.assertFalse(env.get_status.called)
         # The charm URL has been retrieved from the charm store API based on
         # the current bootstrap node series.
-        self.assertEqual('cs:trusty/juju-gui-42', url)
+        self.assert_charm_equal('cs:trusty/juju-gui-42', charm)
         mock_get_charm_url.assert_called_once_with(bootstrap_node_series)
         # Since the bootstrap node series is supported by the GUI charm, the
         # GUI unit can be deployed to machine 0.
@@ -952,14 +987,14 @@
         check_preexisting = True
         with self.patch_get_charm_url(
                 return_value='cs:precise/juju-gui-42') as mock_get_charm_url:
-            url, machine, service_data, unit_data = app.check_environment(
+            charm, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # The environment status has been retrieved.
         env.get_status.assert_called_once_with()
         # The charm URL has been retrieved from the charm store API based on
         # the current bootstrap node series.
-        self.assertEqual('cs:precise/juju-gui-42', url)
+        self.assert_charm_equal('cs:precise/juju-gui-42', charm)
         mock_get_charm_url.assert_called_once_with(bootstrap_node_series)
         # Since the bootstrap node series is supported by the GUI charm, the
         # GUI unit can be deployed to machine 0.
@@ -984,13 +1019,13 @@
         bootstrap_node_series = 'precise'
         check_preexisting = True
         with self.patch_get_charm_url() as mock_get_charm_url:
-            url, machine, service_data, unit_data = app.check_environment(
+            charm, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # The environment status has been retrieved.
         env.get_status.assert_called_once_with()
         # The charm URL has been retrieved from the environment.
-        self.assertEqual('cs:precise/juju-gui-47', url)
+        self.assert_charm_equal('cs:precise/juju-gui-47', charm)
         self.assertFalse(mock_get_charm_url.called)
         # Since the bootstrap node series is supported by the GUI charm, the
         # GUI unit can be safely deployed to machine 0.
@@ -1009,12 +1044,12 @@
         check_preexisting = False
         with self.patch_get_charm_url(
                 return_value='cs:trusty/juju-gui-42') as mock_get_charm_url:
-            url, machine, service_data, unit_data = app.check_environment(
+            charm, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # The charm URL has been retrieved from the charm store API using the
         # most recent supported series.
-        self.assertEqual('cs:trusty/juju-gui-42', url)
+        self.assert_charm_equal('cs:trusty/juju-gui-42', charm)
         mock_get_charm_url.assert_called_once_with('trusty')
         # The Juju GUI unit cannot be deployed to saucy machine 0.
         self.assertIsNone(machine)
@@ -1034,11 +1069,11 @@
         bootstrap_node_series = 'trusty'
         check_preexisting = False
         with self.patch_get_charm_url(return_value='cs:trusty/juju-gui-42'):
-            url, machine, service_data, unit_data = app.check_environment(
+            charm, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # The charm URL has been correctly retrieved from the charm store API.
-        self.assertEqual('cs:trusty/juju-gui-42', url)
+        self.assert_charm_equal('cs:trusty/juju-gui-42', charm)
         # The Juju GUI unit cannot be deployed to localhost.
         self.assertIsNone(machine)
 
@@ -1051,7 +1086,7 @@
         bootstrap_node_series = 'trusty'
         check_preexisting = False
         with self.patch_get_charm_url(return_value='cs:trusty/juju-gui-42'):
-            url, machine, service_data, unit_data = app.check_environment(
+            _, machine, _, _ = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         self.assertIsNone(machine)
@@ -1065,11 +1100,11 @@
         bootstrap_node_series = 'precise'
         check_preexisting = False
         with self.patch_get_charm_url(side_effect=IOError('boo!')):
-            url, machine, service_data, unit_data = app.check_environment(
+            charm, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # The default charm URL for the given series is returned.
-        self.assertEqual(settings.DEFAULT_CHARM_URLS['precise'], url)
+        self.assert_charm_equal(settings.DEFAULT_CHARM_URLS['precise'], charm)
         self.assertEqual('0', machine)
 
     def test_most_recent_default_charm_url(self, mock_print):
@@ -1082,12 +1117,12 @@
         bootstrap_node_series = 'saucy'
         check_preexisting = False
         with self.patch_get_charm_url(side_effect=IOError('boo!')):
-            url, machine, service_data, unit_data = app.check_environment(
+            charm, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # The default charm URL for the given series is returned.
         series = settings.JUJU_GUI_SUPPORTED_SERIES[-1]
-        self.assertEqual(settings.DEFAULT_CHARM_URLS[series], url)
+        self.assert_charm_equal(settings.DEFAULT_CHARM_URLS[series], charm)
         self.assertIsNone(machine)
 
     def test_charm_url_provided(self, mock_print):
@@ -1099,14 +1134,14 @@
         bootstrap_node_series = 'trusty'
         check_preexisting = False
         with self.patch_get_charm_url() as mock_get_charm_url:
-            url, machine, service_data, unit_data = app.check_environment(
+            charm, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # There is no need to call the charmword API if the charm URL is
         # provided by the user.
         self.assertFalse(mock_get_charm_url.called)
         # The provided charm URL has been correctly returned.
-        self.assertEqual(charm_url, url)
+        self.assert_charm_equal(charm_url, charm)
         # Since the provided charm series is trusty, the charm itself can be
         # safely deployed to machine 0.
         self.assertEqual('0', machine)
@@ -1126,14 +1161,14 @@
         bootstrap_node_series = 'precise'
         check_preexisting = False
         with self.patch_get_charm_url() as mock_get_charm_url:
-            url, machine, service_data, unit_data = app.check_environment(
+            charm, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # There is no need to call the charmword API if the charm URL is
         # provided by the user.
         self.assertFalse(mock_get_charm_url.called)
         # The provided charm URL has been correctly returned.
-        self.assertEqual(charm_url, url)
+        self.assert_charm_equal(charm_url, charm)
         # Since the provided charm series is not precise, the charm must be
         # deployed to a new machine.
         self.assertIsNone(machine)

=== modified file 'quickstart/tests/test_jujutools.py'
--- quickstart/tests/test_jujutools.py	2015-02-09 12:58:04 +0000
+++ quickstart/tests/test_jujutools.py	2015-02-09 18:28:10 +0000
@@ -28,6 +28,124 @@
 from quickstart.tests import helpers
 
 
+class TestGetApiUrl(unittest.TestCase):
+
+    def test_new_url(self):
+        # The new Juju API endpoint is returned if a recent Juju is used.
+        url = jujutools.get_api_url('1.2.3.4:17070', (1, 22, 0), 'env-uuid')
+        self.assertEqual('wss://1.2.3.4:17070/environment/env-uuid/api', url)
+
+    def test_new_url_with_prefix(self):
+        # The new Juju API endpoint is returned with the given path prefix.
+        url = jujutools.get_api_url(
+            '1.2.3.4:17070', (1, 22, 0), 'env-uuid', prefix='/my/path/')
+        self.assertEqual(
+            'wss://1.2.3.4:17070/my/path/environment/env-uuid/api', url)
+
+    def test_old_juju(self):
+        # The old Juju API endpoint is returned if the Juju in use is not a
+        # recent version.
+        url = jujutools.get_api_url('1.2.3.4:17070', (1, 21, 7), 'env-uuid')
+        self.assertEqual('wss://1.2.3.4:17070', url)
+
+    def test_old_juju_with_prefix(self):
+        # The old Juju API endpoint is returned with the given path prefix.
+        url = jujutools.get_api_url(
+            '1.2.3.4:8888', (1, 21, 7), 'env-uuid', 'proxy/')
+        self.assertEqual('wss://1.2.3.4:8888/proxy', url)
+
+    def test_no_env_uuid(self):
+        # The old Juju API endpoint is returned if the environment unique
+        # identifier is unreachable.
+        url = jujutools.get_api_url('1.2.3.4:17070', (1, 23, 42), None)
+        self.assertEqual('wss://1.2.3.4:17070', url)
+
+    def test_no_env_uuid_with_prefix(self):
+        # The old Juju API endpoint is returned with the given path prefix.
+        url = jujutools.get_api_url(
+            '1.2.3.4:17070', (1, 23, 42), None, 'my/prefix')
+        self.assertEqual('wss://1.2.3.4:17070/my/prefix', url)
+
+    def test_new_charm_old_juju(self):
+        # The old Juju API endpoints are used if and old version of Juju is in
+        # use, even if the Juju GUI charm is recent.
+        charm = charms.Charm.from_url('cs:trusty/juju-gui-42')
+        url = jujutools.get_api_url(
+            '1.2.3.4:5678', (1, 21, 7), 'env-uuid', charm=charm)
+        self.assertEqual('wss://1.2.3.4:5678', url)
+
+    def test_customized_charm_unexpected_name(self):
+        # If a customized Juju GUI charm is used, then we assume it supports
+        # the new Juju Login API endpoint (unexpected charm name).
+        charm = charms.Charm.from_url('cs:trusty/the-amazing-gui-0')
+        url = jujutools.get_api_url(
+            'example.com:17070', (1, 22, 2), 'uuid', charm=charm)
+        self.assertEqual('wss://example.com:17070/environment/uuid/api', url)
+
+    def test_customized_charm_unexpected_user(self):
+        # If a customized Juju GUI charm is used, then we assume it supports
+        # the new Juju Login API endpoint (unexpected charm user).
+        charm = charms.Charm.from_url('cs:~who/trusty/juju-gui-0')
+        url = jujutools.get_api_url(
+            'example.com:17070', (1, 22, 2), 'uuid', charm=charm)
+        self.assertEqual('wss://example.com:17070/environment/uuid/api', url)
+
+    def test_customized_charm_unexpected_schema(self):
+        # If a customized Juju GUI charm is used, then we assume it supports
+        # the new Juju Login API endpoint (local charm).
+        charm = charms.Charm.from_url('local:precise/juju-gui-0')
+        url = jujutools.get_api_url(
+            'example.com:17070', (1, 22, 2), 'uuid', prefix='/', charm=charm)
+        self.assertEqual('wss://example.com:17070/environment/uuid/api', url)
+
+    def test_customized_charm_unexpected_series(self):
+        # If a customized Juju GUI charm is used, then we assume it supports
+        # the new Juju Login API endpoint (unsupported charm series).
+        charm = charms.Charm.from_url('cs:vivid/juju-gui-0')
+        url = jujutools.get_api_url(
+            'example.com:22', (1, 22, 2), 'uuid', prefix='ws', charm=charm)
+        self.assertEqual('wss://example.com:22/ws/environment/uuid/api', url)
+
+    def test_recent_precise_charm(self):
+        # The new API endpoints are used if a recent precise charm is in use.
+        charm = charms.Charm.from_url('cs:precise/juju-gui-107')
+        url = jujutools.get_api_url(
+            '1.2.3.4:4747', (1, 42, 0), 'env-id', charm=charm)
+        self.assertEqual('wss://1.2.3.4:4747/environment/env-id/api', url)
+
+    def test_recent_trusty_charm(self):
+        # The new API endpoints are used if a recent trusty charm is in use.
+        charm = charms.Charm.from_url('cs:trusty/juju-gui-19')
+        url = jujutools.get_api_url(
+            '1.2.3.4:4747', (1, 42, 0), 'env-id', charm=charm)
+        self.assertEqual('wss://1.2.3.4:4747/environment/env-id/api', url)
+
+    def test_old_precise_charm(self):
+        # The old API endpoint is returned if the precise Juju GUI charm in use
+        # is outdated.
+        charm = charms.Charm.from_url('cs:precise/juju-gui-106')
+        url = jujutools.get_api_url(
+            '1.2.3.4:4747', (1, 42, 0), 'env-uuid', charm=charm)
+        self.assertEqual('wss://1.2.3.4:4747', url)
+
+    def test_old_trusty_charm(self):
+        # The old API endpoint is returned if the trusty Juju GUI charm in use
+        # is outdated.
+        charm = charms.Charm.from_url('cs:trusty/juju-gui-18')
+        url = jujutools.get_api_url(
+            '1.2.3.4:4747', (1, 42, 0), 'env-uuid', prefix='ws', charm=charm)
+        self.assertEqual('wss://1.2.3.4:4747/ws', url)
+
+    def test_recent_charm_and_prefix(self):
+        # The new API endpoint is returned if a recent charm and a prefix are
+        # both provided. This test exercises the real case in which the GUI
+        # server API endpoint is returned.
+        charm = charms.Charm.from_url('cs:trusty/juju-gui-42')
+        url = jujutools.get_api_url(
+            '1.2.3.4:17070', (1, 22, 0), 'env-id', prefix='ws', charm=charm)
+        self.assertEqual('wss://1.2.3.4:17070/ws/environment/env-id/api', url)
+
+
 class TestGetServiceInfo(helpers.WatcherDataTestsMixin, unittest.TestCase):
 
     def test_service_and_unit(self):

=== modified file 'quickstart/tests/test_manage.py'
--- quickstart/tests/test_manage.py	2015-01-12 12:10:38 +0000
+++ quickstart/tests/test_manage.py	2015-02-09 18:28:10 +0000
@@ -40,6 +40,7 @@
     views,
 )
 from quickstart.models import (
+    charms,
     envs,
     jenv,
 )
@@ -808,7 +809,7 @@
         env = mock.Mock()
         defaults = {
             # Dependencies are installed.
-            'ensure_dependencies': (1, 18, 0),
+            'ensure_dependencies': (1, 22, 0),
             # Ensure the current Juju version is supported.
             'check_juju_supported': None,
             # Ensure the SSH keys are properly configured.
@@ -819,15 +820,17 @@
             'bootstrap': False,
             # Status is then called, returning the bootstrap node series.
             'status': 'trusty',
-            # The API URL must be retrieved (the environment was not ready).
-            'get_api_url': 'wss://1.2.3.4:17070',
+            # The API address must be retrieved (the environment is not ready).
+            'get_api_address': '1.2.3.4:17070',
+            # Retrieve the environment unique identifier.
+            'get_env_uuid_or_none': 'env-uuid',
             # Retrieve the environment credentials.
             'get_credentials': ('MyUser', 'Secret!'),
             # Connect to the Juju Environment API endpoint.
             'connect': env,
             # The environment is then checked.
             'check_environment': (
-                'cs:trusty/juju-gui-42',
+                charms.Charm.from_url('cs:trusty/juju-gui-42'),
                 '0',
                 {'Name': 'juju-gui'},
                 {'Name': 'juju-gui/0'}
@@ -835,7 +838,7 @@
             # Deploy the Juju GUI charm.
             'deploy_gui': 'juju-gui/0',
             # Watch the deployment progress and return the unit address.
-            'watch': '1.2.3.4',
+            'watch': '1.2.3.5',
             # Create the login token for the Juju GUI.
             'create_auth_token': 'TOKEN',
         }
@@ -859,7 +862,7 @@
         # Ensure the functions have been used correctly.
         mock_app.ensure_dependencies.assert_called_once_with(
             options.distro_only, options.platform, self.juju_command)
-        mock_app.check_juju_supported.assert_called_once_with((1, 18, 0))
+        mock_app.check_juju_supported.assert_called_once_with((1, 22, 0))
         mock_app.ensure_ssh_keys.assert_called_once_with()
         mock_app.check_bootstrapped.assert_called_once_with(options.env_name)
         mock_app.bootstrap.assert_called_once_with(
@@ -870,13 +873,20 @@
             constraints=options.constraints)
         mock_app.status.assert_called_once_with(
             options.env_name, self.juju_command)
-        mock_app.get_api_url.assert_called_once_with(
+        mock_app.get_api_address.assert_called_once_with(
             options.env_name, self.juju_command)
+        mock_app.get_env_uuid_or_none.assert_called_once_with(options.env_name)
         mock_app.get_credentials.assert_called_once_with(options.env_name)
         mock_app.connect.assert_has_calls([
-            mock.call('wss://1.2.3.4:17070', 'MyUser', 'Secret!'),
+            mock.call(
+                'wss://1.2.3.4:17070/environment/env-uuid/api',
+                'MyUser',
+                'Secret!'),
             mock.call().close(),
-            mock.call('wss://1.2.3.4:443/ws', 'MyUser', 'Secret!'),
+            mock.call(
+                'wss://1.2.3.5:443/ws/environment/env-uuid/api',
+                'MyUser',
+                'Secret!'),
             mock.call().close(),
         ])
         mock_app.check_environment.assert_called_once_with(
@@ -887,24 +897,61 @@
             '0', {'Name': 'juju-gui'}, {'Name': 'juju-gui/0'})
         mock_app.watch.assert_called_once_with(env, 'juju-gui/0')
         mock_app.create_auth_token.assert_called_once_with(env)
-        mock_open.assert_called_once_with('https://1.2.3.4/?authtoken=TOKEN')
+        mock_open.assert_called_once_with('https://1.2.3.5/?authtoken=TOKEN')
         # Ensure some of the app function have not been called.
         self.assertFalse(mock_app.get_env_type.called)
         self.assertFalse(mock_app.deploy_bundle.called)
 
+    def test_old_juju_api_endpoint(self, mock_app, mock_open):
+        # The old Juju WebSocket API endpoint is used if the Juju version is
+        # not recent enough.
+        self.configure_app(mock_app, ensure_dependencies=(1, 19, 0))
+        # Run the application.
+        options = self.make_options()
+        with self.patch_get_juju_command():
+            manage.run(options)
+        mock_app.connect.assert_has_calls([
+            mock.call('wss://1.2.3.4:17070', 'MyUser', 'Secret!'),
+            mock.call().close(),
+            mock.call('wss://1.2.3.5:443/ws', 'MyUser', 'Secret!'),
+            mock.call().close(),
+        ])
+
+    def test_new_api_endpoint_old_charm(self, mock_app, mock_open):
+        # Even if the Juju version is new, the old GUI server login API is used
+        # if the charm in the environment is not recent enough.
+        self.configure_app(mock_app, check_environment=(
+            charms.Charm.from_url('cs:trusty/juju-gui-0'),
+            '0',
+            {'Name': 'juju-gui'},
+            {'Name': 'juju-gui/0'}
+        ))
+        # Run the application.
+        options = self.make_options()
+        with self.patch_get_juju_command():
+            manage.run(options)
+        mock_app.connect.assert_has_calls([
+            mock.call(
+                'wss://1.2.3.4:17070/environment/env-uuid/api',
+                'MyUser',
+                'Secret!'),
+            mock.call().close(),
+            mock.call('wss://1.2.3.5:443/ws', 'MyUser', 'Secret!'),
+            mock.call().close(),
+        ])
+
     def test_already_bootstrapped(self, mock_app, mock_open):
         # The application correctly reuses an already bootstrapped environment.
-        env = self.configure_app(
-            mock_app, check_bootstrapped='wss://example.com')
+        env = self.configure_app(mock_app, check_bootstrapped='example.com')
         # Run the application.
         options = self.make_options()
         with self.patch_get_juju_command():
             manage.run(options)
         # The environment type is retrieved from the jenv.
         mock_app.get_env_type.assert_called_once_with(env)
-        # No reason to call bootstrap or get_api_url functions.
+        # No reason to call bootstrap or get_api_address functions.
         self.assertFalse(mock_app.bootstrap.called)
-        self.assertFalse(mock_app.get_api_url.called)
+        self.assertFalse(mock_app.get_api_address.called)
 
     def test_already_bootstrapped_race(self, mock_app, mock_open):
         # The application correctly reuses an already bootstrapped environment.
@@ -915,8 +962,8 @@
         options = self.make_options()
         with self.patch_get_juju_command():
             manage.run(options)
-        # The bootstrap and get_api_url functions are still called, but this
-        # time also get_env_type is required.
+        # The bootstrap and get_api_address functions are still called, but
+        # this time also get_env_type is required.
         # The environment type is retrieved from the jenv.
         mock_app.bootstrap.assert_called_once_with(
             options.env_name, self.juju_command,
@@ -924,7 +971,7 @@
             upload_tools=options.upload_tools,
             upload_series=options.upload_series,
             constraints=options.constraints)
-        mock_app.get_api_url.assert_called_once_with(
+        mock_app.get_api_address.assert_called_once_with(
             options.env_name, self.juju_command)
         mock_app.get_env_type.assert_called_once_with(env)
 
@@ -938,7 +985,7 @@
             manage.run(options)
         # Ensure the browser is still open without an auth token.
         mock_app.create_auth_token.assert_called_once_with(env)
-        mock_open.assert_called_once_with('https://1.2.3.4')
+        mock_open.assert_called_once_with('https://1.2.3.5')
 
     def test_bundle(self, mock_app, mock_open):
         # A bundle is correctly deployed by the application.