Merge lp:~frankban/juju-quickstart/idempotent-feature into lp:juju-quickstart

[Francesco Banconi]

Make quickstart idempotent.

- do not bootstrap an environment if already bootstrapped;
- do not deploy the GUI if already there.

Sorry, the diff is long, but there are a lot of tests.

Tests: make check

QA:
- .venv/bin/python juju-quickstart -e ec2
  and ensure the GUI is correctly deployed;

- .venv/bin/python juju-quickstart -e ec2
  again, to check it recognizes that env is
  already bootstrapped and the
  GUI unit is already there;

In the following steps, sometimes the browser
can get confused about certs, wss conections
etc. If the GUI is not loading correctly,
try harder, use incognito mode, change the
browser.

- juju destroy-service -e ec2 juju-gui;
- .venv/bin/python juju-quickstart -e ec2
  again, to check the service and the unit
  are correctly re-deployed;

Incidentally the step above, in the case it
succeeds, also demonstrates that the GUI can
safely be redeployed in the same machine: I
wasn't sure about this and this means we are
cleaning up things correctly in our charm, yay!

- juju unexpose -e ec2 juju-gui;
- .venv/bin/python juju-quickstart -e ec2
  again, to check that the service is
  properly re-exposed;

- juju destroy-unit -e ec2 juju-gui/0;
- .venv/bin/python juju-quickstart -e ec2
  again, to check that the unit is
  re-added on the existing service
  (this time it should be named juju-gui/1);

- juju destroy-service -e ec2 juju-gui;
- juju deploy -e ec2 juju-gui (if juju exits with a
  "service already exists" error, retry after a while);
- .venv/bin/python juju-quickstart -e ec2 \
    bundle:~jorge/mediawiki-simple/4/mediawiki-simple;
The last command, executed right after juju-deploy should
also demonstrates that incidentally quickstart
can also be used to watch an already running
deployment, and that a bundle can still be deployed;

Final check:
- .venv/bin/python juju-quickstart -e ec2;
just to ensure quickstart is not surprised
that the unit is not in the bootstrap node
(i.e. you should see "juju-gui/0 is ready on machine 1").

Thanks a lot for testing all of this.
I added a card to automate the QA above with
a collection of functional tests.

Remember to destroy your ec2 environment.

https://codereview.appspot.com/28250044/

[Francesco Banconi (frankban)]

Reviewers: mp+195592_code.launchpad.net,

Message:
Please take a look.

Description:
Make quickstart idempotent.

- do not bootstrap an environment if already bootstrapped;
- do not deploy the GUI if already there.

Sorry, the diff is long, but there are a lot of tests.

Tests: make check

QA:
- .venv/bin/python juju-quickstart -e ec2
   and ensure the GUI is correctly deployed;

- .venv/bin/python juju-quickstart -e ec2
   again, to check it recognizes that env is
   already bootstrapped and the
   GUI unit is already there;

In the following steps, sometimes the browser
can get confused about certs, wss conections
etc. If the GUI is not loading correctly,
try harder, use incognito mode, change the
browser.

- juju destroy-service -e ec2 juju-gui;
- .venv/bin/python juju-quickstart -e ec2
   again, to check the service and the unit
   are correctly re-deployed;

Incidentally the step above, in the case it
succeeds, also demonstrates that the GUI can
safely be redeployed in the same machine: I
wasn't sure about this and this means we are
cleaning up things correctly in our charm, yay!

- juju unexpose -e ec2 juju-gui;
- .venv/bin/python juju-quickstart -e ec2
   again, to check that the service is
   properly re-exposed;

- juju destroy-unit -e ec2 juju-gui/0;
- .venv/bin/python juju-quickstart -e ec2
   again, to check that the unit is
   re-added on the existing service
   (this time it should be named juju-gui/1);

- juju destroy-service -e ec2 juju-gui;
- juju deploy -e ec2 juju-gui (if juju exits with a
   "service already exists" error, retry after a while);
- .venv/bin/python juju-quickstart -e ec2 \
     bundle:~jorge/mediawiki-simple/4/mediawiki-simple;
The last command, executed right after juju-deploy should
also demonstrates that incidentally quickstart
can also be used to watch an already running
deployment, and that a bundle can still be deployed;

Final check:
- .venv/bin/python juju-quickstart -e ec2;
just to ensure quickstart is not surprised
that the unit is not in the bootstrap node
(i.e. you should see "juju-gui/0 is ready on machine 1").

Thanks a lot for testing all of this.
I added a card to automate the QA above with
a collection of functional tests.

Remember to destroy your ec2 environment.

https://code.launchpad.net/~frankban/juju-quickstart/idempotent-feature/+merge/195592

(do not edit description out of merge proposal)

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

Affected files (+635, -182 lines):
   A [revision details]
   M quickstart/__init__.py
   M quickstart/app.py
   M quickstart/juju.py
   M quickstart/manage.py
   M quickstart/tests/helpers.py
   M quickstart/tests/test_app.py
   M quickstart/tests/test_juju.py
   M quickstart/tests/test_manage.py
   M quickstart/tests/test_utils.py
   M quickstart/utils.py

[Gary Poster (gary)]

LGTM with a few trivials and a small. QA good. Very nice
functionality. Thank you!

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

https://codereview.appspot.com/28250044/diff/1/quickstart/app.py#newcode66
quickstart/app.py:66: # XXX frankban 2013-11-13: the check below is
weak. We are relying on
Could you file a Juju Core bug, add juju-quickstart as an affected
project, and add the bug number to this comment, please?

It looks like Wm prefers --format to get machine readable output, so
maybe that's a way forward?

https://codereview.appspot.com/28250044/diff/1/quickstart/app.py#newcode77
quickstart/app.py:77: # rather thank comparing the expected error with
the obtained one, we
typo: ...rather than...

https://codereview.appspot.com/28250044/diff/1/quickstart/app.py#newcode82
quickstart/app.py:82: already_bootstrapped = True
It took me a few seconds of thinking to realize why you didn't just
return True here. Low priority, but might be nice to say something
explanatory. Example:

# Juju is bootstapped, but we don't know if it is ready yet. Fall
# through to the next block for that check.

https://codereview.appspot.com/28250044/diff/1/quickstart/app.py#newcode155
quickstart/app.py:155: Raise a ProgramExit if the API server returns an
error response.
After reading docstring, I am not clear on three things.

(1) why is the provider type important here?
(2) why is the already_bootstrapped value important here?
(3) what happens if the GUI charm exists with a different name? what
happens if the given name is not a GUI charm?

Maybe we don't need to answer all of these in the docstring, but seemed
like a hole as I read it.

The code below answers #1 and #2; I have a comment below about #3.

https://codereview.appspot.com/28250044/diff/1/quickstart/app.py#newcode158
quickstart/app.py:158: if already_bootstrapped:
Ah! It is an optimization.

I thought about suggesting some different names for the argument,
focused on the local behavior of enabling checking for services and
units rather than the contextual idea that we are already bootstrapped.
E.g., s/already_bootstrapped/check_for_preexisting/ or something. From
the local function perspective, you could even argue that you should
only control disabling the behavior, since this is an
optimization--e.g., s/already_bootstrapped/not
prevent_preexisting_check/--but that's effectively a double negative.
In the end, I'm not suggesting this because I don't like any of the
other concrete options I considered. At best, this would have been
bikeshedding, anyway.

https://codereview.appspot.com/28250044/diff/1/quickstart/app.py#newcode187
quickstart/app.py:187: print('charm URL: {}'.format(charm_url))
Maybe we should warn the user if the actual charm_url != the given
charm_url, and warn louder if the charm id doesn't match
/\/juju-gui-\d+$/ ?

