Add documentation and fix minor bugs in SSH bootstrap process.

Author: tintoy

Makefile

@@ -7,6 +7,9 @@ fmt:
 dev: version fmt
 	go build -o _bin/docker-machine-driver-ddcloud
 
+install: dev
+	go install
+
 # Perform a full (all-platforms) build.
 build: version build-windows64 build-linux64 build-mac64
 
@@ -29,4 +32,4 @@ test: fmt
 	go test -v github.com/DimensionDataResearch/docker-machine-driver-ddcloud/...
 
 version:
-	echo "package main\n\n// ProviderVersion is the current version of the CloudControl driver for Docker Machine.\nconst ProviderVersion = \"v0.1 (`git rev-parse HEAD`)\"" > ./version-info.go
+	echo "package main\n\n// DriverVersion is the current version of the CloudControl driver for Docker Machine.\nconst DriverVersion = \"v0.1 (`git rev-parse HEAD`)\"" > ./version-info.go

README.md

@@ -1,2 +1,59 @@
-# docker-machine-driver-ddcloud
-Docker Machine driver for Dimension Data CloudControl.
+# Docker Machine driver for Dimension Data CloudControl
+
+## Usage
+
+You will need:
+
+* A network domain
+* A VLAN in that network domain (servers will be attached to this VLAN)
+* A firewall rule that permits SSH traffic from your (local) public IPv4 address to the VLAN's IPv4 network
+
+The driver will allocate a public IP address and NAT rule for each machine that it creates.
+
+### Example
+
+```bash
+docker-machine create --driver ddcloud \
+	--ddcloud-region AU \
+	--ddcloud-datacenter AU9 \
+	--ddcloud-networkdomain 'my-docker-domain' \
+	--ddcloud-vlan 'my-docker-vlan' \
+	--ddcloud-ssh-key ~/.ssh/id_rsa \
+	--ddcloud-ssh-bootstrap-password 'throw-away-password' \
+	mydockermachine
+```
+
+If you're running on Windows, just remove the backslashes so the whole command is on a single line.
+
+### Options
+
+The driver supports all Docker Machine commands, and can be configured using the following command-line arguments (or environment variables):
+
+* `ddcloud-user` - The user name used to authenticate to the CloudControl API.  
+Environment: `DD_COMPUTE_USER`
+* `ddcloud-password` - The password used to authenticate to the CloudControl API.  
+Environment: `DD_COMPUTE_PASSWORD`.
+* `ddcloud-region` - The CloudControl region name (e.g. AU, NA, EU, etc).  
+Environment: `DD_COMPUTE_REGION`.
+* `ddcloud-networkdomain` - The name of the target CloudControl network domain.
+* `ddcloud-datacenter` - The name of the CloudControl datacenter (e.g. NA1, AU9) in which the network domain is located.
+* `ddcloud-vlan` - The name of the target CloudControl VLAN.
+* `ddcloud-ssh-user` - The SSH username to use.  
+Default: "root".  
+Environment: `DD_COMPUTE_SSH_USER`
+* `ddcloud-ssh-key` - The SSH key file to use.  
+Environment: `DD_COMPUTE_SSH_KEY`
+* `ddcloud-ssh-port` - The SSH port to use.  
+Default: 22.  
+Environment: `DD_COMPUTE_SSH_PORT`
+* `ddcloud-ssh-bootstrap-password` - The initial SSH password used to bootstrap SSH key authentication.  
+This password is removed once the SSH key has been installed  
+Environment: `DD_COMPUTE_SSH_BOOTSTRAP_PASSWORD`
+
+## Installing the provider
+
+Download the [latest release](https://github.com/DimensionDataResearch/docker-machine-driver-ddcloud/releases) and place the provider executable in the same directory as `docker-machine` executable (or somewhere on your `PATH`).
+
+## Building the provider
+
+If you'd rather run from source, simply run `make install` and you're good to go.

client.go

@@ -33,7 +33,10 @@ func (driver *Driver) getCloudControlClient() (client *compute.Client, err error
 		return
 	}
 
-	driver.client = compute.NewClient(driver.CloudControlRegion, driver.CloudControlUser, driver.CloudControlPassword)
+	client = compute.NewClient(driver.CloudControlRegion, driver.CloudControlUser, driver.CloudControlPassword)
+	client.ConfigureRetry(10, 5*time.Second)
+
+	driver.client = client
 
 	return
 }
