Permalink
Browse files

Lint all Markdown documents

Signed-off-by: David Gageot <david@gageot.net>
  • Loading branch information...
dgageot committed Nov 27, 2015
1 parent e0998d0 commit 68e6e3f905856bc1d93cb5c1e99cc3b3ac900022
Showing with 1,129 additions and 1,231 deletions.
  1. +187 −180 CHANGELOG.md
  2. +35 −38 CONTRIBUTING.md
  3. +10 −10 README.md
  4. +5 −2 ROADMAP.md
  5. +12 −12 docs/AVAILABLE_DRIVER_PLUGINS.md
  6. +43 −31 docs/DRIVER_SPEC.md
  7. +8 −9 docs/README.md
  8. +61 −61 docs/RELEASE.md
  9. +30 −32 docs/drivers/aws.md
  10. +23 −22 docs/drivers/azure.md
  11. +9 −8 docs/drivers/digital-ocean.md
  12. +10 −9 docs/drivers/exoscale.md
  13. +23 −26 docs/drivers/gce.md
  14. +1 −1 docs/drivers/generic.md
  15. +13 −12 docs/drivers/hyper-v.md
  16. +14 −14 docs/drivers/index.md
  17. +48 −47 docs/drivers/openstack.md
  18. +9 −9 docs/drivers/os-base.md
  19. +11 −10 docs/drivers/rackspace.md
  20. +18 −17 docs/drivers/soft-layer.md
  21. +12 −12 docs/drivers/virtualbox.md
  22. +17 −16 docs/drivers/vm-cloud.md
  23. +8 −7 docs/drivers/vm-fusion.md
  24. +16 −15 docs/drivers/vsphere.md
  25. +53 −75 docs/get-started-cloud.md
  26. +64 −86 docs/get-started.md
  27. +14 −15 docs/index.md
  28. +28 −28 docs/install-machine.md
  29. +22 −23 docs/migrate-to-machine.md
  30. +8 −10 docs/reference/active.md
  31. +2 −4 docs/reference/config.md
  32. +109 −125 docs/reference/create.md
  33. +38 −48 docs/reference/env.md
  34. +1 −1 docs/reference/help.md
  35. +19 −20 docs/reference/index.md
  36. +41 −51 docs/reference/inspect.md
  37. +5 −7 docs/reference/ip.md
  38. +7 −9 docs/reference/kill.md
  39. +19 −25 docs/reference/ls.md
  40. +3 −5 docs/reference/regenerate-certs.md
  41. +2 −4 docs/reference/restart.md
  42. +8 −10 docs/reference/rm.md
  43. +9 −11 docs/reference/scp.md
  44. +34 −44 docs/reference/ssh.md
  45. +2 −4 docs/reference/start.md
  46. +2 −4 docs/reference/status.md
  47. +7 −9 docs/reference/stop.md
  48. +7 −9 docs/reference/upgrade.md
  49. +2 −4 docs/reference/url.md
View

Large diffs are not rendered by default.