https://codereview.appspot.com/28250044/diff/1/quickstart/app.py#newcode199
quickstart/app.py:199: # bootstrap node if we are using the local
provider.
Ah-ha!

https://codereview.appspot.com/28250044/

[Gary Poster (gary)]

One QA note.

The end of your instructions said this:

--------------------------
Final check:
- .venv/bin/python juju-quickstart -e ec2;
just to ensure quickstart is not surprised
that the unit is not in the bootstrap node
(i.e. you should see "juju-gui/0 is ready on machine 1").
--------------------------

I saw it on machine 0 (ec2), which I expected given the immediately
previous instruction to destroy the service. If this is in fact a
surprise and broken...I reported it. :-)

https://codereview.appspot.com/28250044/

[Richard Harding (rharding)]

LGTM and qa-ok.

I'm with Gary on the is_bootstrapped being a bit confusing sometimes in
the inner workings.

I also get a bit confused with the 'charm_url' as I forget that in this
context that's ALWAYS the Gui charm. As features grow and things like
deploying bundles come into the picture, I wonder if a
s/charm_url/gui_charm_url might be in order.

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

https://codereview.appspot.com/28250044/diff/1/quickstart/app.py#newcode74
quickstart/app.py:74: # jens files seems to be an internal juju-core
detail. Definitely we
jenv

https://codereview.appspot.com/28250044/

[lp:~frankban/juju-quickstart/idempotent-feature]

23. By Francesco Banconi on 2013-11-18

Changes as per review.

[Francesco Banconi (frankban)]

*** Submitted:

Make quickstart idempotent.

- do not bootstrap an environment if already bootstrapped;
- do not deploy the GUI if already there.

Sorry, the diff is long, but there are a lot of tests.

Tests: make check

QA:
- .venv/bin/python juju-quickstart -e ec2
   and ensure the GUI is correctly deployed;

- .venv/bin/python juju-quickstart -e ec2
   again, to check it recognizes that env is
   already bootstrapped and the
   GUI unit is already there;

In the following steps, sometimes the browser
can get confused about certs, wss conections
etc. If the GUI is not loading correctly,
try harder, use incognito mode, change the
browser.

- juju destroy-service -e ec2 juju-gui;
- .venv/bin/python juju-quickstart -e ec2
   again, to check the service and the unit
   are correctly re-deployed;

Incidentally the step above, in the case it
succeeds, also demonstrates that the GUI can
safely be redeployed in the same machine: I
wasn't sure about this and this means we are
cleaning up things correctly in our charm, yay!

- juju unexpose -e ec2 juju-gui;
- .venv/bin/python juju-quickstart -e ec2
   again, to check that the service is
   properly re-exposed;

- juju destroy-unit -e ec2 juju-gui/0;
- .venv/bin/python juju-quickstart -e ec2
   again, to check that the unit is
   re-added on the existing service
   (this time it should be named juju-gui/1);

- juju destroy-service -e ec2 juju-gui;
- juju deploy -e ec2 juju-gui (if juju exits with a
   "service already exists" error, retry after a while);
- .venv/bin/python juju-quickstart -e ec2 \
     bundle:~jorge/mediawiki-simple/4/mediawiki-simple;
The last command, executed right after juju-deploy should
also demonstrates that incidentally quickstart
can also be used to watch an already running
deployment, and that a bundle can still be deployed;

Final check:
- .venv/bin/python juju-quickstart -e ec2;
just to ensure quickstart is not surprised
that the unit is not in the bootstrap node
(i.e. you should see "juju-gui/0 is ready on machine 1").

Thanks a lot for testing all of this.
I added a card to automate the QA above with
a collection of functional tests.

Remember to destroy your ec2 environment.

R=gary.poster, rharding
CC=
https://codereview.appspot.com/28250044

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

https://codereview.appspot.com/28250044/diff/1/quickstart/app.py#newcode66
quickstart/app.py:66: # XXX frankban 2013-11-13: the check below is
weak. We are relying on
On 2013/11/18 15:02:19, gary.poster wrote:
> Could you file a Juju Core bug, add juju-quickstart as an affected
project, and
> add the bug number to this comment, please?

> It looks like Wm prefers --format to get machine readable output, so
maybe
> that's a way forward?

Done. Filed bug 1252322.

https://codereview.appspot.com/28250044/diff/1/quickstart/app.py#newcode74
quickstart/app.py:74: # jens files seems to be an internal juju-core
detail. Definitely we
On 2013/11/18 15:42:56, rharding wrote:
> jenv

Done.

https://codereview.appspot.com/28250044/diff/1/quickstart/app.py#newcode77
quickstart/app.py:77: # rather thank comparing the expected error with
the obtai...

[Francesco Banconi (frankban)]

Thank you both for the great reviews!

https://codereview.appspot.com/28250044/

=== modified file 'quickstart/__init__.py'
--- quickstart/__init__.py	2013-11-06 10:17:08 +0000
+++ quickstart/__init__.py	2013-11-18 16:54:22 +0000
@@ -19,7 +19,7 @@
 that it can be managed using a Web interface (the Juju GUI).
 """
 
-VERSION = (0, 3, 0)
+VERSION = (0, 4, 0)
 
 
 def get_version():

=== modified file 'quickstart/app.py'
--- quickstart/app.py	2013-11-13 12:23:36 +0000
+++ quickstart/app.py	2013-11-18 16:54:22 +0000
@@ -47,17 +47,41 @@
 def bootstrap(env_name, debug=False):
     """Bootstrap the Juju environment with the given name.
 
-    If debug is True, bootstrap the environment passing the --debug flag.
-
-    Return when the bootstrap node is ready.
+    Do not bootstrap the environment if already bootstrapped.
+
+    Return True without errors if the environment is already bootstrapped.
+    Return False otherwise. Only return when the bootstrap node is ready.
+
+    If debug is True and the environment not bootstrapped, execute the
+    bootstrap command passing the --debug flag.
+
     Raise a ProgramExit if any error occurs in the bootstrap process.
     """
+    already_bootstrapped = False
     cmd = ['juju', 'bootstrap', '-e', env_name]
     if debug:
         cmd.append('--debug')
     retcode, _, error = utils.call(*cmd)
     if retcode:
-        raise ProgramExit(error)
+        # XXX frankban 2013-11-13 bug 1252322: the check below is weak. We are
+        # relying on an error message in order to decide if the environment is
+        # already bootstrapped. Other possibilities include checking if the
+        # jenv file is present (in ~/.juju/environments/) and, if so, check the
+        # juju status. Unfortunately this is also prone to errors, because a
+        # jenv file can be there but the environment not really bootstrapped or
+        # functional (e.g. sync-tools was used, or a previous bootstrap failed,
+        # or the user terminated machines from the ec2 panel, etc.). Moreover
+        # jenv files seems to be an internal juju-core detail. Definitely we
+        # need to find a better way, but for now the "asking forgiveness"
+        # approach feels like the best compromise we have. Also note that,
+        # rather than comparing the expected error with the obtained one, we
+        # search in the error in order to support bootstrap --debug.
+        if 'environment is already bootstrapped' not in error:
+            # We exit if the error is not "already bootstrapped".
+            raise ProgramExit(error)
+        # Juju is bootstrapped, but we don't know if it is ready yet. Fall
+        # through to the next block for that check.
+        already_bootstrapped = True
     # Call "juju status" multiple times until the bootstrap node is ready.
     for _ in range(5):
         retcode, output, error = utils.call(
@@ -70,7 +94,7 @@
         except ValueError:
             continue
         if agent_state == 'started':
-            return
+            return already_bootstrapped
     details = ''.join(filter(None, [output, error])).strip()
     raise ProgramExit('the state server is not ready:\n{}'.format(details))
 
@@ -112,34 +136,88 @@
     return env
 
 
-def deploy_gui(env, service_name, charm_url=None):
+def deploy_gui(
+        env, service_name, machine, charm_url=None, check_preexisting=False):
     """Deploy and expose the given service, reusing the bootstrap node.
 