@@ -115,34 +118,36 @@ func (driver *Driver) getVLAN() (*compute.VLAN, error) {
 	return client.GetVLAN(driver.VLANID)
 }
 
-// Resolve (find) the target OS image.
-func (driver *Driver) resolveOSImage() error {
-	driver.ImageID = ""
+// Resolve (find) the target network domain by name and data centre Id.
+func (driver *Driver) resolveVLAN() error {
+	driver.VLANID = ""
 
-	networkDomain, err := driver.getNetworkDomain()
-	if err != nil {
-		return err
+	if driver.VLANName == "" {
+		return errors.New("VLAN name has not been configured")
+	}
+
+	var err error
+	if driver.NetworkDomainID == "" {
+		err = driver.resolveNetworkDomain()
+		if err != nil {
+			return err
+		}
 	}
 
 	client, err := driver.getCloudControlClient()
 	if err != nil {
 		return err
 	}
 
-	// Find target OS image.
-	log.Info("Searching for image '%s' in data centre '%s'...", driver.ImageName, networkDomain.DatacenterID)
-
-	image, err := client.FindOSImage(driver.ImageName, networkDomain.DatacenterID)
-	if err == nil {
+	vlan, err := client.GetVLANByName(driver.VLANName, driver.NetworkDomainID)
+	if err != nil {
 		return err
 	}
-	if image == nil {
-		log.Errorf("OS image '%s' was not found in data centre '%s'.", driver.ImageName, networkDomain.DatacenterID)
-
-		return fmt.Errorf("OS image '%s' was not found in data centre '%s'", driver.ImageName, networkDomain.DatacenterID)
+	if vlan == nil {
+		return fmt.Errorf("No VLAN named '%s' was found in network domain '%s' ('%s')", driver.VLANName, driver.NetworkDomainName, driver.NetworkDomainID)
 	}
 
-	driver.ImageID = image.ID
+	driver.VLANID = vlan.ID
 
 	return nil
 }
@@ -161,6 +166,35 @@ func (driver *Driver) getOSImage() (*compute.OSImage, error) {
 	return client.GetOSImage(driver.ImageID)
 }
 
+// Resolve (find) the target OS image.
+func (driver *Driver) resolveOSImage() error {
+	driver.ImageID = ""
+
+	networkDomain, err := driver.getNetworkDomain()
+	if err != nil {
+		return err
+	}
+
+	client, err := driver.getCloudControlClient()
+	if err != nil {
+		return err
+	}
+
+	image, err := client.FindOSImage(driver.ImageName, driver.DataCenterID)
+	if err != nil {
+		return err
+	}
+	if image == nil {
+		log.Errorf("OS image '%s' was not found in data centre '%s'.", driver.ImageName, networkDomain.DatacenterID)
+
+		return fmt.Errorf("OS image '%s' was not found in data centre '%s'", driver.ImageName, networkDomain.DatacenterID)
+	}
+
+	driver.ImageID = image.ID
+
+	return nil
+}
+
 func (driver *Driver) deployServer() (*compute.Server, error) {
 	if driver.isServerCreated() {
 		return nil, fmt.Errorf("Server '%s' already exists (Id = '%s')", driver.MachineName, driver.ServerID)
@@ -181,17 +215,50 @@ func (driver *Driver) deployServer() (*compute.Server, error) {
 		return nil, err
 	}
 
-	log.Debug("Deploying server '%s' ('%s')...", driver.ServerID, driver.MachineName)
+	log.Debugf("Deploying server '%s' ('%s')...", driver.ServerID, driver.MachineName)
 
 	resource, err := client.WaitForDeploy(compute.ResourceTypeServer, driver.ServerID, 15*time.Minute)
 	if err != nil {
 		return nil, err
 	}
 	server := resource.(*compute.Server)
 
-	log.Debug("Server '%s' ('%s') has been successfully provisioned...", driver.ServerID, server.Name)
+	log.Debugf("Server '%s' ('%s') has been successfully deployed...", driver.ServerID, server.Name)
+
+	driver.PrivateIPAddress = *server.Network.PrimaryAdapter.PrivateIPv4Address
+
+	log.Debugf("Creating NAT rule for server '%s' ('%s')...", driver.MachineName, driver.PrivateIPAddress)
+
+	natRule, err := driver.getExistingNATRuleByInternalIP(driver.PrivateIPAddress)
+	if natRule == nil {
+		err = driver.ensurePublicIPAvailable()
+		if err != nil {
+			return nil, err
+		}
+
+		natRuleID, err := client.AddNATRule(driver.NetworkDomainID, driver.PrivateIPAddress, nil)
+		if err != nil {
+			return nil, err
+		}
+		natRule, err = client.GetNATRule(natRuleID)
+		if err != nil {
+			return nil, err
+		}
+		if natRule == nil {
+			return nil, fmt.Errorf("Failed to retrieve newly-created NAT rule '%s' for server '%s'", natRuleID, driver.MachineName)
+		}
+	} else {
+		log.Debugf("NAT rule already exists (Id = '%s').", natRule.ID)
+	}
+
+	driver.IPAddress = natRule.ExternalIPAddress
 
-	driver.IPAddress = *server.Network.PrimaryAdapter.PrivateIPv4Address
+	log.Debugf("Created NAT rule '%s' for server '%s' (Ext:'%s' -> Int:'%s').",
+		driver.NATRuleID,
+		driver.MachineName,
+		driver.IPAddress,
+		driver.PrivateIPAddress,
+	)
 
 	return server, nil
 }
@@ -229,3 +296,69 @@ func (driver *Driver) buildDeploymentConfiguration() (deploymentConfiguration co
 
 	return
 }
+
+// Ensure that at least one public IP address is available in the target network domain.
+func (driver *Driver) ensurePublicIPAvailable() error {
+	if driver.NetworkDomainID == "" {
+		return errors.New("Network domain has not been resolved.")
+	}
+
+	log.Debugf("Verifying that network domain '%s' has a public IP available for server '%s'...", driver.NetworkDomainName, driver.MachineName)
+
+	client, err := driver.getCloudControlClient()
+	if err != nil {
+		return err
+	}
+
+	availableIPs, err := client.GetAvailablePublicIPAddresses(driver.NetworkDomainID)
+	if err != nil {
+		return err
+	}
+
+	if len(availableIPs) == 0 {
+		log.Debugf("There are no available public IPs in network domain '%s'; a new block of public IPs will be allocated.", driver.NetworkDomainID)
+
+		blockID, err := client.AddPublicIPBlock(driver.NetworkDomainID)
+		if err != nil {
+			return err
+		}
+
+		log.Debugf("Allocated new public IP block '%s'.", blockID)
+	}
+
+	return nil
+}
+
+// Find the existing NAT rule (if any) for the specified internal IPv4 address.
+func (driver *Driver) getExistingNATRuleByInternalIP(internalIPAddress string) (*compute.NATRule, error) {
+	if driver.NetworkDomainID == "" {
+		return nil, errors.New("Network domain has not been resolved.")
+	}
+
+	client, err := driver.getCloudControlClient()
+	if err != nil {
+		return nil, err
+	}
+
+	page := compute.DefaultPaging()
+	for {
+		var rules *compute.NATRules
+		rules, err = client.ListNATRules(driver.NetworkDomainID, page)
+		if err != nil {
+			return nil, err
+		}
+		if rules.IsEmpty() {
+			break // We're done
+		}
+
+		for _, rule := range rules.Rules {
+			if rule.InternalIPAddress == internalIPAddress {
+				return &rule, nil
+			}
+		}
+
+		page.Next()
+	}
+
+	return nil, nil
+}