diff --git a/README.md b/README.md index 3c18ff1175..07e03bdaee 100644 --- a/README.md +++ b/README.md @@ -38,9 +38,334 @@ dev virtualbox Running tcp://192.168.99.108:2376 staging * digitalocean Running tcp://104.236.37.134:2376 ``` -## Installation and documentation +Machine creates Docker hosts that are secure by default. The connection between the client and daemon is encrypted and authenticated using TLS security. To get the Docker arguments for a machine use the command: `docker-machine config ` i.e. `docker-machine config dev`. -Full documentation [is available here](https://docs.docker.com/machine/). +You can also get the commands to export environment variables to use with the Docker CLI: `docker-machine env ` i.e. `docker-machine env dev` to show or `$(docker-machine env dev)` to load in your environment. + +## Try it out + +Machine is still in its early stages. If you'd like to try out a preview build, [download it here](https://github.com/docker/machine/releases/latest). + +## Swarm + +Machine can create [Docker Swarm](https://github.com/docker/swarm) clusters. + +First, create a Swarm token. Optionally, you can use another discovery service. +See the Swarm docs for details. + +To create the token, first create a Machine. This example will use VirtualBox. + +``` +$ docker-machine create -d virtualbox local +``` + +Load the Machine configuration into your shell: + +``` +$ $(docker-machine env local) +``` +Then run generate the token using the Swarm Docker image: + +``` +$ docker run swarm create +1257e0f0bbb499b5cd04b4c9bdb2dab3 +``` +Once you have the token, you can create the cluster. + +### Swarm Master + +Create the Swarm master: + +`docker-machine create -d virtualbox --swarm --swarm-master --swarm-discovery token:// swarm-master` + +Replace `` with your random token. This will create the Swarm master. + +### Swarm Nodes + +Now, create more Swarm nodes: + +`docker-machine create -d virtualbox --swarm --swarm-discovery token:// swarm-node-00` + +You now have a Swarm cluster. To connect to the Swarm master, you can use `docker-machine env --swarm swarm-master` + +For example: + +``` +$ docker-machine env --swarm swarm-master +export DOCKER_TLS_VERIFY=yes +export DOCKER_CERT_PATH=/home/ehazlett/.docker/machines/.client +export DOCKER_HOST=tcp://192.168.99.100:3376 +``` + +You can load this into your environment using `$(docker-machine env --swarm swarm-master)`. + +Now you can use the Docker CLI to query: + +``` +$ docker info +Containers: 1 +Nodes: 1 + swarm-node-00: 192.168.99.101:2376 +``` + +## Drivers + +### VirtualBox + +Creates machines locally on [VirtualBox](https://www.virtualbox.org/). Requires VirtualBox to be installed. + +Options: + + - `--virtualbox-boot2docker-url`: The URL of the boot2docker image. Defaults to the latest available version. + - `--virtualbox-disk-size`: Size of disk for the host in MB. Default: `20000` + - `--virtualbox-memory`: Size of memory for the host in MB. Default: `1024` + +### Digital Ocean + +Creates machines on [Digital Ocean](https://www.digitalocean.com/). You need to create a personal access token under "Apps & API" in the Digital Ocean Control Panel and pass that to `docker-machine create` with the `--digitalocean-access-token` option. + +Options: + + - `--digitalocean-access-token`: Your personal access token for the Digital Ocean API. + - `--digitalocean-image`: The name of the Digital Ocean image to use. Default: `docker` + - `--digitalocean-region`: The region to create the droplet in. Default: `nyc3` + - `--digitalocean-size`: The size of the Digital Ocean driver. Default: `512mb` + +### Microsoft Azure + +Create machines on [Microsoft Azure](http://azure.microsoft.com/). + +You need to create a subscription with a cert. Run these commands: + + $ openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem + $ openssl pkcs12 -export -out mycert.pfx -in mycert.pem -name "My Certificate" + $ openssl x509 -inform pem -in mycert.pem -outform der -out mycert.cer + +Go to the Azure portal, go to the "Settings" page, then "Manage Certificates" and upload `mycert.cer`. + +Grab your subscription ID from the portal, then run `docker-machine create` with these details: + + $ docker-machine create -d azure --azure-subscription-id="SUB_ID" --azure-subscription-cert="mycert.pem" + +Options: + + - `--azure-subscription-id`: **required** Your Azure subscription ID. + - `--azure-subscription-cert`: **required** Your Azure subscription cert. + - `--azure-docker-port`: Azure Docker port. Default '2376' + - `--azure-image`: Azure image name. Default is Ubuntu 14.04 LTS x64 [$AZURE_IMAGE] + - `--azure-location`: Azure location. Default is 'West US' [$AZURE_LOCATION] + - `--azure-name`: Azure cloud service name + - `--azure-password`: Azure user password + - `--azure-publish-settings-file`: Azure publish settings file [$AZURE_PUBLISH_SETTINGS_FILE] + - `--azure-size`: Azure size. Default 'Small' [$AZURE_SIZE] + - `--azure-ssh-port`: Azure SSH port. Default '22' + - `--azure-username`: Azure username. Default 'ubuntu' + +Note: the machine name will be used as DNS name for the Cloud Service (e.g. machinename.cloudapp.net) and needs to be unique within Azure. + +### Amazon EC2 + +Create machines on [Amazon Web Services](http://aws.amazon.com). You will need an Access Key ID, Secret Access Key and a VPC ID. To find the VPC ID, login to the AWS console and go to Services -> VPC -> Your VPCs. Select the one where you would like to launch the instance. + +Options: + + - `--amazonec2-access-key`: **required** Your access key id for the Amazon Web Services API. + - `--amazonec2-ami`: The AMI ID of the instance to use Default: `ami-4ae27e22` + - `--amazonec2-instance-type`: The instance type to run. Default: `t2.micro` + - `--amazonec2-region`: The region to use when launching the instance. Default: `us-east-1` + - `--amazonec2-root-size`: The root disk size of the instance (in GB). Default: `16` + - `--amazonec2-secret-key`: **required** Your secret access key for the Amazon Web Services API. + - `--amazonec2-security-group-name`: AWS VPC security group name. Default: `docker-machine` + - `--amazonec2-session-token`: Your session token for the Amazon Web Services API. + - `--amazonec2-subnet-id`: AWS VPC subnet id + - `--amazonec2-vpc-id`: **required** Your VPC ID to launch the instance in. + - `--amazonec2-zone`: The AWS zone launch the instance in (i.e. one of a,b,c,d,e). Default: `a` + +### Google Compute Engine + +Create machines on [Google Compute Engine](https://cloud.google.com/compute/). You will need a Google account and project name. See https://cloud.google.com/compute/docs/projects for details on projects. + +The Google driver uses oAuth. When creating the machine, you will have your browser opened to authorize. Once authorized, paste the code given in the prompt to launch the instance. + +Options: + + - `--google-zone`: The zone to launch the instance. Default: `us-central1-a` + - `--google-machine-type`: The type of instance. Default: `f1-micro` + - `--google-disk-size`: The disk size of the instance (in GB). Default: `10` + - `--google-username`: The username to use for the instance. Default: `docker-user` + - `--google-instance-name`: The name of the instance. Default: `docker-machine` + - `--google-project`: The name of your project to use when launching the instance. + - `--google-scopes`: The scopes associated to the instance. Comma-separated if multiple scopes. Default: `https://www.googleapis.com/auth/devstorage.read_only,https://www.googleapis.com/auth/logging.write`` + +### VMware Fusion + +Creates machines locally on [VMware Fusion](http://www.vmware.com/products/fusion). Requires VMware Fusion to be installed. + +Options: + + - `--vmwarefusion-boot2docker-url`: URL for boot2docker image. + - `--vmwarefusion-disk-size`: Size of disk for host VM (in MB). Default: `20000` + - `--vmwarefusion-memory-size`: Size of memory for host VM (in MB). Default: `1024` + +### VMware vCloud Air + +Creates machines on [vCloud Air](http://vcloud.vmware.com) subscription service. You need an account within an existing subscription of vCloud Air VPC or Dedicated Cloud. + +Options: + + - `--vmwarevcloudair-username`: vCloud Air Username. + - `--vmwarevcloudair-password`: vCloud Air Password. + - `--vmwarevcloudair-catalog`: Catalog. Default: `Public Catalog` + - `--vmwarevcloudair-catalogitem`: Catalog Item. Default: `Ubuntu Server 12.04 LTS (amd64 20140927)` + - `--vmwarevcloudair-computeid`: Compute ID (if using Dedicated Cloud). + - `--vmwarevcloudair-cpu-count`: VM Cpu Count. Default: `1` + - `--vmwarevcloudair-docker-port`: Docker port. Default: `2376` + - `--vmwarevcloudair-edgegateway`: Organization Edge Gateway. Default: `` + - `--vmwarevcloudair-memory-size`: VM Memory Size in MB. Default: `2048` + - `--vmwarevcloudair-name`: vApp Name. Default: `` + - `--vmwarevcloudair-orgvdcnetwork`: Organization VDC Network to attach. Default: `-default-routed` + - `--vmwarevcloudair-provision`: Install Docker binaries. Default: `true` + - `--vmwarevcloudair-publicip`: Org Public IP to use. + - `--vmwarevcloudair-ssh-port`: SSH port. Default: `22` + - `--vmwarevcloudair-vdcid`: Virtual Data Center ID. + +### VMware vSphere + +Creates machines on a [VMware vSphere](http://www.vmware.com/products/vsphere) Virtual Infrastructure. Requires a working vSphere (ESXi and optionally vCenter) installation. The vSphere driver depends on [`govc`](https://github.com/vmware/govmomi/tree/master/govc) (must be in path) and has been tested with [vmware/govmomi@`c848630`](https://github.com/vmware/govmomi/commit/c8486300bfe19427e4f3226e3b3eac067717ef17). + +Options: + + - `--vmwarevsphere-username`: vSphere Username. + - `--vmwarevsphere-password`: vSphere Password. + - `--vmwarevsphere-boot2docker-url`: URL for boot2docker image. + - `--vmwarevsphere-compute-ip`: Compute host IP where the Docker VM will be instantiated. + - `--vmwarevsphere-cpu-count`: CPU number for Docker VM. Default: `2` + - `--vmwarevsphere-datacenter`: Datacenter for Docker VM (must be set to `ha-datacenter` when connecting to a single host). + - `--vmwarevsphere-datastore`: Datastore for Docker VM. + - `--vmwarevsphere-disk-size`: Size of disk for Docker VM (in MB). Default: `20000` + - `--vmwarevsphere-memory-size`: Size of memory for Docker VM (in MB). Default: `2048` + - `--vmwarevsphere-network`: Network where the Docker VM will be attached. + - `--vmwarevsphere-pool`: Resource pool for Docker VM. + - `--vmwarevsphere-vcenter`: IP/hostname for vCenter (or ESXi if connecting directly to a single host). + +### OpenStack + +Create machines on [Openstack](http://www.openstack.org/software/) + +Mandatory: + + - `--openstack-flavor-id`: The flavor ID to use when creating the machine + - `--openstack-image-id`: The image ID to use when creating the machine. + +Options: + + - `--openstack-auth-url`: Keystone service base URL. + - `--openstack-username`: User identifer to authenticate with. + - `--openstack-password`: User password. It can be omitted if the standard environment variable `OS_PASSWORD` is set. + - `--openstack-tenant-name` or `--openstack-tenant-id`: Identify the tenant in which the machine will be created. + - `--openstack-region`: The region to work on. Can be omitted if there is ony one region on the OpenStack. + - `--openstack-endpoint-type`: Endpoint type can be `internalURL`, `adminURL` or `publicURL`. It is a helper for the driver + to choose the right URL in the OpenStack service catalog. If not provided the default is `publicURL`. + - `--openstack-net-id`: The private network id the machine will be connected on. If your OpenStack project + contains only one private network it will be use automatically. + - `--openstack-sec-groups`: If security groups are available on your OpenStack you can specify a comma separated list + to use for the machine (e.g. `secgrp001,secgrp002`). + - `--openstack-floatingip-pool`: The IP pool that will be used to get a public IP and assign it to the machine. If there is an + IP address already allocated but not assigned to any machine, this IP will be chosen and assigned to the machine. If + there is no IP address already allocated a new IP will be allocated and assigned to the machine. + - `--openstack-ssh-user`: The username to use for SSH into the machine. If not provided `root` will be used. + - `--openstack-ssh-port`: Customize the SSH port if the SSH server on the machine does not listen on the default port. + +Environment variables: + +Here comes the list of the supported variables with the corresponding options. If both environment variable +and CLI option are provided the CLI option takes the precedence. + +| Environment variable | CLI option | +|----------------------|-----------------------------| +| `OS_AUTH_URL` | `--openstack-auth-url` | +| `OS_USERNAME` | `--openstack-username` | +| `OS_PASSWORD` | `--openstack-password` | +| `OS_TENANT_NAME` | `--openstack-tenant-name` | +| `OS_TENANT_ID` | `--openstack-tenant-id` | +| `OS_REGION_NAME` | `--openstack-region` | +| `OS_ENDPOINT_TYPE` | `--openstack-endpoint-type` | + +### Rackspace + +Create machines on [Rackspace cloud](http://www.rackspace.com/cloud) + +Options: + + - `--rackspace-username`: Rackspace account username + - `--rackspace-api-key`: Rackspace API key + - `--rackspace-region`: Rackspace region name + - `--rackspace-endpoint-type`: Rackspace endpoint type (adminURL, internalURL or the default publicURL) + - `--rackspace-image-id`: Rackspace image ID. Default: Ubuntu 14.10 (Utopic Unicorn) (PVHVM) + - `--rackspace-flavor-id`: Rackspace flavor ID. Default: General Purpose 1GB + - `--rackspace-ssh-user`: SSH user for the newly booted machine. Set to root by default + - `--rackspace-ssh-port`: SSH port for the newly booted machine. Set to 22 by default + +Environment variables: + +Here comes the list of the supported variables with the corresponding options. If both environment +variable and CLI option are provided the CLI option takes the precedence. + +| Environment variable | CLI option | +|----------------------|-----------------------------| +| `OS_USERNAME` | `--rackspace-username` | +| `OS_API_KEY` | `--rackspace-ap-key` | +| `OS_REGION_NAME` | `--rackspace-region` | +| `OS_ENDPOINT_TYPE` | `--rackspace-endpoint-type` | + +### Softlayer + +Create machines on [Softlayer](http://softlayer.com). + +You need to generate an API key in the softlayer control panel. +[Retrieve your API key](http://knowledgelayer.softlayer.com/procedure/retrieve-your-api-key) + +Options: + - `--softlayer-api-endpoint=`: Change softlayer API endpoint + - `--softlayer-user`: **required** username for your softlayer account, api key needs to match this user. + - `--softlayer-api-key`: **required** API key for your user account + - `--softlayer-cpu`: Number of CPU's for the machine. + - `--softlayer-disk-size: Size of the disk in MB. `0` sets the softlayer default. + - `--softlayer-domain`: **required** domain name for the machine + - `--softlayer-hostname`: hostname for the machine + - `--softlayer-hourly-billing`: Sets the hourly billing flag (default), otherwise uses monthly billing + - `--softlayer-image`: OS Image to use + - `--softlayer-local-disk`: Use local machine disk instead of softlayer SAN. + - `--softlayer-memory`: Memory for host in MB + - `--softlayer-private-net-only`: Disable public networking + - `--softlayer-region`: softlayer region + +### Hyper-V + +Creates a Boot2Docker virtual machine locally on your Windows machine +using Hyper-V. [See here](http://windows.microsoft.com/en-us/windows-8/hyper-v-run-virtual-machines) +for instructions to enable Hyper-V. You will need to use an +Administrator level account to create and manage Hyper-V machines. + +> **Note**: You will need an existing virtual switch to use the +> driver. Hyper-V can share an external network interface (aka +> bridging), see [this blog](http://blogs.technet.com/b/canitpro/archive/2014/03/11/step-by-step-enabling-hyper-v-for-use-on-windows-8-1.aspx). +> If you would like to use NAT, create an internal network, and use +> [Internet Connection +> Sharing](http://www.packet6.com/allowing-windows-8-1-hyper-v-vm-to-work-with-wifi/). + +Options: + + - `--hyper-v-boot2docker-location`: Location of a local boot2docker iso to use. Overrides the URL option below. + - `--hyper-v-boot2docker-url`: The URL of the boot2docker iso. Defaults to the latest available version. + - `--hyper-v-disk-size`: Size of disk for the host in MB. Defaults to `20000`. + - `--hyper-v-memory`: Size of memory for the host in MB. Defaults to `1024`. The machine is setup to use dynamic memory. + - `--hyper-v-virtual-switch`: Name of the virtual switch to use. Defaults to first found. + +## Running on Windows +Machine needs some helper applications to be installed (`ssh`, etc). The easiest way to get started on Windows +is to install [msysGit](https://msysgit.github.io/) and [OpenSSL on Windows](http://slproweb.com/products/Win32OpenSSL.html). +After this, you should have a working setup to use Machine. ## Contributing