From 4e89c72b86d7ad4c19d05b0956262010b819c29a Mon Sep 17 00:00:00 2001
From: Cel Skeggs <cela@mit.edu>
Date: Sun, 23 Jul 2017 16:41:16 -0400
Subject: [PATCH] Update and clarify deploy.md

---
 deployment/deploy.md | 83 ++++++++++++++++++++++++++++++++++----------
 1 file changed, 65 insertions(+), 18 deletions(-)

diff --git a/deployment/deploy.md b/deployment/deploy.md
index ebfb30958..803360241 100644
--- a/deployment/deploy.md
+++ b/deployment/deploy.md
@@ -1,17 +1,51 @@
 # How to deploy a Homeworld cluster
 
-## Building Software
+## Generating admission keys
 
- * Install sbuild and dependencies from debian repositories.
- * In packages, run `./build-all.sh`.
- * Rebuild and/or update the repository by going into `repository` and running
-   `./rebuild.sh`.
+To generate infrastructural access keys:
+
+    $ cd deployment/admit
+    $ ./generate-secrets ??/secrets/ <AUTHSERVER>.mit.edu
+
+You'll now have the certificate authorities for the admission process and the
+certificate authorities for ongoing cluster access.
+
+## Building the ISO
+
+You will need to install, at the very least:
+
+ * build-essential
+ * sbuild
+ * cpio
+ * genisoimage
+
+And probably some other miscellaneous things too.
+
+To build a new ISO, although you don't need everything built, you do need two
+packages built:
+
+ * homeworld-apt-setup
+ * homeworld-admitclient
+
+To do so, you need to build the go compiler first. So:
+
+    $ cd building/build-helpers/helper-go
+    $ ./build.sh
+
+    $ cd building/build-debs/homeworld-apt-setup
+    $ ./build-package.sh
+
+    $ cd building/build-debs/homeworld-admitclient
+    $ ./build-package.sh
+
+    $ cd building/build-iso
+    $ ./generate.sh <AUTHSERVER>.mit.edu ??/secrets/admission.pem
+
+Now you should burn and/or upload the .iso that you've just gotten, so that you
+can use it for installing servers. Make a note of the password it generated.
 
 ## Provisioning a server
 
- * Generate a preseeded ISO by going into `installation` and running
-   `generate.sh`. You will need a few packages, such as cpio and genisoimage.
-   - Keep track of the password that it outputted.
  * Boot the ISO on the target system.
    - Select `Install`
    - Enter the last two octets of the IP address for the server.
@@ -24,8 +58,7 @@
  * Provision a server as above; set up direct SSH key access for now.
  * Until you've verified that kerberos auth works (below), keep a SSH session
    open continously, just in case.
- * Generate ssh user CA locally; save it in the secrets directory.
- * Rotate the keys (and upgrade their cryptographic strength):
+ * Rotate the keytab (and upgrade its cryptographic strength):
 
        $ k5srvutil -f <keytab> change -e aes256-cts:normal,aes128-cts:normal
          # the following will invalidate current tickets:
@@ -39,12 +72,25 @@
  * Confirm that you can log into the server with kerberos auth.
  * Remove your direct SSH key access.
 
-## Initial server setup
+## Set up the admission server
+
+This probably goes on the same box as the authentication server.
+
+    $ cd deployment-config
+    $ nano setup.conf
+    $ ./compile-config.py
+
+    $ cd admit
+    $ ./deploy.sh AUTHSERVER.mit.edu ???/secrets ../deployment-config/cluster-config/
+
+The deployment should finish successfully.
+
+## Initial node setup
 
  * Provision a server as above.
- * Generate a ssh host CA locally; save it in the secrets directory.
- * Launch an admission server from a trusted machine. Copy up the relevant files.
- * Admit the server according to the instructions. Verify all hashes carefully.
+ * Locally, run `$ admit/prepare-admit.sh ???/secrets AUTHSERVER.mit.edu new-node-hostname`
+     (The hostname should not contain the .mit.edu.)
+ * Run `# pull-admit <TOKEN>` on the new server, with the token produced by prepare-admit.sh.
  * Make sure to add the CA key for the server into your known_hosts.
 
        @cert-authority eggs-benedict.mit.edu,huevos-rancheros.mit.edu,[...] ssh-rsa ...
@@ -53,11 +99,8 @@
 
 ## Configuration and SSL setup and package installation
 
- * Modify deployment-config/setup.conf
- * Run ./compile-config.py
- * Run ./compile-certificates cluster-config/certificates.list <secrets-directory>
+ * Run deployment-config/compile-certificates cluster-config/certificates.list <secrets-directory>
  * Run pkg-install-all.sh
- * Run deploy-config-all.sh
  * If this is the first time installing this cluster, run authority-gen.sh
  * Run certify.sh
 
@@ -69,6 +112,10 @@
 
 ## Core cluster services
 
+ * Go into clustered/
+ * Generate flannel config: generate.sh ../deployment-config/cluster-config/cluster.conf
+ * Deploy: kubectl create -f flannel.yml
+ * Verify flannel functionality by using two homeworld.mit.edu/debian containers.
  * Set up DNS: kubectl create -f dns-addon.yml
  * Verify DNS: nslookup kubernetes.default.svc.hyades.local 172.28.0.2
      "Address: 172.28.0.1"