Oops, something went wrong.
View
@@ -18,9 +18,9 @@ guidelines](https://github.com/docker/docker/blob/master/CONTRIBUTING.md).
The requirements to build Machine are:
1. A running instance of Docker or a Golang 1.5 development environment
2. The `bash` shell
3. [Make](https://www.gnu.org/software/make/)
1. A running instance of Docker or a Golang 1.5 development environment
2. The `bash` shell
3. [Make](https://www.gnu.org/software/make/)
## Build using Docker containers
@@ -33,13 +33,12 @@ To build the `docker-machine` binary using containers, simply run:
Make sure the source code directory is under a correct directory structure to use Go 1.5 vendoring;
example of cloning and preparing the correct environment `GOPATH`:
```
mkdir docker-machine
cd docker-machine
export GOPATH="$PWD"
go get github.com/docker/machine
cd src/github.com/docker/machine
```
mkdir docker-machine
cd docker-machine
export GOPATH="$PWD"
go get github.com/docker/machine
cd src/github.com/docker/machine
At this point, simply run:
@@ -56,6 +55,7 @@ You may call:
to clean-up build results.
## Tests and validation
We use the usual `go` tools for this, to run those commands you need at least the linter which you can
install with `go get -u github.com/golang/lint/golint`
@@ -67,7 +67,6 @@ If you want more indepth validation (vet, lint), and all tests with race detecti
$ make validate
If you make a pull request, it is highly encouraged that you submit tests for
the code that you have added or modified in the same pull request.
@@ -77,7 +76,7 @@ To generate an html code coverage report of the Machine codebase, run:
make coverage-serve
And navigate to http://localhost:8000 (hit `CTRL+C` to stop the server).
And navigate to <http://localhost:8000> (hit `CTRL+C` to stop the server).
### Native build
@@ -211,15 +210,13 @@ Keep in mind that Machine supports environment variables for many of these
flags. So, for instance, you could run the command (substituting, of course,
the proper secrets):
```
$ DRIVER=amazonec2 \
AWS_VPC_ID=vpc-xxxxxxx \
AWS_SECRET_ACCESS_KEY=yyyyyyyyyyyyy \
AWS_ACCESS_KEY_ID=zzzzzzzzzzzzzzzz \
AWS_AMI=ami-12663b7a \
AWS_SSH_USER=ec2-user \
make test-integration test/integration/core
```
$ DRIVER=amazonec2 \
AWS_VPC_ID=vpc-xxxxxxx \
AWS_SECRET_ACCESS_KEY=yyyyyyyyyyyyy \
AWS_ACCESS_KEY_ID=zzzzzzzzzzzzzzzz \
AWS_AMI=ami-12663b7a \
AWS_SSH_USER=ec2-user \
make test-integration test/integration/core
in order to run the core tests on Red Hat Enterprise Linux on Amazon.
@@ -231,11 +228,11 @@ guide you.
At the time of writing, there is:
1. A `core` directory which contains tests that are applicable to all drivers.
2. A `drivers` directory which contains tests that are applicable only to
specific drivers with sub-directories for each provider.
3. A `cli` directory which is meant for testing functionality of the command
line interface, without much regard for driver-specific details.
1. A `core` directory which contains tests that are applicable to all drivers.
2. A `drivers` directory which contains tests that are applicable only to
specific drivers with sub-directories for each provider.
3. A `cli` directory which is meant for testing functionality of the command
line interface, without much regard for driver-specific details.
### Guidelines
@@ -244,27 +241,27 @@ work in progress, but here are some general guidelines from the maintainers:
1. Ideally, each test file should have only one concern.
2. Tests generally should not spin up more than one machine unless the test is
deliberately testing something which involves multiple machines, such as an `ls`
test which involves several machines, or a test intended to create and check
some property of a Swarm cluster.
deliberately testing something which involves multiple machines, such as an `ls`
test which involves several machines, or a test intended to create and check
some property of a Swarm cluster.
3. BATS will print the output of commands executed during a test if the test
fails. This can be useful, for instance to dump the magic `$output` variable
that BATS provides and/or to get debugging information.
fails. This can be useful, for instance to dump the magic `$output` variable
that BATS provides and/or to get debugging information.
4. It is not strictly needed to clean up the machines as part of the test. The
BATS wrapper script has a hook to take care of cleaning up all created machines
after each test.
BATS wrapper script has a hook to take care of cleaning up all created machines
after each test.
# Drivers
Docker Machine has several included drivers that supports provisioning hosts
in various providers. If you wish to contribute a driver, we ask the following
to ensure we keep the driver in a consistent and stable state:
- Address issues filed against this driver in a timely manner
- Review PRs for the driver
- Be responsible for maintaining the infrastructure to run unit tests
and integration tests on the new supported environment
- Participate in a weekly driver maintainer meeting
- Address issues filed against this driver in a timely manner
- Review PRs for the driver
- Be responsible for maintaining the infrastructure to run unit tests
and integration tests on the new supported environment
- Participate in a weekly driver maintainer meeting
If you can commit to those, the next step is to make sure the driver adheres
to the [spec](https://github.com/docker/machine/blob/master/docs/DRIVER_SPEC.md).
View
@@ -83,16 +83,16 @@ process, `create` is often where these types of errors show up.
A hang could be due to a variety of factors, but the most common suspect is
networking. Consider the following:
- Are you using a VPN? If so, try disconnecting and see if creation will
succeed without the VPN. Some VPN software aggressively controls routes and
you may need to [manually add the route](https://github.com/docker/machine/issues/1500#issuecomment-121134958).
- Are you connected to a proxy server, corporate or otherwise? If so, take a
look at the `--no-proxy` flag for `env` and at [setting environment variables
for the created Docker Engine](https://docs.docker.com/machine/reference/create/#specifying-configuration-options-for-the-created-docker-engine).
- Are there a lot of host-only interfaces listed by the command `VBoxManage list
hostonlyifs`? If so, this has sometimes been known to cause bugs. Consider
removing the ones you are not using (`VBoxManage hostonlyif remove name`) and
trying machine creation again.
- Are you using a VPN? If so, try disconnecting and see if creation will
succeed without the VPN. Some VPN software aggressively controls routes and
you may need to [manually add the route](https://github.com/docker/machine/issues/1500#issuecomment-121134958).
- Are you connected to a proxy server, corporate or otherwise? If so, take a
look at the `--no-proxy` flag for `env` and at [setting environment variables
for the created Docker Engine](https://docs.docker.com/machine/reference/create/#specifying-configuration-options-for-the-created-docker-engine).
- Are there a lot of host-only interfaces listed by the command `VBoxManage list
hostonlyifs`? If so, this has sometimes been known to cause bugs. Consider
removing the ones you are not using (`VBoxManage hostonlyif remove name`) and
trying machine creation again.
We are keenly aware of this as an issue and working towards a set of solutions
which is robust for all users, so please give us feedback and/or report issues,
View
@@ -14,18 +14,21 @@ For what is coming in specific releases, see our [upcoming
milestones](https://github.com/docker/machine/milestones).)
### Docker Engine / Swarm Configuration
Currently there are only a few things that can be configured in the Docker Engine and Swarm. This will enable more operations such as Engine labels and Swarm strategies.
### Boot2Docker Migration Support
Currently both Machine and Boot2Docker provider similar functionality. This will enable users to migrate from boot2docker to machine.
### Expand Provisioner
Machine currently supports running Boot2Docker for "local" providers and Ubuntu for "remote" providers. This will expand the provisioning capabilities to include other base operating systems such as Red Hat-like distributions and possibly other "just enough" operating systems.
### Windows Experience
Currently, the Machine on Windows experience is not as good as the Mac / Linux. There is no "recommended" path to use Machine and there are several inconsistencies on Windows such as logging and output formatting.
Project Planning
================
# Project Planning
An [Open-Source Planning Process](https://github.com/docker/machine/wiki/Open-Source-Planning-Process) is used to define the Roadmap. [Project Pages](https://github.com/docker/machine/wiki) define the goals for each Milestone and identify current progress.
@@ -16,17 +16,17 @@ pull request adding the relevant information to the list. Submitting your
driver here will allow others to discover it and the core Machine team to keep
you informed of upstream changes.
__NOTE__: The linked repositories are not maintained by or formally associated
**NOTE**: The linked repositories are not maintained by or formally associated
with Docker Inc. Use 3rd party plugins at your own risk.
| Name | Repository | Maintainer GitHub Handle | Maintainer Email |
| ---- | ---------- | ------------------------- | ---------------- |
| Amazon Cloud Formation | https://github.com/jeffellin/machine-cloudformation |[Jeff Ellin](https://github.com/jeffellin) | acf@ellin.com |
| BrightBox | https://github.com/brightbox/docker-machine-driver-brightbox | [NeilW](https://github.com/NeilW) | neil@aldur.co.uk |
| Docker-In-Docker | https://github.com/nathanleclaire/docker-machine-driver-dind | [nathanleclaire](https://github.com/nathanleclaire) | nathan.leclaire@gmail.com |
| HPE OneView | https://github.com/HewlettPackard/docker-machine-oneview | [wenlock](https://github.com/wenlock) | wenlock@hpe.com |
| Packet | https://github.com/packethost/docker-machine-driver-packet | [betawaffle](https://github.com/betawaffle) | andy@packet.net |
| Parallels for OSX | https://github.com/Parallels/docker-machine-parallels | [legal90](https://github.com/legal90) | legal90@gmail.com |
| SAKURA CLOUD | https://github.com/yamamoto-febc/docker-machine-sakuracloud | [yamamoto-febc](https://github.com/yamamoto-febc) | yamamoto.febc@gmail.com |
| VULTR | https://github.com/janeczku/docker-machine-vultr | [janeczku](https://github.com/janeczku) | jb@festplatte.eu.org |
| xhyve | https://github.com/zchee/docker-machine-xhyve | [zchee](https://github.com/zchee) | zchee.io@gmail.com |
| Name | Repository | Maintainer GitHub Handle | Maintainer Email |
| ---------------------- | -------------------------------------------------------------- | --------------------------------------------------- | ------------------------- |
| Amazon Cloud Formation | <https://github.com/jeffellin/machine-cloudformation> | [Jeff Ellin](https://github.com/jeffellin) | acf@ellin.com |
| BrightBox | <https://github.com/brightbox/docker-machine-driver-brightbox> | [NeilW](https://github.com/NeilW) | neil@aldur.co.uk |
| Docker-In-Docker | <https://github.com/nathanleclaire/docker-machine-driver-dind> | [nathanleclaire](https://github.com/nathanleclaire) | nathan.leclaire@gmail.com |
| HPE OneView | <https://github.com/HewlettPackard/docker-machine-oneview> | [wenlock](https://github.com/wenlock) | wenlock@hpe.com |
| Packet | <https://github.com/packethost/docker-machine-driver-packet> | [betawaffle](https://github.com/betawaffle) | andy@packet.net |
| Parallels for OSX | <https://github.com/Parallels/docker-machine-parallels> | [legal90](https://github.com/legal90) | legal90@gmail.com |
| SAKURA CLOUD | <https://github.com/yamamoto-febc/docker-machine-sakuracloud> | [yamamoto-febc](https://github.com/yamamoto-febc) | yamamoto.febc@gmail.com |
| VULTR | <https://github.com/janeczku/docker-machine-vultr> | [janeczku](https://github.com/janeczku) | jb@festplatte.eu.org |
| xhyve | <https://github.com/zchee/docker-machine-xhyve> | [zchee](https://github.com/zchee) | zchee.io@gmail.com |
View
@@ -10,79 +10,95 @@ parent="mn_install"
<![end-metadata]-->
# Machine Driver Specification v1
This is the standard configuration and specification for version 1 drivers.
Along with defining how a driver should provision instances, the standard
also discusses behavior and operations Machine expects.
# Requirements
The following are required for a driver to be included as a supported driver
for Docker Machine.
## Base Operating System
The provider must offer a base operating system supported by the Docker Engine.
Currently Machine requires Ubuntu for non-Boot2Docker machines. This will
change in the future.
## API Access
We prefer accessing the provider service via HTTP APIs and strongly recommend
using those over external executables. For example, using the Amazon EC2 API
instead of the EC2 command line tools. If in doubt, contact a project
maintainer.
## SSH
The provider must offer SSH access to control the instance. This does not
have to be public, but must offer it as Machine relies on SSH for system
level maintenance.
# Provider Operations
The following instance operations should be supported by the provider.
## Create
`Create` will launch a new instance and make sure it is ready for provisioning.
This includes setting up the instance with the proper SSH keys and making
sure SSH is available including any access control (firewall). This should
return an error on failure.
## Remove
`Remove` will remove the instance from the provider. This should remove the
instance and any associated services or artifacts that were created as part
of the instance including keys and access groups. This should return an
error on failure.
## Start
`Start` will start a stopped instance. This should ensure the instance is
ready for operations such as SSH and Docker. This should return an error on
failure.
## Stop
`Stop` will stop a running instance. This should ensure the instance is
stopped and return an error on failure.
## Kill
`Kill` will forcibly stop a running instance. This should ensure the instance
is stopped and return an error on failure.
## Restart
`Restart` will restart a running instance. This should ensure the instance
is ready for operations such as SSH and Docker. This should return an error
on failure.
## Status
`Status` will return the state of the instance. This should return the
current state of the instance (running, stopped, error, etc). This should
return an error on failure.
# Testing
Testing is strongly recommended for drivers. Unit tests are preferred as well
as inclusion into the [integration tests](https://github.com/docker/machine#integration-tests).
# Maintaining
Driver plugin maintainers are encouraged to host their own repo and distribute
the driver plugins as executables.
# Implementation
The following describes what is needed to create a Machine Driver. The driver
interface has methods that must be implemented for all drivers. These include
operations such as `Create`, `Remove`, `Start`, `Stop` etc.
@@ -91,47 +107,43 @@ For details see the [Driver Interface](https://github.com/docker/machine/blob/ma
To provide this functionality, you should embed the `drivers.BaseDriver` struct, similar to the following:
```
type Driver struct {
*drivers.BaseDriver
DriverSpecificField string
}
```
type Driver struct {
*drivers.BaseDriver
DriverSpecificField string
}
Each driver must then use an `init` func to "register" the driver:
```
func init() {
drivers.Register("drivername", &drivers.RegisteredDriver{
New: NewDriver,
GetCreateFlags: GetCreateFlags,
})
}
```
func init() {
drivers.Register("drivername", &drivers.RegisteredDriver{
New: NewDriver,
GetCreateFlags: GetCreateFlags,
})
}
## Flags
Driver flags are used for provider specific customizations. To add flags, use
a `GetCreateFlags` func. For example:
```
func GetCreateFlags() []cli.Flag {
return []cli.Flag{
cli.StringFlag{
EnvVar: "DRIVERNAME_TOKEN",
Name: "drivername-token",
Usage: "Provider access token",
},
cli.StringFlag{
EnvVar: "DRIVERNAME_IMAGE",
Name: "drivername-image",
Usage: "Provider Image",
Value: "ubuntu-14-04-x64",
},
func GetCreateFlags() []cli.Flag {
return []cli.Flag{
cli.StringFlag{
EnvVar: "DRIVERNAME_TOKEN",
Name: "drivername-token",
Usage: "Provider access token",
},
cli.StringFlag{
EnvVar: "DRIVERNAME_IMAGE",
Name: "drivername-image",
Usage: "Provider Image",
Value: "ubuntu-14-04-x64",
},
}
}
}
```
## Examples
You can reference the existing [Drivers](https://github.com/docker/machine/tree/master/drivers)
as well.
Oops, something went wrong.

0 comments on commit 68e6e3f

Please sign in to comment.