-    Receive an authenticated Juju Environment instance, the name of the service
-    and the optional Juju GUI charm URL, e.g. cs:~juju-gui/precise/juju-gui-42.
-    If the charm URL is not provided, the function tries to retrieve it from
-    charmworld. In this case a default charm URL is used if charmworld is not
-    available.
-
+    Only deploy the service if not already present in the environment.
+    Do not add a unit to the service if the unit is already there.
+
+    Receive an authenticated Juju Environment instance, the name of the
+    service, the machine where to deploy to (or None for a new machine),
+    the optional Juju GUI charm URL (e.g. cs:~juju-gui/precise/juju-gui-42),
+    and a flag (check_preexisting) that can be set to True in order to make
+    the function check for a pre-existing service and/or unit.
+
+    If the charm URL is not provided, and the service is not already deployed,
+    the function tries to retrieve it from charmworld. In this case a default
+    charm URL is used if charmworld is not available.
+
+    Return the name of the first running unit belonging to the given service.
     Raise a ProgramExit if the API server returns an error response.
     """
-    if charm_url is None:
-        try:
-            charm_url = utils.get_charm_url()
-        except (IOError, ValueError) as err:
-            msg = 'unable to retrieve the Juju GUI charm URL from the API: {}'
-            logging.warn(msg.format(err))
-            charm_url = settings.DEFAULT_CHARM_URL
-    print('charm URL: {}'.format(charm_url))
-    try:
-        env.deploy(service_name, charm_url, to=0)
-        env.expose(service_name)
-    except jujuclient.EnvError as err:
-        raise ProgramExit('bad API server response: {}'.format(err.message))
-
-
-def watch(env, service_name):
-    """Start watching the first unit belonging to the given service.
+    service_data, unit_data = None, None
+    if check_preexisting:
+        # The service and/or the unit can be already in the environment.
+        try:
+            status = env.get_status()
+        except jujuclient.EnvError as err:
+            raise ProgramExit('bad API response: {}'.format(err.message))
+        service_data, unit_data = utils.get_service_info(status, service_name)
+    if service_data is None:
+        # The service does not exist in the environment.
+        print('requesting {} deployment'.format(service_name))
+        if charm_url is None:
+            try:
+                charm_url = utils.get_charm_url()
+            except (IOError, ValueError) as err:
+                msg = 'unable to retrieve the {} charm URL from the API: {}'
+                logging.warn(msg.format(service_name, err))
+                charm_url = settings.DEFAULT_CHARM_URL
+        print('charm URL: {}'.format(charm_url))
+        # Deploy the service without units.
+        try:
+            env.deploy(service_name, charm_url, num_units=0)
+        except jujuclient.EnvError as err:
+            raise ProgramExit('bad API response: {}'.format(err.message))
+        print('{} deployment request accepted'.format(service_name))
+        service_exposed = False
+    else:
+        # We already have the service in the environment.
+        print('service {} already deployed'.format(service_name))
+        charm_url = service_data['CharmURL']
+        print('charm URL: {}'.format(charm_url))
+        # XXX frankban: warn the user if the actual charm_url != the given
+        # charm_url, and warn louder if the charm URL does not match
+        # /\/juju-gui-\d+$/.
+        service_exposed = service_data.get('Exposed', False)
+    # At this point the service is surely deployed in the environment: expose
+    # it if necessary and add a unit if it is missing.
+    if not service_exposed:
+        print('exposing service {}'.format(service_name))
+        try:
+            env.expose(service_name)
+        except jujuclient.EnvError as err:
+            raise ProgramExit('bad API response: {}'.format(err.message))
+    if unit_data is None:
+        # Add a unit to the service.
+        print('requesting new unit deployment')
+        try:
+            response = env.add_unit(service_name, machine_spec=machine)
+        except jujuclient.EnvError as err:
+            raise ProgramExit('bad API response: {}'.format(err.message))
+        unit_name = response['Units'][0]
+        print('{} deployment request accepted'.format(unit_name))
+    else:
+        # A service unit is already present in the environment. Go ahead
+        # and try to reuse that unit.
+        unit_name = unit_data['Name']
+        print('reusing unit {}'.format(unit_name))
+    return unit_name
+
+
+def watch(env, unit_name):
+    """Start watching the given unit.
 
     Output a human readable messages from each time a relevant change is found.
 
@@ -153,7 +231,6 @@
     Raise a ProgramExit if the API server returns an error response, or if
     the service unit is removed or in error.
     """
-    unit_name = '{}/0'.format(service_name)
     processor = functools.partial(utils.unit_changes, unit_name)
     watcher = env.watch_changes(processor)
     address = current_status = ''
@@ -176,7 +253,7 @@
         if not address:
             address = data['PublicAddress']
             if address:
-                print('installing {} on {}'.format(unit_name, address))
+                print('setting up {} on {}'.format(unit_name, address))
         # Notify status changes.
         if status != current_status:
             if status == 'pending':
@@ -185,7 +262,8 @@
                 print('{} is installed'.format(unit_name))
             elif address and status == 'started':
                 # We can exit this loop.
-                print('{} is ready'.format(unit_name))
+                print('{} is ready on machine {}'.format(
+                    unit_name, data['MachineId']))
                 return address
             current_status = status
 

=== modified file 'quickstart/juju.py'
--- quickstart/juju.py	2013-10-30 11:44:35 +0000
+++ quickstart/juju.py	2013-11-18 16:54:22 +0000
@@ -41,35 +41,25 @@
     deployments to specific machines.
     """
 
-    def deploy(
-            self, service_name, charm_url, num_units=1, config=None,
-            constraints=None, to=None):
-        """Deploy a charm. Local charms are not supported.
+    def add_unit(self, service_name, machine_spec=None):
+        """Add a unit to the given service and machine.
 
-        This method is overridden to add the ability to deploy to a specific
-        machine (i.e. support the ToMachineSpec API parameter).
+        This method is present in newer versions of python-jujuclient and can
+        be safely deleted when upgrading to the new releases.
         """
-        service_config = {}
-        if config is not None:
-            service_config = self._prepare_strparams(config)
-        service_constraints = {}
-        if constraints is not None:
-            service_constraints = self._prepare_constraints(constraints)
+        # XXX frankban 2013-11-15: remove this method when upgrading to
+        # python-jujuclient >= 0.15.
         params = {
             'ServiceName': service_name,
-            'CharmURL': charm_url,
-            'NumUnits': num_units,
-            'Config': service_config,
-            'Constraints': service_constraints,
+            'NumUnits': 1,
         }
-        if to is not None:
-            params['ToMachineSpec'] = str(to)
-        request = {
+        if machine_spec is not None:
+            params['ToMachineSpec'] = machine_spec
+        return self._rpc({
             'Type': 'Client',
-            'Request': 'ServiceDeploy',
+            'Request': 'AddServiceUnits',
             'Params': params,
-        }
-        return self._rpc(request)
+        })
 
     def deploy_bundle(self, yaml, name=None):
         """Deploy a bundle."""
@@ -83,13 +73,28 @@
         }
         return self._rpc(request)
 
