docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #694 from ehazlett/driver-spec 

Proposal: driver spec v1
This commit is contained in:
Evan Hazlett 2015-03-06 04:47:40 -06:00
parent 2121382d08 9404aa2f88
commit 2045708e70
1 changed files with 85 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
docs/DRIVER_SPEC.md Normal file
View File

@ -0,0 +1,85 @@
> DRAFT
# 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.
## 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.
## Maintainer
To be supported as an official driver, it will need to be maintained. There
can be multiple driver maintainers and they will be identified in the
maintainers file.
# 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 contributors are strongly encouraged to maintain the driver to keep
it supported. We recommend and encourage contributors to join in the weekly
meetings to give feedback and participate in the development around Machine.
Driver maintainers will be notified and consulted for issues regarding their
driver.
# Third Party Libraries
If you want to use a third party library to interact with the provider, you
will need to make sure it is compliant with the Docker license terms (non-GPL).
For more information, contact a project maintainer.