Update provisioning internals docs

 - Placement directives
 - Availability zone spread

Also, changed to use Markdown format.
use the mgo built in remove rather than a custom one
UnShareEnvirionment

Add a new client-side API function: UnShareEnvironment which denies
the given environment user access to the environment.
Merge pull request #679 from voidspace/waitfor-replicaset

Remove the Remove

replicaset/replicaset_test : get rid of extraneous calls to Remove

Remove is a slow operation, and we're seeing spurious failures in CI here. We create a bunch of mongo instances and defer removing them from the replicaset. We destroy them immediately after removal, and then destroy the root, so the Remove is extraneous. This should improve test reliability.
fix merge conflicts
Merge pull request #697 from waigani/unshare-environ

UnShareEnvirionment

Add a new client-side API function, UnShareEnvironment, which denies
the given environment user access to the environment.
Improved machine agent test setup functionality

In preparation for upcoming upgrade changes:
- machines created by primeAgent now have a pinger running so that
  EnsureAvailability can be used in tests to create additional state
  servers
- separated machine configuration from creation in primeAgent to allow
  machines created through other means (e.g. EnsureAvailability) to
  still be configured for use with machine agents
apiserver/admin: Restrict user logins

Any user login will fail unless that user exists in the environment.
Update blobstore dependency to pick up new checksum behaviour
Merge branch 'master' of https://github.com/juju/juju into login-environ-user-only
Merge pull request #712 from wallyworld/update-blobstore

Update blobstore dependency to pick up new checksum behaviour

Fixes: https://bugs.launchpad.net/bugs/1364750
cmd/jujud: synchronise state server upgrades

Use state's UpgradeInfo to synchronise state server upgrades. Overview:

- after restarting into a new tools version, master state servers will
  wait up to 15 minutes for any other state servers to indicate they
  are ready for upgrade. A downgrade to the previous tools version
  will occur if this wait times out.
- secondary state servers will wait until the master has completed its
  upgrade (to allow DB schema migrations to happen first)
- as state servers complete their upgrades they report this to the
  UpgradeInfo document. The document is archived once the last state
  server completes its upgrade.
Merge pull request #702 from waigani/login-environ-user-only

apiserver/admin: Restrict user logins

Any user login will fail unless that user exists in the environment.
Add new wrench points for upgrade-steps worker
Merge pull request #709 from mjs/upgrade-sync

cmd/jujud: synchronise state server upgrades

Use state's UpgradeInfo to synchronise state server upgrades. Overview:
    
- after restarting into a new tools version, master state servers will wait up to 15 minutes for any other state servers to indicate they are ready for upgrade. A downgrade to the previous tools version will occur if this wait times out.
- secondary state servers will wait until the master has completed its upgrade (to allow DB schema migrations to happen first)
- as state servers complete their upgrades they report this to the UpgradeInfo document. The document is archived once the last state server completes its upgrade.

Note that some refactoring to the implementation and tests is planned immediately after this PR lands. I didn't include them here because I didn't want to clutter up this PR any further.
Merge pull request #711 from wallyworld/default-lts-trusty

Change hard coded series fallback for LatestLtsSeries() to trusty

Fixes:
https://bugs.launchpad.net/bugs/1315473
https://bugs.launchpad.net/bugs/1363971

The LatestLtsSeries() detection had a hard coded fallback to "precise" when the call to 'distro-info --lts' fails. The fallback is changed to "trusty".

This covers the add-machine case (whether adding a container or a new machine) where the default-series config value is not specified.
cmd/jujud: avoid duplicate code for counting upgrade attempts in upgrade tests
cmd/jujud: avoid duplication in the 2 "success" upgrade test cases
cmd/jujud: shorten upgrade test helper names

Makes the tests a little more readable.
cmd/jujud: rationalise machine & config handling in upgrade tests

These tests have always been a bit confusing because machine-0 and its
config were being stored on the test suite, with various helper
methods magically using them as required. Data associated with other
machines have always been stored in local variables and passed around.

This change makes the data for machine-0 be handled consistently. This
makes for more explicit, clearer tests and has allowed for various
cleanups.