From aecc7b7886baff23017a89b77596fd1df1485886 Mon Sep 17 00:00:00 2001 From: Gwendolynne Barr <31074572+gbarr01@users.noreply.github.com> Date: Mon, 11 Sep 2017 17:05:23 -0700 Subject: [PATCH] Add --amazonec2-open-port to example and tidy page (#4554) --- machine/examples/aws.md | 202 ++++++++++++++++++++++++++++------------ 1 file changed, 144 insertions(+), 58 deletions(-) diff --git a/machine/examples/aws.md b/machine/examples/aws.md index 081216b014..7d84ace3d2 100644 --- a/machine/examples/aws.md +++ b/machine/examples/aws.md @@ -25,11 +25,11 @@ Follow along with this example to create a Dockerized [Amazon Web Services (AWS) ### Step 1. Sign up for AWS and configure credentials -1. If you are not already an AWS user, sign up for [AWS](https://aws.amazon.com/) to create an account and get root access to EC2 cloud computers. +1. If you are not already an AWS user, sign up for [AWS](https://aws.amazon.com/) to create an account and get root access to EC2 cloud computers. If you have an Amazon account, you can use it as your root user account. -2. Create an IAM (Identity and Access Management) administrator user, an admin group, and a key pair associated with a region. +2. Create an IAM (Identity and Access Management) administrator user, an admin group, and a key pair associated with a region. From the AWS menus, select **Services** > **IAM** to get started. @@ -43,99 +43,185 @@ Follow along with this example to create a Dockerized [Amazon Web Services (AWS) ### Step 2. Use Machine to create the instance -1. Optionally, create an AWS credential file. +1. Optionally, create an AWS credential file. - 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. + 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. - [default] - aws_access_key_id = AKID1234567890 - aws_secret_access_key = MY-SECRET-KEY + ```conf + [default] + aws_access_key_id = AKID1234567890 + aws_secret_access_key = MY-SECRET-KEY + ``` -2. Run `docker-machine create` with the `amazonec2` driver, your keys, and a name for the new instance. +2. Run `docker-machine create` with the `amazonec2` driver, credentials, inbound + port, region, and a name for the new instance. For example: - **Using a credentials file** + ```bash + docker-machine create --driver amazonec2 --amazonec2-open-port 8000 --amazonec2-region us-west-1 aws-sandbox + ``` - If you specified your keys in a credentials file, this command looks like this to create an instance called `aws-sandbox`: + > **Note**: For all aws create flags, run: `docker-machine create --driver amazonec2 --help` - docker-machine create --driver amazonec2 aws-sandbox + **Use aws credentials file** - **Specifying keys at the command line** + If you set your keys in a credentials file, the command looks like this to + create an instance called `aws-sandbox`: - If you don't have a credentials file, you can use the flags `--amazonec2-access-key` and `--amazonec2-secret-key` on the command line: + ```bash + docker-machine create --driver amazonec2 aws-sandbox + ``` - $ docker-machine create --driver amazonec2 --amazonec2-access-key AKI******* --amazonec2-secret-key 8T93C******* aws-sandbox + **Specify keys at the command line** - **Specifying a region** + If you don't have a credentials file, you can use the flags + `--amazonec2-access-key` and `--amazonec2-secret-key` on the command line: - 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). + ```bash + docker-machine create --driver amazonec2 --amazonec2-access-key AKI******* --amazonec2-secret-key 8T93C******* aws-sandbox + ``` - $ docker-machine create --driver amazonec2 --amazonec2-region us-west-1 aws-01 + **Expose a port** -3. Go to the AWS EC2 Dashboard to view the new instance. + To expose an inbound port to the new machine, use the flag, `--amazonec2-open-port`: + + ```bash + docker-machine create --driver amazonec2 --amazonec2-open-port 8000 aws-sandbox + ``` + + **Specify a region** + + 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, create aws-sandbox in us-west-1 + (Northern California). + + ```bash + docker-machine create --driver amazonec2 --amazonec2-region us-west-1 aws-sandbox + ``` + +3. Go to the AWS EC2 Dashboard to view the new instance. Log into AWS with your IAM credentials, and navigate to your EC2 Running Instances. ![instance on AWS EC2 Dashboard](../img/aws-instance-east.png) - **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. + > **Note**: To ensure that you see your new instance, select your region from + > the menu in the upper right. If you did not specify a region as part of + > `docker-machine create` (with the optional `--amazonec2-region` flag), select + > the default, US East (N. Virginia). -3. At the command terminal, run `docker-machine ls`. +4. Ensure that your new machine is the active host. - $ docker-machine ls - NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS - aws-sandbox * amazonec2 Running tcp://52.90.113.128:2376 v1.10.0 - default - virtualbox Running tcp://192.168.99.100:2376 v1.10.0-rc4 - aws-sandbox - digitalocean Running tcp://104.131.43.236:2376 v1.9.1 + ```bash + $ docker-machine ls + NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS + aws-sandbox * amazonec2 Running tcp://52.90.113.128:2376 v1.10.0 + default - virtualbox Running tcp://192.168.99.100:2376 v1.10.0-rc4 + aws-sandbox - digitalocean Running tcp://104.131.43.236:2376 v1.9.1 + ``` - 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 to 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. + The new `aws-sandbox` instance is running and is the active host as + indicated by the asterisk (\*). When you create a new machine, your command + shell automatically connects to it. You can also check active status by + running `docker-machine active`. -### Step 3. Run Docker commands on the instance + > **Note**: If your new machine is not the active host, connect to it by + running `docker-machine env aws-sandbox` and the returned eval command: + `eval $(docker-machine env aws-sandbox)`. -1. Run some `docker-machine` commands to inspect the remote host. For example, `docker-machine ip ` gets the host IP address and `docker-machine inspect ` lists all the details. +5. Inspect the remote host. For example, `docker-machine ip ` returns +the host IP address and `docker-machine inspect ` lists all the +details. - $ docker-machine ip - 192.168.99.100 + ```bash + $ docker-machine ip aws-sandbox + 192.168.99.100 - $ docker-machine inspect aws-sandbox - { - "ConfigVersion": 3, - "Driver": { - "IPAddress": "52.90.113.128", - "MachineName": "aws-sandbox", - "SSHUser": "ubuntu", - "SSHPort": 22, - ... + $ docker-machine inspect aws-sandbox + { + "ConfigVersion": 3, + "Driver": { + "IPAddress": "52.90.113.128", + "MachineName": "aws-sandbox", + "SSHUser": "ubuntu", + "SSHPort": 22, + ... + } + } + ``` -2. Verify Docker Engine is installed correctly by running `docker` commands. +### Step 3. Run Docker commands on the new instance +You can run docker commands from a local terminal to the active docker machine. - Start with something basic like `docker run hello-world`, or for a more interesting test, run a Dockerized webserver on your new remote machine. +1. Run docker on the active docker machine by downloading and running the +hello-world image: - **Note**: We are using port `8000` in this example and that port has been added to the AWS Security Group associated with docker-machine. If you want to run your container on another port, you will need to update the security group to reflect that. + ```bash + docker run hello-world + ``` - 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 `aws-sandbox` host. +2. Ensure that you ran hello-world on aws-sandbox (and not localhost or some +other machine): - $ docker run -d -p 8000:80 --name webserver kitematic/hello-world-nginx - Unable to find image 'kitematic/hello-world-nginx:latest' locally - latest: Pulling from kitematic/hello-world-nginx - a285d7f063ea: Pull complete - 2d7baf27389b: Pull complete - ... - Digest: sha256:ec0ca6dcb034916784c988b4f2432716e2e92b995ac606e080c7a54b52b87066 - Status: Downloaded newer image for kitematic/hello-world-nginx:latest - 942dfb4a0eaae75bf26c9785ade4ff47ceb2ec2a152be82b9d7960e8b5777e65 + Log on to aws-sandbox with ssh and list all containers. You should see + hello-world (with a recent exited status): - In a web browser, go to `http://:8000` to bring up the webserver home page. You got the `` from the output of the `docker-machine ip ` command you ran in a previous step. Use the port you exposed in the `docker run` command. + ```bash + docker-machine ssh aws-sandbox + sudo docker container ls -a + exit + ``` + + Log off aws-sandbox and unset this machine as active. Then list images + again. You should not see hello-world (at least not with the same exited + status): + + ```bash + eval $(docker-machine env -u) + docker container ls -a + ``` + +3. Reset aws-sandbox as the active docker machine: + + ```bash + eval $(docker-machine env aws-sandbox) + ``` + + For a more interesting test, run a Dockerized webserver on your new machine. + + > **Note**: In this example, we use port `8000` which we added to the + > docker-machine AWS Security Group during `docker-machine create`. To run your + > container on another port, update the security group to reflect that. + + 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 `aws-sandbox` host. + + ```bash + $ docker run -d -p 8000:80 --name webserver kitematic/hello-world-nginx + Unable to find image 'kitematic/hello-world-nginx:latest' locally + latest: Pulling from kitematic/hello-world-nginx + a285d7f063ea: Pull complete + 2d7baf27389b: Pull complete + ... + Digest: sha256:ec0ca6dcb034916784c988b4f2432716e2e92b995ac606e080c7a54b52b87066 + Status: Downloaded newer image for kitematic/hello-world-nginx:latest + 942dfb4a0eaae75bf26c9785ade4ff47ceb2ec2a152be82b9d7960e8b5777e65 + ``` + + In a web browser, go to `http://:8000` to bring up the webserver + home page. You got the `` from the output of the `docker-machine ip + ` command you ran in a previous step. Use the port you exposed in + the `docker run` command. ![nginx webserver](../img/nginx-webserver.png) ### Step 4. Use Machine to remove the instance -To remove an instance and all of its containers and images, first stop the machine, then use `docker-machine rm`: + To remove an instance and all of its containers and images, first stop the + machine, then use `docker-machine rm`: - $ docker-machine stop aws-sandbox - $ docker-machine rm aws-sandbox - Do you really want to remove "aws-sandbox"? (y/n): y - Successfully removed aws-sandbox ## Where to go next - [Understand Machine concepts](../concepts.md)