+    def get_status(self):
+        """Return the current status of the environment.
+
+        The status is represented by a single mega-watcher changeset.
+        Each change in the changeset is a tuple (entity, action, data) where:
+            - entity is a string representing the changed content type
+              (e.g. "service" or "unit");
+            - action is a string representing the event which generated the
+              change (i.e. "change" or "remove");
+            - data is a dict containing information about the releated entity.
+        """
+        with self.get_watch() as watcher:
+            changeset = watcher.next()
+        return changeset
+
     def watch_changes(self, processor):
         """Start watching the changes occurring in the Juju environment.
 
         For each changeset, call the given processor callable, and yield
         the values returned by the processor.
         """
-        with jujuclient.Watcher(self.conn) as watcher:
+        with self.get_watch() as watcher:
             # The watcher closes when the context manager exit hook is called.
             for changeset in watcher:
                 changes = processor(changeset)

=== modified file 'quickstart/manage.py'
--- quickstart/manage.py	2013-11-13 12:23:36 +0000
+++ quickstart/manage.py	2013-11-18 16:54:22 +0000
@@ -187,7 +187,8 @@
         help='The Juju GUI charm URL to deploy in the environment. If not '
              'provided, the last release of the GUI will be deployed. The '
              'charm URL must include the charm version, e.g. '
-             'cs:~juju-gui/precise/juju-gui-116')
+             'cs:~juju-gui/precise/juju-gui-116. This option is ignored if '
+             'Juju GUI is already present in the environment')
     parser.add_argument(
         '--no-browser', action='store_false', dest='open_browser',
         help='Avoid opening the browser to the GUI at the end of the process')
@@ -218,15 +219,23 @@
     print('juju quickstart v{}'.format(version))
     print('bootstrapping the {} environment (type: {})'.format(
         options.env_name, options.env_type))
-    app.bootstrap(options.env_name, debug=options.debug)
+    already_bootstrapped = app.bootstrap(options.env_name, debug=options.debug)
+    if already_bootstrapped:
+        print('reusing the already bootstrapped {} environment'.format(
+            options.env_name))
+
     print('retrieving the Juju API address')
     api_url = app.get_api_url(options.env_name)
     print('connecting to {}'.format(api_url))
     env = app.connect(api_url, options.admin_secret)
-    print('requesting Juju GUI deployment')
-    app.deploy_gui(env, settings.JUJU_GUI_NAME, charm_url=options.charm_url)
-    print('Juju GUI deployment request accepted')
-    address = app.watch(env, settings.JUJU_GUI_NAME)
+
+    # It is not possible to deploy on the bootstrap node if we are using the
+    # local provider.
+    machine = None if options.env_type == 'local' else '0'
+    unit_name = app.deploy_gui(
+        env, settings.JUJU_GUI_NAME, machine, charm_url=options.charm_url,
+        check_preexisting=already_bootstrapped)
+    address = app.watch(env, unit_name)
     url = 'https://{}'.format(address)
     print('url: {}\npassword: {}'.format(url, options.admin_secret))
 

=== modified file 'quickstart/tests/helpers.py'
--- quickstart/tests/helpers.py	2013-11-06 14:55:30 +0000
+++ quickstart/tests/helpers.py	2013-11-18 16:54:22 +0000
@@ -150,3 +150,33 @@
         with self.assertRaises(ValueError) as context_manager:
             yield
         self.assertEqual(error, str(context_manager.exception))
+
+
+class WatcherDataTestsMixin(object):
+    """Shared methods for testing Juju mega-watcher data."""
+
+    def _make_change(self, entity, action, default_data, data):
+        if data is not None:
+            default_data.update(data)
+        return entity, action, default_data
+
+    def make_service_change(self, action='change', data=None):
+        """Create and return a change on a service.
+
+        The passed data can be used to override default values.
+        """
+        default_data = {
+            'CharmURL': 'cs:precise/juju-gui-47',
+            'Exposed': True,
+            'Life': 'alive',
+            'Name': 'my-gui',
+        }
+        return self._make_change('service', action, default_data, data)
+
+    def make_unit_change(self, action='change', data=None):
+        """Create and return a change on a unit.
+
+        The passed data can be used to override default values.
+        """
+        default_data = {'Name': 'my-gui/47', 'Service': 'my-gui'}
+        return self._make_change('unit', action, default_data, data)

=== modified file 'quickstart/tests/test_app.py'
--- quickstart/tests/test_app.py	2013-11-13 12:23:36 +0000
+++ quickstart/tests/test_app.py	2013-11-18 16:54:22 +0000
@@ -99,7 +99,8 @@
     def test_success(self):
         # The environment is successfully bootstrapped.
         with self.patch_multiple_calls(self.make_side_effects()) as mock_call:
-            app.bootstrap(self.env_name)
+            already_bootstrapped = app.bootstrap(self.env_name)
+        self.assertFalse(already_bootstrapped)
         mock_call.assert_has_calls([
             mock.call('juju', 'bootstrap', '-e', self.env_name),
         ] + self.make_status_calls(1))
@@ -107,11 +108,26 @@
     def test_success_debug(self):
         # The environment is successfully bootstrapped in debug mode.
         with self.patch_multiple_calls(self.make_side_effects()) as mock_call:
-            app.bootstrap(self.env_name, debug=True)
+            already_bootstrapped = app.bootstrap(self.env_name, debug=True)
+        self.assertFalse(already_bootstrapped)
         mock_call.assert_has_calls([
             mock.call('juju', 'bootstrap', '-e', self.env_name, '--debug'),
         ] + self.make_status_calls(1))
 
+    def test_already_bootstrapped(self):
+        # The function succeeds and returns True if the environment is already
+        # bootstrapped.
+        side_effects = [
+            (1, '', '***environment is already bootstrapped**'),
+            (0, self.make_status_output('started'), ''),
+        ]
+        with self.patch_multiple_calls(side_effects) as mock_call:
+            already_bootstrapped = app.bootstrap(self.env_name)
+        self.assertTrue(already_bootstrapped)
+        mock_call.assert_has_calls([
+            mock.call('juju', 'bootstrap', '-e', self.env_name),
+        ] + self.make_status_calls(1))
+
     def test_bootstrap_failure(self):
         # A ProgramExit is raised if an error occurs while bootstrapping.
         with self.patch_call(1, error='bad wolf') as mock_call:
@@ -251,10 +267,32 @@
 
 
 @mock_print
-class TestDeployGui(ProgramExitTestsMixin, unittest.TestCase):
+class TestDeployGui(
+        ProgramExitTestsMixin, helpers.WatcherDataTestsMixin,
+        unittest.TestCase):
 
     charm_url = 'cs:precise/juju-gui-42'
 
+    def make_env(self, unit_name=None, service_data=None, unit_data=None):
+        """Create and return a mock environment object.
+
+        Set up the object so that a call to add_unit returns the given
+        unit_name, and a call to status returns a status object containing the
+        service and unit described by the given service_data and unit_data.
+        """
+        env = mock.Mock()
+        # Set up the add_unit return value.
+        if unit_name is not None:
+            env.add_unit.return_value = {'Units': [unit_name]}
+        #Set up the get_status return value.
+        status = []
+        if service_data is not None:
+            status.append(self.make_service_change(data=service_data))
+        if unit_data is not None:
+            status.append(self.make_unit_change(data=unit_data))
+        env.get_status.return_value = status
+        return env
+
     def patch_get_charm_url(self, side_effect=None):
         """Patch the get_charm_url helper function."""
         if side_effect is None:
@@ -265,65 +303,198 @@
     def test_deployment(self, mock_print):
         # The function correctly deploys and exposes the service, retrieving
         # the charm URL from the charmworld API.
