Docs on using special SSH keypair with ACS/Kubernetes

docs/server/source/appendices/aws-setup.md

@@ -42,23 +42,10 @@ This writes two files: `~/.aws/credentials` and `~/.aws/config`. AWS tools and p
 
 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:
+See the [page about how to generate a key pair for SSH](generate-key-pair-for-ssh.html).
 
-* `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
+## Send the Public Key to AWS
 
 To send the public key to AWS, use the AWS Command-Line Interface:
 ```text

docs/server/source/appendices/generate-key-pair-for-ssh.md

@@ -0,0 +1,34 @@
+# Generate a Key Pair for SSH
+
+This page describes how to use `ssh-keygen`
+to generate a public/private RSA key pair
+that can be used with SSH.
+(Note: `ssh-keygen` is found on most Linux and Unix-like
+operating systems; if you're using Windows,
+then you'll have to use another tool,
+such as PuTTYgen.)
+
+By convention, SSH key pairs get stored in the `~/.ssh/` directory.
+Check what keys you already have there:
+```text
+ls -1 ~/.ssh/
+```
+
+Next, make up a new key pair name (called `<name>` below).
+Here are some ideas:
+
+* `aws-bdb-2`
+* `tim-bdb-azure`
+* `chris-bcdb-key`
+
+Next, generate a public/private RSA key pair with that name:
+```text
+ssh-keygen -t rsa -C "<name>" -f ~/.ssh/<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/<name>.pub` is the public key
+2. `~/.ssh/<name>` is the private key

docs/server/source/appendices/index.rst

@@ -17,6 +17,7 @@ Appendices
    pipelines
    backend
    aws-setup
+   generate-key-pair-for-ssh
    firewall-notes
    ntp-notes
    example-rethinkdb-storage-setups

docs/server/source/cloud-deployment-templates/template-kubernetes-azure.rst

@@ -18,7 +18,20 @@ You may find that you have to sign up for a Free Trial subscription first.
 That's okay: you can have many subscriptions.
 
 
-Step 2: Deploy an Azure Container Service (ACS)
+Step 2: Create an SSH Key Pair
+------------------------------
+
+You'll want an SSH key pair so you'll be able to SSH
+to the virtual machines that you'll deploy in the next step.
+(If you already have an SSH key pair, you *could* reuse it,
+but it's probably a good idea to make a new SSH key pair
+for your Kubernetes VMs and nothing else.)
+
+See the
+:ref:`page about how to generate a key pair for SSH <Generate a Key Pair for SSH>`.
+
+
+Step 3: Deploy an Azure Container Service (ACS)
 -----------------------------------------------
 
 It's *possible* to deploy an Azure Container Service (ACS)
@@ -82,8 +95,7 @@ Finally, you can deploy an ACS using something like:
    --agent-count 3 \
    --agent-vm-size Standard_D2_v2 \
    --dns-prefix <make up a name> \
-   --generate-ssh-keys \
-   --location <same location as the resource group> \
+   --ssh-key-value ~/.ssh/<name>.pub \
    --orchestrator-type kubernetes
 
 There are more options. For help understanding all the options, use the built-in help:
@@ -100,4 +112,32 @@ and click on the one you created
 to see all the resources in it.
 
 Next, you can :doc:`run a BigchainDB node on your new
-Kubernetes cluster <node-on-kubernetes>`.
+Kubernetes cluster <node-on-kubernetes>`.
+
+
+Optional: SSH to Your New Kubernetes Cluster Nodes
+--------------------------------------------------
+
+You can SSH to one of the just-deployed Kubernetes "master" nodes
+(virtual machines) using:
+
+.. code:: bash
+
+   $ ssh -i ~/.ssh/<name>.pub azureuser@<master-ip-address-or-hostname>
+
+where you can get the IP address or hostname
+of a master node from the Azure Portal.
+Note how the default username is ``azureuser``.
+
+The "agent" nodes don't get public IP addresses or hostnames,
+so you can't SSH to them *directly*,
+but you can first SSH to the master
+and then SSH to an agent from there 
+(using the *private* IP address of the agent node).
+To do that, you either need to copy your SSH key pair to
+the master (a bad idea),
+or use something like
+`SSH agent forwarding <https://yakking.branchable.com/posts/ssh-A/>`_ (better).
+
+Next, you can :doc:`run a BigchainDB node on your new
+Kubernetes cluster <node-on-kubernetes>`.