Merge pull request #2826 from dgageot/nathanleclaire-precreatecheckdoc

Add note about pre-create check and exit code

docs/RELEASE.md

@@ -12,10 +12,10 @@ several "checklist items" which should be documented.  This document is intended
 to cover the current Docker Machine release process.  It is written for Docker
 Machine core maintainers who might find themselves performing a release.
 
-1. **Get a GITHUB_TOKEN** Check that you have a proper `GITHUB_TOKEN`. This
-   token needs only to have the `repo` scope. The token can be created on github
-   in the settings > Personal Access Token menu.
-1. **Run the release script** At the root of the project, run the following
+1.  **Get a GITHUB_TOKEN** Check that you have a proper `GITHUB_TOKEN`. This
+    token needs only to have the `repo` scope. The token can be created on github
+    in the settings > Personal Access Token menu.
+2.  **Run the release script** At the root of the project, run the following
     command `GITHUB_TOKEN=XXXX script/release.sh X.Y.Z` where `XXXX` is the
     value of the GITHUB_TOKEN generated, `X.Y.Z` the version to release
     ( Explicitly excluding the 'v' prefix, the script takes care of it.). As of
@@ -23,18 +23,18 @@ Machine core maintainers who might find themselves performing a release.
     script has been built to be as resilient as possible, cleaning everything
     it does along its way if necessary. You can run it many times in a row,
     fixing the various bits along the way.
-1. **Update the changelog on github** -- The script generated a list of all
-   commits since last release. You need to edit this manually, getting rid of
-   non critical details, and putting emphasis to what need our users attention.
-1.  **Update the CHANGELOG.md** -- Add the same notes from the previous step to
+3.  **Update the changelog on github** -- The script generated a list of all
+    commits since last release. You need to edit this manually, getting rid of
+    non critical details, and putting emphasis to what need our users attention.
+4.  **Update the CHANGELOG.md** -- Add the same notes from the previous step to
     the `CHANGELOG.md` file in the repository.
-1. **Update the Documentation** -- Ensure that the `docs` branch on GitHub
+5.  **Update the Documentation** -- Ensure that the `docs` branch on GitHub
     (which the Docker docs team uses to deploy from) is up to date with the
     changes to be deployed from the release branch / master.
-1. **Verify the Installation** -- Copy and paste the suggested commands in the
+6.  **Verify the Installation** -- Copy and paste the suggested commands in the
     installation notes to ensure that they work properly.  Best of all, grab an
     (uninvolved) buddy and have them try it.  `docker-machine -v` should give
     them the released version once they have run the install commands.
-1. (Optional) **Drink a Glass of Wine** -- You've worked hard on this release.
+7.  (Optional) **Drink a Glass of Wine** -- You've worked hard on this release.
     You deserve it.  For wine suggestions, please consult your friendly
     neighborhood sommelier.

docs/drivers/aws.md

@@ -99,7 +99,6 @@ Environment variables and default values:
 | `--amazonec2-monitoring`                 | -                       | `false`          |
 | `--amazonec2-use-ebs-optimized-instance` | -                       | `false`          |
 
-
 ## Security Group
 
 Note that a security group will be created and associated to the host. This security group will have the following ports opened inbound :
@@ -110,4 +109,3 @@ Note that a security group will be created and associated to the host. This secu
 
 If you specify a security group yourself using the `--amazonec2-security-group` flag, the above ports will be checked and opened and the security group modified.
 If you want more ports to be opened, like application specific ports, use the aws console and modify the configuration manually.
-

docs/drivers/generic.md

@@ -34,7 +34,7 @@ Options:
 Environment variables and default values:
 
 | CLI option                 | Environment variable | Default                   |
-|----------------------------|----------------------|---------------------------|
+| -------------------------- | -------------------- | ------------------------- |
 | **`--generic-ip-address`** | `GENERIC_IP_ADDRESS` | -                         |
 | `--generic-ssh-key`        | `GENERIC_SSH_KEY`    | _(defers to `ssh-agent`)_ |
 | `--generic-ssh-user`       | `GENERIC_SSH_USER`   | `root`                    |

docs/get-started-cloud.md

@@ -95,10 +95,11 @@ Docker Machine drivers are available for several other cloud providers. For a fu
 
 ### Docker Machine command and driver reference
 
-  * `docker-machine` [create](https://docs.docker.com/machine/reference/create/) command
-  * [Driver options and operating system defaults](https://docs.docker.com/machine/drivers/os-base/)
+-   `docker-machine` [create](https://docs.docker.com/machine/reference/create/) command
+-   [Driver options and operating system defaults](https://docs.docker.com/machine/drivers/os-base/)
 
 ### 3rd-party driver plugins
+
   Several Docker Machine driver plugins for use with other cloud platforms are available from 3rd party contributors. These are use-at-your-own-risk plugins, not maintained by or formally associated with Docker.
 
   See [Available driver plugins](https://github.com/docker/machine/blob/master/docs/AVAILABLE_DRIVER_PLUGINS.md) in the docker/machine repo on GitHub.

docs/reference/create.md

@@ -224,3 +224,15 @@ Example create:
 This will set the swarm scheduling strategy to "binpack" (pack in containers as
 tightly as possible per host instead of spreading them out), and the "heartbeat"
 interval to 5 seconds.
+
+## Pre-create check
+
+Since many drivers require a certain set of conditions to be in place before
+they can successfully perform a create (e.g. VirtualBox should be installed, or
+the provided API credentials should be valid), Docker Machine has a "pre-create
+check" which is specified at the driver level.
+
+If this pre-create check succeeds, Docker Machine will proceed with the creation
+as normal.  If the pre-create check fails, the Docker Machine process will exit
+with status code 3 to indicate that the source of the non-zero exit was the
+pre-create check failing.