-        env = mock.Mock()
-        with self.patch_get_charm_url():
-            app.deploy_gui(env, 'my-gui')
-        env.assert_has_calls([
-            mock.call.deploy('my-gui', self.charm_url, to=0),
-            mock.call.expose('my-gui')
-        ])
-        mock_print.assert_called_once_with(
-            'charm URL: {}'.format(self.charm_url))
-
-    def test_deployment_default_charm_url(self, mock_print):
+        env = self.make_env(unit_name='my-gui/42')
+        with self.patch_get_charm_url():
+            unit_name = app.deploy_gui(env, 'my-gui', '0')
+        self.assertEqual('my-gui/42', unit_name)
+        env.assert_has_calls([
+            mock.call.deploy('my-gui', self.charm_url, num_units=0),
+            mock.call.expose('my-gui'),
+            mock.call.add_unit('my-gui', machine_spec='0'),
+        ])
+        # There is no need to call status if the environment was just created.
+        self.assertFalse(env.get_status.called)
+        mock_print.assert_has_calls([
+            mock.call('requesting my-gui deployment'),
+            mock.call('charm URL: {}'.format(self.charm_url)),
+            mock.call('my-gui deployment request accepted'),
+            mock.call('exposing service my-gui'),
+            mock.call('requesting new unit deployment'),
+            mock.call('my-gui/42 deployment request accepted'),
+        ])
+
+    def test_existing_environment_without_entities(self, mock_print):
+        # The deployment is processed in an already bootstrapped environment
+        # with no relevant entities in it.
+        env = self.make_env(unit_name='my-gui/42')
+        with self.patch_get_charm_url():
+            unit_name = app.deploy_gui(
+                env, 'my-gui', '0', check_preexisting=True)
+        self.assertEqual('my-gui/42', unit_name)
+        env.assert_has_calls([
+            mock.call.get_status(),
+            mock.call.deploy('my-gui', self.charm_url, num_units=0),
+            mock.call.expose('my-gui'),
+            mock.call.add_unit('my-gui', machine_spec='0'),
+        ])
+
+    def test_default_charm_url(self, mock_print):
         # The function correctly deploys and exposes the service, even if it is
         # not able to retrieve the charm URL from the charmworld API.
-        env = mock.Mock()
-        log = 'unable to retrieve the Juju GUI charm URL from the API: boo!'
+        env = self.make_env(unit_name='my-gui/42')
+        log = 'unable to retrieve the my-gui charm URL from the API: boo!'
         with self.patch_get_charm_url(side_effect=IOError('boo!')):
             # A warning is logged which notifies we are using the default URL.
             with helpers.assert_logs([log], level='warn'):
-                app.deploy_gui(env, 'my-gui')
+                app.deploy_gui(env, 'my-gui', '0')
         env.assert_has_calls([
-            mock.call.deploy('my-gui', settings.DEFAULT_CHARM_URL, to=0),
-            mock.call.expose('my-gui')
-        ])
-        mock_print.assert_called_once_with(
-            'charm URL: {}'.format(settings.DEFAULT_CHARM_URL))
+            mock.call.deploy(
+                'my-gui', settings.DEFAULT_CHARM_URL, num_units=0),
+            mock.call.expose('my-gui'),
+            mock.call.add_unit('my-gui', machine_spec='0'),
+        ])
+        mock_print.assert_has_calls([
+            mock.call('requesting my-gui deployment'),
+            mock.call('charm URL: {}'.format(settings.DEFAULT_CHARM_URL)),
+        ])
 
-    def test_deployment_provided_charm_url(self, mock_print):
+    def test_provided_charm_url(self, mock_print):
         # The function correctly deploys and exposes the service using a user
         # provided Juju GUI charm URL.
-        env = mock.Mock()
+        env = self.make_env(unit_name='my-gui/42')
         charm_url = 'cs:~juju-gui/precise/juju-gui-116'
-        app.deploy_gui(env, 'my-gui', charm_url=charm_url)
-        env.assert_has_calls([
-            mock.call.deploy('my-gui', charm_url, to=0),
-            mock.call.expose('my-gui')
-        ])
-        mock_print.assert_called_once_with('charm URL: {}'.format(charm_url))
-
-    def test_api_error(self, mock_print):
-        # A ProgramExit is raised if an error occurs in one of the API calls.
-        env = mock.Mock()
-        env.deploy.side_effect = self.make_env_error('service already exists')
-        expected = 'bad API server response: service already exists'
-        with self.patch_get_charm_url():
-            with self.assert_program_exit(expected):
-                app.deploy_gui(env, 'another-gui')
+        app.deploy_gui(env, 'my-gui', '0', charm_url=charm_url)
+        env.assert_has_calls([
+            mock.call.deploy('my-gui', charm_url, num_units=0),
+            mock.call.expose('my-gui'),
+            mock.call.add_unit('my-gui', machine_spec='0'),
+        ])
+        mock_print.assert_has_calls([
+            mock.call('requesting my-gui deployment'),
+            mock.call('charm URL: {}'.format(charm_url)),
+        ])
+
+    def test_existing_service(self, mock_print):
+        # The deployment is executed reusing an already deployed service.
+        env = self.make_env(unit_name='my-gui/42', service_data={})
+        unit_name = app.deploy_gui(
+            env, 'my-gui', '0', check_preexisting=True)
+        self.assertEqual('my-gui/42', unit_name)
+        env.assert_has_calls([
+            mock.call.get_status(),
+            mock.call.add_unit('my-gui', machine_spec='0'),
+        ])
+        # The service is not re-deployed.
+        self.assertFalse(env.deploy.called)
+        # The service is not re-exposed.
+        self.assertFalse(env.expose.called)
+        mock_print.assert_has_calls([
+            mock.call('service my-gui already deployed'),
+            mock.call('charm URL: cs:precise/juju-gui-47'),
+            mock.call('requesting new unit deployment'),
+            mock.call('my-gui/42 deployment request accepted'),
+        ])
+
+    def test_existing_service_unexposed(self, mock_print):
+        # The existing service is exposed if required.
+        service_data = {'Exposed': False}
+        env = self.make_env(unit_name='my-gui/42', service_data=service_data)
+        unit_name = app.deploy_gui(
+            env, 'my-gui', '1', check_preexisting=True)
+        self.assertEqual('my-gui/42', unit_name)
+        env.assert_has_calls([
+            mock.call.get_status(),
+            mock.call.expose('my-gui'),
+            mock.call.add_unit('my-gui', machine_spec='1'),
+        ])
+        # The service is not re-deployed.
+        self.assertFalse(env.deploy.called)
+        mock_print.assert_has_calls([
+            mock.call('service my-gui already deployed'),
+            mock.call('charm URL: cs:precise/juju-gui-47'),
+            mock.call('exposing service my-gui'),
+            mock.call('requesting new unit deployment'),
+            mock.call('my-gui/42 deployment request accepted'),
+        ])
+
+    def test_existing_service_and_unit(self, mock_print):
+        # A unit is reused if a suitable one is already present.
+        env = self.make_env(service_data={}, unit_data={})
+        unit_name = app.deploy_gui(
+            env, 'my-gui', '0', check_preexisting=True)
+        self.assertEqual('my-gui/47', unit_name)
+        env.get_status.assert_called_once_with()
+        # The service is not re-deployed.
+        self.assertFalse(env.deploy.called)
+        # The service is not re-exposed.
+        self.assertFalse(env.expose.called)
+        # The unit is not re-added.
+        self.assertFalse(env.add_unit.called)
+        mock_print.assert_has_calls([
+            mock.call('service my-gui already deployed'),
+            mock.call('charm URL: cs:precise/juju-gui-47'),
+            mock.call('reusing unit my-gui/47'),
+        ])
+
+    def test_new_machine(self, mock_print):
+        # The unit is correctly deployed in a new machine.
+        env = self.make_env(unit_name='my-gui/42')
+        with self.patch_get_charm_url():
+            unit_name = app.deploy_gui(env, 'my-gui', None)
+        self.assertEqual('my-gui/42', unit_name)
+        env.assert_has_calls([
+            mock.call.deploy('my-gui', self.charm_url, num_units=0),
+            mock.call.expose('my-gui'),
+            mock.call.add_unit('my-gui', machine_spec=None),
+        ])
+
+    def test_status_error(self, mock_print):
+        # A ProgramExit is raised if an error occurs in the status API call.
+        env = self.make_env()
+        env.get_status.side_effect = self.make_env_error('bad wolf')
+        with self.assert_program_exit('bad API response: bad wolf'):
+            app.deploy_gui(
+                env, 'another-gui', '0', check_preexisting=True)
+        env.get_status.assert_called_once_with()
+
+    def test_deploy_error(self, mock_print):
+        # A ProgramExit is raised if an error occurs in the deploy API call.
+        env = self.make_env()
+        env.deploy.side_effect = self.make_env_error('bad wolf')
+        with self.patch_get_charm_url():
+            with self.assert_program_exit('bad API response: bad wolf'):
+                app.deploy_gui(env, 'another-gui', '0')
         env.deploy.assert_called_once_with(
-            'another-gui', 'cs:precise/juju-gui-42', to=0)
+            'another-gui', self.charm_url, num_units=0)
+
+    def test_expose_error(self, mock_print):
+        # A ProgramExit is raised if an error occurs in the expose API call.
+        env = self.make_env()
+        env.expose.side_effect = self.make_env_error('bad wolf')
+        with self.patch_get_charm_url():
+            with self.assert_program_exit('bad API response: bad wolf'):
+                app.deploy_gui(env, 'another-gui', '0')
+        env.expose.assert_called_once_with('another-gui')
+
+    def test_add_unit_error(self, mock_print):
+        # A ProgramExit is raised if an error occurs in the add_unit API call.
+        env = self.make_env()
+        env.add_unit.side_effect = self.make_env_error('bad wolf')
+        with self.patch_get_charm_url():
+            with self.assert_program_exit('bad API response: bad wolf'):
+                app.deploy_gui(env, 'another-gui', '0')
+        env.add_unit.assert_called_once_with('another-gui', machine_spec='0')
 
     def test_other_errors(self, mock_print):
         # Any other errors occurred during the process are not trapped.
         error = ValueError('explode!')
