Fix up the integration tests for volumes

This adds an env flag to toggle behavior on copying vs pulling
standard images, as well as fixing paths for volume based deployments.

install_upgrade_spec.md

@@ -15,7 +15,7 @@ logic that resides largely within this bootstrapper.
 ## Assumptions
 
 * Orca will not be HA in v1
-* We wont use data volume containers, but instead host volume mounts
+* We will use named volumes for persistence
 * Our goal is to get as close to a full end-to-end deployment as possible (from bare-metal up to orca)
     * Advanced customers may be able to cherry-pick, but that's not the focus in v1
     * We'll deploy an internal consul instance for swarm (not HA)
@@ -25,7 +25,7 @@ logic that resides largely within this bootstrapper.
 * Swarm manager and docker proxy may fold into one component, but this shouldn't fundamentally change the flow
 * We'll "own" two internal root CAs for orca/swarm to provide access control
     * Set up so that certs can be replaced post v1
-    * We'll store the certs in a host volume mount
+    * We'll store the certs in a named volume
     * The volume could be swapped out for a keywhiz volume mount in the future (unclear if we can write to it though...)
     * Laying the groundwork of a central CA for our managed swarm will enable keywhiz for secret management post v1
 * Installation logic should be idempotent, and not clobber any pertinent state unless the user asks us to
@@ -117,7 +117,7 @@ docker run --rm -t \
     * If this fails, inform user to "docker login" using their hub credentials and try again
 7. Stop any existing orca containers already running on the host
 8. (conditional) clobber existing state if requested
-9. Generate Root CA and certs if not present in host volume path: /etc/docker/ssl/orca
+9. Generate Root CA and certs if not present in named volume:
     * Orca CA cert
     * Swarm CA cert
 10. Generate cert for proxy/swarm manager signed by Swarm CA
@@ -137,7 +137,7 @@ docker run --rm -t \
     * Bind to port 2376 so this becomes the "default" way to talk to this node
 15. Verify we can see the swarm manager we just deployed
     * if not warn user firewall settings may need to be opened for port XXX (moot in baremetal case)
-16. Deploy DB with host volume mount for data directory
+16. Deploy DB with named volume data directory
 17. Deploy Orca server
     * Linked to DB, pointed at consul external port
     * Bind 80/443, use random ports if unavailable

quickstart.md

@@ -36,6 +36,22 @@ Important notes for first time users:
     * Take a look at the env.sh within the zip file for instructions (should be familiar if you've used machine)
 
 
+## Data Persistence
+
+Orca uses named volumes for persistence of user data.  By default,
+the bootstrapper will create these using the default volume driver and
+flags if they are not detected.  If you use a custom volume driver, you
+can pre-create volumes prior to installing Orca.
+
+* **orca-root-ca** - The certificate and key for the Orca Root CA
+* **orca-swarm-root-ca** - The certificate and key for the Swarm Root CA
+* **orca-server-certs** - The server certificates for the Orca web server
+* **orca-swarm-node-certs** - The swarm certificates for the current node (repeated on every node in the cluster)
+* **orca-config** - Orca server configuration settings (ID, locations of key services)
+* **orca-db** - Orca server data (local accounts, etc.)
+* **orca-kv** - KV store persistence
+
+
 ## User Supplied Certificates
 
 Orca uses two separate root CAs for access control - one for Swarm,
@@ -60,15 +76,20 @@ internal Swarm Root CA.  Normal user accounts should be signed by the
 same external Root CA (or a trusted intermediary), and the public keys
 manually added through the UI.
 
-To install Orca with an external Root CA, place the following files on the
-engine host where you will install Orca **before** running the install:
+To install Orca with an external Root CA, create a named volume called **orca-server-certs**
+on the engine host where you will install Orca **before** running the install, and ensure the following
+files are present in the top-level directory of this volume:
 
-* /var/lib/docker/orca\_ssl/orca\_ca.pem - Your Root CA Certificate chain (including any intermediaries)
-* /var/lib/docker/orca\_ssl/orca\_controller.pem - Your signed Orca server cert
-* /var/lib/docker/orca\_ssl/orca\_controller\_key.pem - Your Orca server private key
+* **ca.pem** - Your Root CA Certificate chain (including any intermediaries)
+* **cert.pem** - Your signed Orca server cert
+* **key.pem** - Your Orca server private key
 
 After setting up these files on the host, you can install with the "--external-orca-ca" flag.
 
+If you are creating your own storage volumes (for example, to take
+advantage of a 3rd party storage driver) you can omit the **orca-root-ca**
+volume as it will not be used when using an external Orca Root CA.
+
 ```bash
 docker run --rm -it \
     -v /var/run/docker.sock:/var/run/docker.sock \