From 2cf681d792be77bb5ec69987b95b78b428854a48 Mon Sep 17 00:00:00 2001 From: Evan Hazlett Date: Mon, 2 Mar 2015 19:49:15 -0500 Subject: [PATCH 1/3] initial driver spec draft Signed-off-by: Evan Hazlett --- drivers/SPEC.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 drivers/SPEC.md diff --git a/drivers/SPEC.md b/drivers/SPEC.md new file mode 100644 index 0000000000..a57b3611a9 --- /dev/null +++ b/drivers/SPEC.md @@ -0,0 +1,84 @@ +> 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. + +# 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. + From d00e67b3f7875ec26f84d6a237fe75a33e452154 Mon Sep 17 00:00:00 2001 From: Evan Hazlett Date: Tue, 3 Mar 2015 07:15:07 -0500 Subject: [PATCH 2/3] elaborate on testing for the driver spec Signed-off-by: Evan Hazlett --- drivers/SPEC.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/drivers/SPEC.md b/drivers/SPEC.md index a57b3611a9..8e27f83caf 100644 --- a/drivers/SPEC.md +++ b/drivers/SPEC.md @@ -68,7 +68,8 @@ current state of the instance (running, stopped, error, etc). This should return an error on failure. # Testing -Testing is strongly recommended for drivers. +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 From 9404aa2f88029d1cf3232c23a1589a42eff5abc8 Mon Sep 17 00:00:00 2001 From: Evan Hazlett Date: Tue, 3 Mar 2015 11:51:56 -0800 Subject: [PATCH 3/3] move driver spec to docs Signed-off-by: Evan Hazlett --- drivers/SPEC.md => docs/DRIVER_SPEC.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename drivers/SPEC.md => docs/DRIVER_SPEC.md (100%) diff --git a/drivers/SPEC.md b/docs/DRIVER_SPEC.md similarity index 100% rename from drivers/SPEC.md rename to docs/DRIVER_SPEC.md