-        env = mock.Mock()
+        env = self.make_env(unit_name='my-gui/42')
         env.expose.side_effect = error
         with self.patch_get_charm_url():
             with self.assertRaises(ValueError) as context_manager:
-                app.deploy_gui(env, 'juju-gui')
+                app.deploy_gui(env, 'juju-gui', '0')
         env.deploy.assert_called_once_with(
-            'juju-gui', 'cs:precise/juju-gui-42', to=0)
+            'juju-gui', 'cs:precise/juju-gui-42', num_units=0)
         env.expose.assert_called_once_with('juju-gui')
         self.assertIs(error, context_manager.exception)
 
@@ -334,28 +505,29 @@
     address = 'unit.example.com'
     change_pending = ('unit', 'change', {
         'Name': 'django/42',
-        'Status': 'pending',
         'PublicAddress': '',
+        'Status': 'pending',
     })
     change_reachable = ('unit', 'change', {
         'Name': 'django/42',
+        'PublicAddress': address,
         'Status': 'pending',
-        'PublicAddress': address,
     })
     change_installed = ('unit', 'change', {
         'Name': 'django/42',
+        'PublicAddress': address,
         'Status': 'installed',
-        'PublicAddress': address,
     })
     change_started = ('unit', 'change', {
+        'MachineId': '0',
         'Name': 'django/42',
+        'PublicAddress': address,
         'Status': 'started',
-        'PublicAddress': address,
     })
-    pending_call = mock.call('django/0 deployment is pending')
-    reachable_call = mock.call('installing django/0 on {}'.format(address))
-    installed_call = mock.call('django/0 is installed')
-    started_call = mock.call('django/0 is ready')
+    pending_call = mock.call('django/42 deployment is pending')
+    reachable_call = mock.call('setting up django/42 on {}'.format(address))
+    installed_call = mock.call('django/42 is installed')
+    started_call = mock.call('django/42 is ready on machine 0')
 
     def make_env(self, changes):
         """Create and return a patched Environment instance.
@@ -375,7 +547,7 @@
             self.change_installed,
             self.change_started,
         ])
-        address = app.watch(env, 'django')
+        address = app.watch(env, 'django/42')
         self.assertEqual(self.address, address)
         mock_print.assert_has_calls([
             self.pending_call,
@@ -392,7 +564,7 @@
             self.change_installed,
             self.change_started,
         ])
-        address = app.watch(env, 'django')
+        address = app.watch(env, 'django/42')
         self.assertEqual(self.address, address)
         mock_print.assert_has_calls([
             self.reachable_call,
@@ -404,7 +576,7 @@
     def test_missing_changes(self, mock_print):
         # Only the started change is strictly required.
         env = self.make_env([self.change_started])
-        address = app.watch(env, 'django')
+        address = app.watch(env, 'django/42')
         self.assertEqual(self.address, address)
         mock_print.assert_has_calls([
             self.reachable_call,
@@ -432,7 +604,7 @@
             }),
             self.change_started,
         ])
-        address = app.watch(env, 'django')
+        address = app.watch(env, 'django/42')
         self.assertEqual(self.address, address)
         mock_print.assert_has_calls([
             self.pending_call,
@@ -449,7 +621,7 @@
         ])
         expected = 'bad API server response: next returned an error'
         with self.assert_program_exit(expected):
-            app.watch(env, 'django')
+            app.watch(env, 'django/42')
         mock_print.assert_has_calls([self.pending_call])
 
     def test_other_errors(self, mock_print):
@@ -457,7 +629,7 @@
         error = ValueError('explode!')
         env = self.make_env([self.change_installed, error])
         with self.assertRaises(ValueError) as context_manager:
-            app.watch(env, 'django')
+            app.watch(env, 'django/42')
         mock_print.assert_has_calls([self.reachable_call, self.installed_call])
         self.assertIs(error, context_manager.exception)
 
@@ -472,8 +644,8 @@
             }),
             self.change_reachable,
         ])
-        with self.assert_program_exit('django/0 unexpectedly removed'):
-            app.watch(env, 'django')
+        with self.assert_program_exit('django/42 unexpectedly removed'):
+            app.watch(env, 'django/42')
         mock_print.assert_has_calls([self.pending_call])
 
     def test_status_error(self, mock_print):
@@ -483,14 +655,14 @@
             ('unit', 'change', {
                 'Name': 'django/42',
                 'Status': 'error',
-                'StatusInfo': 'install hook failure',
+                'StatusInfo': 'install failure',
                 'PublicAddress': '',
             }),
             self.change_reachable,
         ])
-        expected = 'django/0 is in an error state: error: install hook failure'
+        expected = 'django/42 is in an error state: error: install failure'
         with self.assert_program_exit(expected):
-            app.watch(env, 'django')
+            app.watch(env, 'django/42')
         mock_print.assert_has_calls([self.pending_call])
 
 

=== modified file 'quickstart/tests/test_juju.py'
--- quickstart/tests/test_juju.py	2013-10-30 10:16:36 +0000
+++ quickstart/tests/test_juju.py	2013-11-18 16:54:22 +0000
@@ -25,6 +25,9 @@
 from quickstart.tests import helpers
 
 
+patch_rpc = mock.patch('quickstart.juju.Environment._rpc')
+
+
 class TestConnect(unittest.TestCase):
 
     api_url = 'wss://api.example.com:17070'
@@ -45,6 +48,9 @@
 
 
 class TestEnvironment(unittest.TestCase):
+    # Note that in some of the tests below, rather than exercising quickstart
+    # code, we are actually testing the external jujuclient methods. This is so
+    # by design, and will help us when upgrading the python-jujuclient library.
 
     api_url = 'wss://api.example.com:17070'
     charm_url = 'cs:precise/juju-gui-77'
@@ -59,8 +65,24 @@
         # Keep track of watcher changes in the changesets list.
         self.changesets = []
 
+    def make_add_unit_request(self, **kwargs):
+        """Create and return an "add unit" request.
+
+        Use kwargs to add or override request parameters.
+        """
+        params = {
+            'ServiceName': self.service_name,
+            'NumUnits': 1,
+        }
+        params.update(kwargs)
+        return {
+            'Type': 'Client',
+            'Request': 'AddServiceUnits',
+            'Params': params,
+        }
+
     def make_deploy_request(self, **kwargs):
-        """Create and return a deploy request.
+        """Create and return a "deploy" request.
 
         Use kwargs to add or override request parameters.
         """
