docs: Updated AWS Setup & AWS test cluster depl. docs: generate your own SSH key

docs/source/appendices/aws-setup.md

@@ -36,3 +36,37 @@ Default output format [None]: [Press Enter]
 ```
 
 This writes two files: `~/.aws/credentials` and `~/.aws/config`. AWS tools and packages look for those files.
+
+
+## Generate an RSA Key Pair for SSH
+
+Eventually, you'll have one or more instances (virtual machines) running on AWS and you'll want to SSH to them. To do that, you need a public/private key pair. The public key will be sent to AWS, and you can tell AWS to put it in any instances you provision there. You'll keep the private key on your local workstation.
+
+First you need to make up a key name. Some ideas:
+
+* `bcdb-troy-1`
+* `bigchaindb-7`
+* `bcdb-jupiter`
+
+If you already have key pairs on AWS (Amazon EC2), you have to pick a name that's not already being used.
+Below, replace every instance of `<key-name>` with your actual key name.
+To generate a public/private RSA key pair with that name:
+```text
+ssh-keygen -t rsa -C "<key-name>" -f ~/.ssh/<key-name>
+```
+
+It will ask you for a passphrase. You can use whatever passphrase you like, but don't lose it. Two keys (files) will be created in `~/.ssh/`:
+
+1. `~/.ssh/<key-name>.pub` is the public key
+2. `~/.ssh/<key-name>` is the private key
+
+To send the public key to AWS, use the AWS Command-Line Interface:
+```text
+aws ec2 import-key-pair \
+--key-name "<key-name>" \
+--public-key-material file://~/.ssh/<key-name>.pub
+```
+
+If you're curious why there's a `file://` in front of the path to the public key, see issue [aws/aws-cli#41 on GitHub](https://github.com/aws/aws-cli/issues/41).
+
+If you want to verify that your key pair was imported by AWS, go to the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/), select the region you gave above when you did `aws configure` (e.g. eu-central-1), click on **Key Pairs** in the left sidebar, and check that `<key-name>` is listed.

docs/source/clusters-feds/aws-testing-cluster.md

@@ -41,16 +41,6 @@ See the page about [basic AWS Setup](../appendices/aws-setup.html) in the Append
 
 The AWS cluster deployment scripts use elastic IP addresses (although that may change in the future). By default, AWS accounts get five elastic IP addresses. If you want to deploy a cluster with more than five nodes, then you will need more than five elastic IP addresses; you may have to apply for those; see [the AWS documentation on elastic IP addresses](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html).
 
-
-## Create an Amazon EC2 Key Pair
-
-Go to the AWS EC2 Console and select "Key Pairs" in the left sidebar. Click the "Create Key Pair" button. Give it the name `bigchaindb`. You should be prompted to save a file named `bigchaindb.pem`. That file contains the RSA private key. (You can get the public key from the private key, so there's no need to send it separately.)
-
-Save the file in `bigchaindb/deploy-cluster-aws/pem/bigchaindb.pem`.
-
-**You should not share your private key.**
-
-
 ## Create an Amazon EC2 Security Group
 
 Go to the AWS EC2 Console and select "Security Groups" in the left sidebar. Click the "Create Security Group" button. Name it `bigchaindb`. The description probably doesn't matter; you can also put `bigchaindb` for that.
@@ -132,6 +122,7 @@ Step 2 is to make an AWS deployment configuration file, if necessary. There's an
 NUM_NODES=3
 BRANCH="master"
 WHAT_TO_DEPLOY="servers"
+SSH_KEY_NAME="not-set-yet"
 USE_KEYPAIRS_FILE=False
 IMAGE_ID="ami-accff2b1"
 INSTANCE_TYPE="m3.2xlarge"
@@ -140,7 +131,7 @@ EBS_VOLUME_SIZE=30
 EBS_OPTIMIZED=False
 ```
 
-If you're happy with those settings, then you can skip to the next step. Otherwise, you could make a copy of `example_deploy_conf.py` (e.g. `cp example_deploy_conf.py my_deploy_conf.py`) and then edit the copy using a text editor.
+Make a copy of that file and call it whatever you like (e.g. `cp example_deploy_conf.py my_deploy_conf.py`). You can leave most of the settings at their default values, but you must change the value of `SSH_KEY_NAME` to the name of your private SSH key. You can do that with a text editor. Set `SSH_KEY_NAME` to the name you used for `<key-name>` when you generated an RSA key pair for SSH (in basic AWS setup).
 
 If you want your nodes to have a predictable set of pre-generated keypairs, then you should 1) set `USE_KEYPAIRS_FILE=True` in the AWS deployment configuration file, and 2) provide a `keypairs.py` file containing enough keypairs for all of your nodes. You can generate a `keypairs.py` file using the `write_keypairs_file.py` script. For example:
 ```text