chore(ssh): add page for managing ssh keys

Author: slack

mkdocs.yml

@@ -32,6 +32,7 @@ pages:
   - Using Workflow:
     - Command Line Interface: using-workflow/cli.md
     - Users and Registration: using-workflow/users-and-registration.md
+    - User SSH Keys: using-workflow/user-ssh-keys.md
   - Applications:
     - Deploying Apps: applications/deploying-apps.md
     - Buildpacks: applications/using-buildpacks.md

src/applications/deploying-apps.md

@@ -10,7 +10,6 @@ For example, if your application persists state to the local filesystem -- commo
 
 Fortunately, most modern applications feature a stateless application tier that can scale horizontally inside Deis.
 
-
 ## Login to the Controller
 
 !!! important
@@ -26,21 +25,6 @@ password:
 Logged in as deis
 ```
 
-## Upload Your SSH Public Key
-
-If you plan on using `git push` to deploy applications to Deis, you must provide your SSH public key.  Use the `deis keys:add` command to upload your default SSH public key, usually one of:
-
-* ~/.ssh/id_rsa.pub
-* ~/.ssh/id_dsa.pub
-
-```
-$ deis keys:add
-Found the following SSH public keys:
-1) id_rsa.pub
-Which would you like to use with Deis? 1
-Uploading /Users/myuser/.ssh/id_rsa.pub to Deis... done
-```
-
 ## Select a Build Process
 
 Deis supports three different ways of building applications:

src/using-workflow/user-ssh-keys.md

@@ -0,0 +1,57 @@
+# Users and SSH Keys
+
+For **Dockerfile** and **Buildpack** based application deploys via `git push`, Deis Workflow identifies users via SSH
+keys. SSH keys are pushed to the platform and must be unique to each user. Users may have multiple SSH keys as needed.
+
+## Generate an SSH Key
+
+If you do not already have an SSH key or would like to create a new key for Deis Workflow, generate a new key using
+`ssh-keygen`:
+
+```
+$ ssh-keygen -f ~/.ssh/id_deis -t rsa
+Generating public/private rsa key pair.
+Enter passphrase (empty for no passphrase):
+Enter same passphrase again:
+Your identification has been saved in /Users/admin/.ssh/id_deis.
+Your public key has been saved in /Users/admin/.ssh/id_deis.pub.
+The key fingerprint is:
+3d:ac:1f:f4:83:f7:64:51:c1:7e:7f:80:b6:70:36:c9 admin@plinth-23437.local
+The key's randomart image is:
++--[ RSA 2048]----+
+|              .. |
+|               ..|
+|           . o. .|
+|         o. E .o.|
+|        S == o..o|
+|         o +.  .o|
+|        . o + o .|
+|         . o =   |
+|          .   .  |
++-----------------+
+```
+
+## Adding and Removing SSH Keys
+
+By publishing the **public** half of your SSH key to Deis Workflow the component responsible for receiving `git push`
+will be able to authenticate the user and ensure that they have access to the destination application.
+
+```
+$ deis keys:add ~/.ssh/id_deis.pub
+Uploading id_deis.pub to deis... done
+```
+
+You can always view the keys associated with your user as well:
+
+```
+$ deis keys:list
+=== admin Keys
+admin@plinth-23437.local ssh-rsa AAAAB3Nz...3437.local
+admin@subgenius.local ssh-rsa AAAAB3Nz...nius.local
+```
+
+Remove keys by their name:
+```
+$ deis keys:remove admin@plinth-23437.local
+Removing admin@plinth-23437.local SSH Key... don
+```