@@ -78,17 +100,43 @@
             'Params': params,
         }
 
+    def patch_get_watch(self, return_value):
+        """Patch the Environment.get_watch method.
+
+        When the resulting mock is used as a context manager, the given return
+        value is returned.
+        """
+        get_watch_path = 'quickstart.juju.jujuclient.Environment.get_watch'
+        mock_get_watch = mock.MagicMock()
+        mock_get_watch().__enter__.return_value = iter(return_value)
+        mock_get_watch.reset_mock()
+        return mock.patch(get_watch_path, mock_get_watch)
+
     def processor(self, changeset):
         self.changesets.append(changeset)
         return changeset
 
-    @mock.patch('quickstart.juju.Environment._rpc')
+    @patch_rpc
+    def test_add_unit(self, mock_rpc):
+        # The AddServiceUnits API call is properly generated.
+        self.env.add_unit(self.service_name)
+        mock_rpc.assert_called_once_with(self.make_add_unit_request())
+
+    @patch_rpc
+    def test_add_unit_to_machine(self, mock_rpc):
+        # The AddServiceUnits API call is properly generated when deploying a
+        # unit in a specific machine.
+        self.env.add_unit(self.service_name, machine_spec='0')
+        expected = self.make_add_unit_request(ToMachineSpec='0')
+        mock_rpc.assert_called_once_with(expected)
+
+    @patch_rpc
     def test_deploy(self, mock_rpc):
         # The deploy API call is properly generated.
         self.env.deploy(self.service_name, self.charm_url)
         mock_rpc.assert_called_once_with(self.make_deploy_request())
 
-    @mock.patch('quickstart.juju.Environment._rpc')
+    @patch_rpc
     def test_deploy_config(self, mock_rpc):
         # The deploy API call is properly generated when passing settings.
         self.env.deploy(
@@ -98,7 +146,7 @@
             Config={'key1': 'value1', 'key2': '42'})
         mock_rpc.assert_called_once_with(expected)
 
-    @mock.patch('quickstart.juju.Environment._rpc')
+    @patch_rpc
     def test_deploy_constraints(self, mock_rpc):
         # The deploy API call is properly generated when passing constraints.
         constraints = {'cpu-cores': 8, 'mem': 16}
@@ -107,15 +155,14 @@
         expected = self.make_deploy_request(Constraints=constraints)
         mock_rpc.assert_called_once_with(expected)
 
-    @mock.patch('quickstart.juju.Environment._rpc')
-    def test_deploy_to(self, mock_rpc):
-        # The deploy API call is properly generated when passing a machine
-        # specification.
-        self.env.deploy(self.service_name, self.charm_url, to=0)
-        expected = self.make_deploy_request(ToMachineSpec='0')
+    @patch_rpc
+    def test_deploy_no_units(self, mock_rpc):
+        # The deploy API call is properly generated when passing zero units.
+        self.env.deploy(self.service_name, self.charm_url, num_units=0)
+        expected = self.make_deploy_request(NumUnits=0)
         mock_rpc.assert_called_once_with(expected)
 
-    @mock.patch('quickstart.juju.Environment._rpc')
+    @patch_rpc
     def test_deploy_bundle(self, mock_rpc):
         # The deploy bundle call is properly generated.
         self.env.deploy_bundle('name: contents')
@@ -126,7 +173,7 @@
         }
         mock_rpc.assert_called_once_with(expected)
 
-    @mock.patch('quickstart.juju.Environment._rpc')
+    @patch_rpc
     def test_deploy_bundle_with_name(self, mock_rpc):
         # The deploy bundle call is properly generated when passing a name.
         self.env.deploy_bundle('name: contents', name='name')
@@ -137,58 +184,75 @@
         }
         mock_rpc.assert_called_once_with(expected)
 
-    @mock.patch('quickstart.juju.jujuclient.Watcher._rpc')
-    def test_watch_changes(self, mock_rpc):
+    @patch_rpc
+    def test_expose(self, mock_rpc):
+        # The expose API call is properly generated.
+        self.env.expose(self.service_name)
+        expected = {
+            'Type': 'Client',
+            'Request': 'ServiceExpose',
+            'Params': {'ServiceName': self.service_name},
+        }
+        mock_rpc.assert_called_once_with(expected)
+
+    def test_get_status(self):
+        # The current status of the Juju environment is properly returned.
+        changeset1 = ['change1', 'change2']
+        changeset2 = ['change3']
+        with self.patch_get_watch([changeset1, changeset2]) as mock_get_watch:
+            status = self.env.get_status()
+        # The get_status call only waits for the first changeset.
+        self.assertEqual(changeset1, status)
+        # The watcher is correctly closed.
+        self.assertEqual(1, mock_get_watch().__exit__.call_count)
+
+    def test_watch_changes(self):
         # It is possible to watch for changes using a processor callable.
         changeset1 = ['change1', 'change2']
         changeset2 = ['change3']
-        mock_rpc.side_effect = [
-            # Define the response to the watcher's start call.
-            {'Response': {}, 'AllWatcherId': 42},
-            # Define two responses to the two subsequent next calls.
-            {'Response': {}, 'Deltas': changeset1},
-            {'Response': {}, 'Deltas': changeset2},
-            # Define the response to the watcher's stop call.
-            {'Response': {}},
-        ]
-        watcher = self.env.watch_changes(self.processor)
-        # The first set of changes is correctly returned.
-        changeset = watcher.next()
-        self.assertEqual(changeset1, changeset)
-        # The second set of changes is correctly returned.
-        changeset = watcher.next()
-        self.assertEqual(changeset2, changeset)
+        with self.patch_get_watch([changeset1, changeset2]) as mock_get_watch:
+            watcher = self.env.watch_changes(self.processor)
+            # The first set of changes is correctly returned.
+            changeset = watcher.next()
+            self.assertEqual(changeset1, changeset)
+            # The second set of changes is correctly returned.
+            changeset = watcher.next()
+            self.assertEqual(changeset2, changeset)
         # All the changes have been processed.
         self.assertEqual([changeset1, changeset2], self.changesets)
         # Ensure the API has been used properly.
