X Tutup
Skip to content

Commit 0eb405f

Browse files
author
Victoria Bialas
committed
AWS example added to Machine docs cloud provisioning topic, reorganized/streamlined topics, tested against updated driver, and documented per new/easier use of it per Jean-Laurent's fixes
split examples out into separate files (aws, digital ocean) fixes issue docker-archive-public#3028:links to Swarm in overview, cloud topics, cloud examples fixed links and mis-spelling Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>
1 parent 1c07446 commit 0eb405f

File tree

11 files changed

+333
-174
lines changed

11 files changed

+333
-174
lines changed

‎docs/concepts.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description = "Understand concepts for Docker Machine, including drivers, base O
55
keywords = ["docker, machine, amazonec2, azure, digitalocean, google, openstack, rackspace, softlayer, virtualbox, vmwarefusion, vmwarevcloudair, vmwarevsphere, exoscale"]
66
[menu.main]
77
parent="workw_machine"
8-
weight=3
8+
weight=-40
99
+++
1010
<![end-metadata]-->
1111

‎docs/examples/aws.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
<!--[metadata]>
2+
+++
3+
title = "Provision AWS EC2 Instances"
4+
description = "Using Docker Machine to provision hosts on AWS"
5+
keywords = ["docker, machine, cloud, aws"]
6+
[menu.main]
7+
parent="cloud_examples"
8+
weight=2
9+
+++
10+
<![end-metadata]-->
11+
12+
# Amazon Web Services (AWS) EC2 example
13+
14+
Follow along with this example to create a Dockerized <a href="https://aws.amazon.com/" target="_blank"> Amazon Web Services (AWS)</a> EC2 instance (AMI).
15+
16+
### Step 1. Sign up for AWS and configure credentials
17+
18+
1. If you are not already an AWS user, sign up for <a href="https://aws.amazon.com/" target="_blank"> AWS</a> to create an account and get root access to EC2 cloud computers.
19+
20+
If you have an Amazon account, you can use it as your root user account.
21+
22+
2. Create an IAM (Identity and Access Management) administrator user, an admin group, and a key pair associated with a region.
23+
24+
From the AWS menus, select **Services** > **IAM** to get started.
25+
26+
To create machines on AWS, you must supply two parameters:
27+
28+
* an AWS Access Key ID
29+
30+
* an AWS Secret Access Key
31+
32+
See the AWS documentation on <a href="http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/get-set-up-for-amazon-ec2.html" target="_blank">Setting Up with Amazon EC2</a>. Follow the steps for "Create an IAM User" and "Create a Key Pair".
33+
34+
### Step 2. Use Machine to create the instance
35+
36+
1. Optionally, create an AWS credential file.
37+
38+
You can create an `~/.aws/credentials` file to hold your AWS keys so that you don't have to type them every time you run the `docker-machine create` command. Here is an example of a credentials file.
39+
40+
[default]
41+
aws_access_key_id = AKID1234567890
42+
aws_secret_access_key = MY-SECRET-KEY
43+
44+
2. Run `docker-machine create` with the `amazonec2` driver, your keys, and a name for the new instance.
45+
46+
**Using a credentials file**
47+
48+
If you specified your keys in a credentials file, this command looks like this to create an instance called `aws-sandbox`:
49+
50+
docker-machine create --driver amazonec2 aws-sandbox
51+
52+
**Specifying keys at the command line**
53+
54+
If you don't have a credentials file, you can use the flags `--amazonec2-access-key` and `--amazonec2-secret-key` on the command line:
55+
56+
$ docker-machine create --driver amazonec2 --amazonec2-access-key AKI******* --amazonec2-secret-key 8T93C******* aws-sandbox
57+
58+
**Specifying a region**
59+
60+
By default, the driver creates new instances in region us-east-1 (North Virginia). You can specify a different region by using the `--amazonec2-region` flag. For example, this command creates a machine called "aws-01" in us-west-1 (Northern California).
61+
62+
$ docker-machine create --driver amazonec2 --amazonec2-region us-west-1 aws-01
63+
64+
3. Go to the AWS EC2 Dashboard to view the new instance.
65+
66+
Log into AWS with your IAM credentials, and navigate to your EC2 Running Instances.
67+
68+
![instance on AWS EC2 Dashboard](../img/aws-instance-east.png)
69+
70+
**Note**: Make sure you set the region appropriately from the menu in the upper right; otherwise, you won't see the new instance. If you did not specify a region as part of `docker-machine create` (with the optional `--amazonec2-region` flag), then the region will be US East, which is the default.
71+
72+
3. At the command terminal, run `docker-machine ls`.
73+
74+
$ docker-machine ls
75+
NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS
76+
aws-sandbox * amazonec2 Running tcp://52.90.113.128:2376 v1.10.0
77+
default - virtualbox Running tcp://192.168.99.100:2376 v1.10.0-rc4
78+
docker-sandbox - digitalocean Running tcp://104.131.43.236:2376 v1.9.1
79+
80+
The new `aws-sandbox` instance is running, and it is the active host as indicated by the asterisk (*). When you create a new machine, your command shell automatically connects it. If for some reason your new machine is not the active host, you'll need to run `docker-machine env aws-sandbox`, followed by `eval $(docker-machine env aws-sandbox)` to connect to it.
81+
82+
### Step 3. Run Docker commands on the instance
83+
84+
1. Run some `docker-machine` commands to inspect the remote host. For example, `docker-machine ip <machine>` gets the host IP address and `docker-machine inspect <machine>` lists all the details.
85+
86+
$ docker-machine ip
87+
192.168.99.100
88+
89+
$ docker-machine inspect aws-sandbox
90+
{
91+
"ConfigVersion": 3,
92+
"Driver": {
93+
"IPAddress": "52.90.113.128",
94+
"MachineName": "aws-sandbox",
95+
"SSHUser": "ubuntu",
96+
"SSHPort": 22,
97+
...
98+
99+
2. Verify Docker Engine is installed correctly by running `docker` commands.
100+
101+
Start with something basic like `docker run hello-world`, or for a more interesting test, run a Dockerized webserver on your new remote machine.
102+
103+
In this example, the `-p` option is used to expose port 80 from the `nginx` container and make it accessible on port `8000` of the `docker-sandbox` host.
104+
105+
$ docker run -d -p 8000:80 --name webserver kitematic/hello-world-nginx
106+
Unable to find image 'kitematic/hello-world-nginx:latest' locally
107+
latest: Pulling from kitematic/hello-world-nginx
108+
a285d7f063ea: Pull complete
109+
2d7baf27389b: Pull complete
110+
...
111+
Digest: sha256:ec0ca6dcb034916784c988b4f2432716e2e92b995ac606e080c7a54b52b87066
112+
Status: Downloaded newer image for kitematic/hello-world-nginx:latest
113+
942dfb4a0eaae75bf26c9785ade4ff47ceb2ec2a152be82b9d7960e8b5777e65
114+
115+
In a web browser, go to `http://<host_ip>:8000` to bring up the webserver home page. You got the `<host_ip>` from the output of the `docker-machine ip <machine>` command you ran in a previous step. Use the port you exposed in the `docker run` command.
116+
117+
![nginx webserver](../img/nginx-webserver.png)
118+
119+
### Step 4. Use Machine to remove the instance
120+
121+
To remove a AMI instance and all of its containers and images, first stop the machine, then use `docker-machine rm`:
122+
123+
$ docker-machine stop aws-sandbox
124+
$ docker-machine rm aws-sandbox
125+
Do you really want to remove "docker-sandbox"? (y/n): y
126+
Successfully removed aws-sandbox
127+
## Where to go next
128+
129+
- [Understand Machine concepts](../concepts.md)
130+
- [Docker Machine driver reference](../drivers/index.md)
131+
- [Docker Machine subcommand reference](../reference/index.md)
132+
- [Provision a Docker Swarm cluster with Docker Machine](https://docs.docker.com/swarm/provision-with-machine/)

‎docs/examples/index.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<!--[metadata]>
2+
+++
3+
title = "Learn by example"
4+
description = "Examples of cloud installs"
5+
keywords = ["docker, machine, amazonec2, azure, digitalocean, google, openstack, rackspace, softlayer, virtualbox, vmwarefusion, vmwarevcloudair, vmwarevsphere, exoscale"]
6+
[menu.main]
7+
parent="workw_machine"
8+
identifier="cloud_examples"
9+
weight="-50"
10+
+++
11+
<![end-metadata]-->
12+
13+
14+
# Learn by example
15+
16+
- [Digital Ocean Example](ocean.md)
17+
- [AWS Example](aws.md)

‎docs/examples/ocean.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
<!--[metadata]>
2+
+++
3+
title = "Provision Digital Ocean Droplets"
4+
description = "Using Docker Machine to provision hosts on Digital Ocean"
5+
keywords = ["docker, machine, cloud, digital ocean"]
6+
[menu.main]
7+
parent="cloud_examples"
8+
weight=1
9+
+++
10+
<![end-metadata]-->
11+
12+
# Digital Ocean example
13+
14+
Follow along with this example to create a Dockerized <a href="https://digitalocean.com" target="_blank">Digital Ocean</a> Droplet (cloud host).
15+
16+
### Step 1. Create a Digital Ocean account
17+
18+
If you have not done so already, go to <a href="https://digitalocean.com" target="_blank">Digital Ocean</a>, create an account, and log in.
19+
20+
### Step 2. Generate a personal access token
21+
22+
To generate your access token:
23+
24+
1. Go to the Digital Ocean administrator console and click **API** in the header.
25+
26+
![Click API in Digital Ocean console](../img/ocean_click_api.png)
27+
28+
2. Click **Generate New Token** to get to the token generator.
29+
30+
![Generate token](../img/ocean_gen_token.png)
31+
32+
3. Give the token a clever name (e.g. "machine"), make sure the **Write (Optional)** checkbox is checked, and click **Generate Token**.
33+
34+
![Name and generate token](../img/ocean_token_create.png)
35+
36+
4. Grab (copy to clipboard) the generated big long hex string and store it somewhere safe.
37+
38+
![Copy and save personal access token](../img/ocean_save_token.png)
39+
40+
This is the personal access token you'll use in the next step to create your cloud server.
41+
42+
### Step 3. Use Machine to create the Droplet
43+
44+
1. Run `docker-machine create` with the `digitalocean` driver and pass your key to the `--digitalocean-access-token` flag, along with a name for the new cloud server.
45+
46+
For this example, we'll call our new Droplet "docker-sandbox".
47+
48+
$ docker-machine create --driver digitalocean --digitalocean-access-token xxxxx docker-sandbox
49+
Running pre-create checks...
50+
Creating machine...
51+
(docker-sandbox) OUT | Creating SSH key...
52+
(docker-sandbox) OUT | Creating Digital Ocean droplet...
53+
(docker-sandbox) OUT | Waiting for IP address to be assigned to the Droplet...
54+
Waiting for machine to be running, this may take a few minutes...
55+
Machine is running, waiting for SSH to be available...
56+
Detecting operating system of created instance...
57+
Detecting the provisioner...
58+
Provisioning created instance...
59+
Copying certs to the local machine directory...
60+
Copying certs to the remote machine...
61+
Setting Docker configuration on the remote daemon...
62+
To see how to connect Docker to this machine, run: docker-machine env docker-sandbox
63+
64+
When the Droplet is created, Docker generates a unique SSH key and stores it on your local system in `~/.docker/machines`. Initially, this is used to provision the host. Later, it's used under the hood to access the Droplet directly with the `docker-machine ssh` command. Docker Engine is installed on the cloud server and the daemon is configured to accept remote connections over TCP using TLS for authentication.
65+
66+
2. Go to the Digital Ocean console to view the new Droplet.
67+
68+
![Droplet in Digital Ocean created with Machine](../img/ocean_droplet.png)
69+
70+
3. At the command terminal, run `docker-machine ls`.
71+
72+
$ docker-machine ls
73+
NAME ACTIVE DRIVER STATE URL SWARM
74+
default - virtualbox Running tcp://192.168.99.100:2376
75+
docker-sandbox * digitalocean Running tcp://45.55.139.48:2376
76+
77+
The new `docker-sandbox` machine is running, and it is the active host as indicated by the asterisk (*). When you create a new machine, your command shell automatically connects it. If for some reason your new machine is not the active host, you'll need to run `docker-machine env aws-sandbox`, followed by `eval $(docker-machine env docker-sandbox)` to connect to it.
78+
79+
### Step 4. Run Docker commands on the Droplet
80+
81+
1. Run some `docker-machine` commands to inspect the remote host. For example, `docker-machine ip <machine>` gets the host IP adddress and `docker-machine inspect <machine>` lists all the details.
82+
83+
$ docker-machine ip docker-sandbox
84+
104.131.43.236
85+
86+
$ docker-machine inspect docker-sandbox
87+
{
88+
"ConfigVersion": 3,
89+
"Driver": {
90+
"IPAddress": "104.131.43.236",
91+
"MachineName": "docker-sandbox",
92+
"SSHUser": "root",
93+
"SSHPort": 22,
94+
"SSHKeyPath": "/Users/samanthastevens/.docker/machine/machines/docker-sandbox/id_rsa",
95+
"StorePath": "/Users/samanthastevens/.docker/machine",
96+
"SwarmMaster": false,
97+
"SwarmHost": "tcp://0.0.0.0:3376",
98+
"SwarmDiscovery": "",
99+
...
100+
101+
2. Verify Docker Engine is installed correctly by running `docker` commands.
102+
103+
Start with something basic like `docker run hello-world`, or for a more interesting test, run a Dockerized webserver on your new remote machine.
104+
105+
In this example, the `-p` option is used to expose port 80 from the `nginx` container and make it accessible on port `8000` of the `docker-sandbox` host.
106+
107+
$ docker run -d -p 8000:80 --name webserver kitematic/hello-world-nginx
108+
Unable to find image 'kitematic/hello-world-nginx:latest' locally
109+
latest: Pulling from kitematic/hello-world-nginx
110+
a285d7f063ea: Pull complete
111+
2d7baf27389b: Pull complete
112+
...
113+
Digest: sha256:ec0ca6dcb034916784c988b4f2432716e2e92b995ac606e080c7a54b52b87066
114+
Status: Downloaded newer image for kitematic/hello-world-nginx:latest
115+
942dfb4a0eaae75bf26c9785ade4ff47ceb2ec2a152be82b9d7960e8b5777e65
116+
117+
In a web browser, go to `http://<host_ip>:8000` to bring up the webserver home page. You got the `<host_ip>` from the output of the `docker-machine ip <machine>` command you ran in a previous step. Use the port you exposed in the `docker run` command.
118+
119+
![nginx webserver](../img/nginx-webserver.png)
120+
121+
### Step 5. Use Machine to remove the Droplet
122+
123+
To remove a host and all of its containers and images, first stop the machine, then use `docker-machine rm`:
124+
125+
$ docker-machine stop docker-sandbox
126+
$ docker-machine rm docker-sandbox
127+
Do you really want to remove "docker-sandbox"? (y/n): y
128+
Successfully removed docker-sandbox
129+
130+
$ docker-machine ls
131+
NAME ACTIVE DRIVER STATE URL SWARM
132+
default * virtualbox Running tcp:////xxx.xxx.xx.xxx:xxxx
133+
134+
If you monitor the Digital Ocean console while you run these commands, you will see it update first to reflect that the Droplet was stopped, and then removed.
135+
136+
If you create a host with Docker Machine, but remove it through the cloud provider console, Machine will lose track of the server status. So please use the `docker-machine rm` command for hosts you create with `docker-machine --create`.
137+
138+
## Where to go next
139+
140+
- [Understand Machine concepts](../concepts.md)
141+
- [Docker Machine driver reference](../drivers/index.md)
142+
- [Docker Machine subcommand reference](../reference/index.md)
143+
- [Provision a Docker Swarm cluster with Docker Machine](https://docs.docker.com/swarm/provision-with-machine/)

0 commit comments

Comments
 (0)
X Tutup