From f7fbd39925613229465269778ed21eb72ba0e3d5 Mon Sep 17 00:00:00 2001 From: Evan Hazlett Date: Mon, 30 Mar 2015 19:13:05 -0400 Subject: [PATCH 1/2] driver doc updates Signed-off-by: Evan Hazlett --- docs/DRIVER_SPEC.md | 131 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 129 insertions(+), 2 deletions(-) diff --git a/docs/DRIVER_SPEC.md b/docs/DRIVER_SPEC.md index 8e27f83caf..bb6fcb52a3 100644 --- a/docs/DRIVER_SPEC.md +++ b/docs/DRIVER_SPEC.md @@ -1,5 +1,3 @@ -> DRAFT - # Machine Driver Specification v1 This is the standard configuration and specification for version 1 drivers. @@ -13,6 +11,9 @@ 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 @@ -83,3 +84,129 @@ 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. +# Implementation +The following describes what is needed to create a Machine Driver. + +As mentioned, please review the [Driver Interface](https://github.com/docker/machine/blob/master/drivers/drivers.go#L23) for full details. + +## Definition +All drivers use a struct for its basic definition: + +``` +type Driver struct { + MachineName string + IPAddress string + SSHUser string + SSHPort int + CaCertPath string + PrivateKeyPath string + DriverKeyPath string + SwarmMaster bool + SwarmHost string + SwarmDiscovery string + storePath string +} +``` + +Each driver must then use an `init` func to "register" the driver: + +``` +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", + }, + } +} +``` + +You will then need to implement the various methods defined in the Driver +interface: + +``` +// AuthorizePort authorizes a port for machine access +AuthorizePort(ports []*Port) error + +// Create a host using the driver's config +Create() error + +// DeauthorizePort removes a port for machine access +DeauthorizePort(ports []*Port) error + +// DriverName returns the name of the driver as it is registered +DriverName() string + +// GetIP returns an IP or hostname that this host is available at +// e.g. 1.2.3.4 or docker-host-d60b70a14d3a.cloudapp.net +GetIP() (string, error) + +// GetMachineName returns the name of the machine +GetMachineName() string + +// GetSSHHostname returns hostname for use with ssh +GetSSHHostname() (string, error) + +// GetSSHKeyPath returns key path for use with ssh +GetSSHKeyPath() string + +// GetSSHPort returns port for use with ssh +GetSSHPort() (int, error) + +// GetSSHUsername returns username for use with ssh +GetSSHUsername() string + +// GetURL returns a Docker compatible host URL for connecting to this host +// e.g. tcp://1.2.3.4:2376 +GetURL() (string, error) + +// GetState returns the state that the host is in (running, stopped, etc) +GetState() (state.State, error) + +// GetProviderType returns whether the instance is local/remote +GetProviderType() provider.ProviderType + +// Kill stops a host forcefully +Kill() error + +// PreCreateCheck allows for pre-create operations to make sure a driver is ready for creation +PreCreateCheck() error + +// Remove a host +Remove() error + +// Restart a host. This may just call Stop(); Start() if the provider does not +// have any special restart behaviour. +Restart() error + +// SetConfigFromFlags configures the driver with the object that was returned +// by RegisterCreateFlags +SetConfigFromFlags(flags DriverOptions) error + +// Start a host +Start() error + +// Stop a host gracefully +Stop() error +``` From dc2dcfd79b04df8dc428b7462046aaa4c36c9e61 Mon Sep 17 00:00:00 2001 From: Evan Hazlett Date: Wed, 1 Apr 2015 15:11:31 -0400 Subject: [PATCH 2/2] updated docs per comments Signed-off-by: Evan Hazlett --- docs/DRIVER_SPEC.md | 80 +++++---------------------------------------- 1 file changed, 8 insertions(+), 72 deletions(-) diff --git a/docs/DRIVER_SPEC.md b/docs/DRIVER_SPEC.md index bb6fcb52a3..e4bcc79847 100644 --- a/docs/DRIVER_SPEC.md +++ b/docs/DRIVER_SPEC.md @@ -85,12 +85,13 @@ will need to make sure it is compliant with the Docker license terms (non-GPL). For more information, contact a project maintainer. # Implementation -The following describes what is needed to create a Machine Driver. +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. -As mentioned, please review the [Driver Interface](https://github.com/docker/machine/blob/master/drivers/drivers.go#L23) for full details. +For details see the [Driver Interface](https://github.com/docker/machine/blob/master/drivers/drivers.go#L24). -## Definition -All drivers use a struct for its basic definition: +To provide this functionality, most drivers use a struct similar to the following: ``` type Driver struct { @@ -142,71 +143,6 @@ func GetCreateFlags() []cli.Flag { } ``` -You will then need to implement the various methods defined in the Driver -interface: - -``` -// AuthorizePort authorizes a port for machine access -AuthorizePort(ports []*Port) error - -// Create a host using the driver's config -Create() error - -// DeauthorizePort removes a port for machine access -DeauthorizePort(ports []*Port) error - -// DriverName returns the name of the driver as it is registered -DriverName() string - -// GetIP returns an IP or hostname that this host is available at -// e.g. 1.2.3.4 or docker-host-d60b70a14d3a.cloudapp.net -GetIP() (string, error) - -// GetMachineName returns the name of the machine -GetMachineName() string - -// GetSSHHostname returns hostname for use with ssh -GetSSHHostname() (string, error) - -// GetSSHKeyPath returns key path for use with ssh -GetSSHKeyPath() string - -// GetSSHPort returns port for use with ssh -GetSSHPort() (int, error) - -// GetSSHUsername returns username for use with ssh -GetSSHUsername() string - -// GetURL returns a Docker compatible host URL for connecting to this host -// e.g. tcp://1.2.3.4:2376 -GetURL() (string, error) - -// GetState returns the state that the host is in (running, stopped, etc) -GetState() (state.State, error) - -// GetProviderType returns whether the instance is local/remote -GetProviderType() provider.ProviderType - -// Kill stops a host forcefully -Kill() error - -// PreCreateCheck allows for pre-create operations to make sure a driver is ready for creation -PreCreateCheck() error - -// Remove a host -Remove() error - -// Restart a host. This may just call Stop(); Start() if the provider does not -// have any special restart behaviour. -Restart() error - -// SetConfigFromFlags configures the driver with the object that was returned -// by RegisterCreateFlags -SetConfigFromFlags(flags DriverOptions) error - -// Start a host -Start() error - -// Stop a host gracefully -Stop() error -``` +## Examples +You can reference the existing [Drivers](https://github.com/docker/machine/tree/master/drivers) +as well.