-        mock_rpc.assert_has_calls([
-            mock.call({'Type': 'Client', 'Request': 'WatchAll', 'Params': {}}),
-            mock.call({'Type': 'AllWatcher', 'Request': 'Next', 'Id': 42}),
-            mock.call({'Type': 'AllWatcher', 'Request': 'Next', 'Id': 42}),
-        ])
-
-    @mock.patch('quickstart.juju.jujuclient.Watcher._rpc')
-    def test_watch_closed(self, mock_rpc):
+        mock_get_watch().__enter__.assert_called_once_with()
+
+    def test_watch_changes_map(self):
+        # The processor callable can be used to modify changes.
+        changeset1 = ['change1', 'change2']
+        changeset2 = ['change3']
+        with self.patch_get_watch([changeset1, changeset2]):
+            watcher = self.env.watch_changes(len)
+            changesets = list(watcher)
+        self.assertEqual([len(changeset1), len(changeset2)], changesets)
+
+    def test_watch_changes_filter(self):
+        # The processor callable can be used to filter changes.
+        changeset1 = ['change1', 'change2']
+        changeset2 = ['change3']
+        processor = lambda changes: None if len(changes) == 1 else changes
+        with self.patch_get_watch([changeset1, changeset2]):
+            watcher = self.env.watch_changes(processor)
+            changesets = list(watcher)
+        self.assertEqual([changeset1], changesets)
+
+    def test_watch_closed(self):
         # A stop API call on the AllWatcher is performed when the watcher is
         # garbage collected.
-        mock_rpc.side_effect = [
-            # Define the response to the watcher's start call.
-            {'Response': {}, 'AllWatcherId': 42},
-            # Define a response to a next call.
-            {'Response': {}, 'Deltas': ['change1', 'change2']},
-            # Define the response to the watcher's stop call.
-            {'Response': {}},
-        ]
-        watcher = self.env.watch_changes(self.processor)
-        # The first set of changes is correctly returned.
-        watcher.next()
-        del watcher
+        changeset = ['change1', 'change2']
+        with self.patch_get_watch([changeset]) as mock_get_watch:
+            watcher = self.env.watch_changes(self.processor)
+            # The first set of changes is correctly returned.
+            watcher.next()
+            del watcher
         # Ensure the API has been used properly.
-        mock_rpc.assert_has_calls([
-            mock.call({'Type': 'Client', 'Request': 'WatchAll', 'Params': {}}),
-            mock.call({'Type': 'AllWatcher', 'Request': 'Next', 'Id': 42}),
-            mock.call({'Type': 'AllWatcher', 'Request': 'Stop', 'Id': 42}),
-        ])
+        self.assertEqual(1, mock_get_watch().__exit__.call_count)
 
 
 class TestWebSocketConnection(unittest.TestCase):

=== modified file 'quickstart/tests/test_manage.py'
--- quickstart/tests/test_manage.py	2013-11-13 12:23:36 +0000
+++ quickstart/tests/test_manage.py	2013-11-18 16:54:22 +0000
@@ -356,10 +356,11 @@
         mock_app.connect.assert_called_once_with(
             mock_app.get_api_url(), options.admin_secret)
         mock_app.deploy_gui.assert_called_once_with(
-            mock_app.connect(), settings.JUJU_GUI_NAME,
-            charm_url=options.charm_url)
+            mock_app.connect(), settings.JUJU_GUI_NAME, '0',
+            charm_url=options.charm_url,
+            check_preexisting=mock_app.bootstrap())
         mock_app.watch.assert_called_once_with(
-            mock_app.connect(), settings.JUJU_GUI_NAME)
+            mock_app.connect(), mock_app.deploy_gui())
         mock_open.assert_called_once_with(
             'https://{}'.format(mock_app.watch()))
         self.assertFalse(mock_app.deploy_bundle.called)

=== modified file 'quickstart/tests/test_utils.py'
--- quickstart/tests/test_utils.py	2013-11-13 12:23:36 +0000
+++ quickstart/tests/test_utils.py	2013-11-18 16:54:22 +0000
@@ -178,6 +178,79 @@
         mock_call.assert_called_once_with('juju', 'switch')
 
 
+class TestGetServiceInfo(helpers.WatcherDataTestsMixin, unittest.TestCase):
+
+    def test_service_and_unit(self):
+        # The data about the given service and unit is correctly returned.
+        service_change = self.make_service_change()
+        unit_change = self.make_unit_change()
+        status = [service_change, unit_change]
+        expected = (service_change[2], unit_change[2])
+        self.assertEqual(expected, utils.get_service_info(status, 'my-gui'))
+
+    def test_service_only(self):
+        # The data about the given service without units is correctly returned.
+        service_change = self.make_service_change()
+        status = [service_change]
+        expected = (service_change[2], None)
+        self.assertEqual(expected, utils.get_service_info(status, 'my-gui'))
+
+    def test_service_removed(self):
+        # A tuple (None, None) is returned if the service is being removed.
+        status = [
+            self.make_service_change(action='remove'),
+            self.make_unit_change(),
+        ]
+        expected = (None, None)
+        self.assertEqual(expected, utils.get_service_info(status, 'my-gui'))
+
+    def test_another_service(self):
+        # A tuple (None, None) is returned if the service is not found.
+        status = [
+            self.make_service_change(data={'Name': 'another-service'}),
+            self.make_unit_change(),
+        ]
+        expected = (None, None)
+        self.assertEqual(expected, utils.get_service_info(status, 'my-gui'))
+
+    def test_service_not_alive(self):
+        # A tuple (None, None) is returned if the service is not alive.
+        status = [
+            self.make_service_change(data={'Life': 'dying'}),
+            self.make_unit_change(),
+        ]
+        expected = (None, None)
+        self.assertEqual(expected, utils.get_service_info(status, 'my-gui'))
+
+    def test_unit_removed(self):
+        # The unit data is not returned if the unit is being removed.
+        service_change = self.make_service_change()
+        status = [service_change, self.make_unit_change(action='remove')]
+        expected = (service_change[2], None)
+        self.assertEqual(expected, utils.get_service_info(status, 'my-gui'))
+
+    def test_another_unit(self):
+        # The unit data is not returned if the unit belongs to another service.
+        service_change = self.make_service_change()
+        status = [
+            service_change,
+            self.make_unit_change(data={'Service': 'another-service'}),
+        ]
+        expected = (service_change[2], None)
+        self.assertEqual(expected, utils.get_service_info(status, 'my-gui'))
+
+    def test_no_services(self):
+        # A tuple (None, None) is returned no services are found.
+        status = [self.make_unit_change()]
+        expected = (None, None)
+        self.assertEqual(expected, utils.get_service_info(status, 'my-gui'))
+
+    def test_no_entities(self):
+        # A tuple (None, None) is returned no entities are found.
+        expected = (None, None)
+        self.assertEqual(expected, utils.get_service_info([], 'my-gui'))
+
+
 class TestParseBundle(
         helpers.BundleFileTestsMixin, helpers.ValueErrorTestsMixin,
         unittest.TestCase):

=== modified file 'quickstart/utils.py'
--- quickstart/utils.py	2013-11-13 12:23:36 +0000
+++ quickstart/utils.py	2013-11-18 16:54:22 +0000
@@ -111,6 +111,31 @@
         return match.groups()[0]
 
 
+def get_service_info(status, service_name):
+    """Retrieve information on the given service and on its first alive unit.
+
+    Return a tuple containing two values: (service data, unit data).
+    Each value can be:
+        - a dictionary of data about the given entity (service or unit) as
+          returned by the Juju watcher;
+        - None, if the entity is not present in the Juju environment.
+    If the service data is None, the unit data is always None.
+    """
+    services = [
+        data for entity, action, data in status if
+        (entity == 'service') and (action != 'remove') and
+        (data['Name'] == service_name) and (data['Life'] == 'alive')
+    ]
+    if not services:
+        return None, None
+    units = [
+        data for entity, action, data in status if
+        entity == 'unit' and action != 'remove' and
+        data['Service'] == service_name
+    ]
+    return services[0], units[0] if units else None
+
+
 def parse_bundle(bundle_yaml, bundle_name=None):
     """Parse the provided bundle YAML encoded contents.