add README

fix from/to version hack

1 files changed, 63 insertions, 0 deletions

diff --git a/README.lut b/README.lut
new file mode 100644
index 0000000..af88681
--- /dev/null
+++ b/README.lut
@@ -0,0 +1,63 @@
+LEAP Upgrade Test
+-----------------
+
+This is basically a provider directory, with a simple shell script to automate
+upgrades from one Platform version to another. Ideally, this will be relatively
+short-lived and we will integrate it into the CI, but for now, here it is.
+
+The basic idea is to make an upgrade test provider that has a number of
+different services configured, fires up different nodes in AWS to init and then
+deploy those services from <old version>, then go through the process of
+upgrading those nodes to <new version>.
+
+The provider is configured to try and provide all the service node
+configurations that might be picked:
+
+ . a monitor with a tor hidden service and a webapp
+ . a couchdb/soledad server
+ . a mx server
+ . an openvpn server would be nice, but we need an addition gateway address
+ . a static node, with a tor hidden service
+ . a tor exit node
+ . a single node with all of the above configured
+
+In order to run the upgrades, you must first `apt install git-crypt` and then do
+git-crypt unlock so that you have access to the AWS credentials in the
+cloud.json file unlocked and available, then you just do:
+
+bin/lut.sh <old version> <new version>
+
+This process takes a long time (mostly because of AWS node startup happening in
+serial, and waiting for the ssh host keys). If it fails, the nodes are stopped,
+but *not removed* so you can start them again and investigate any
+problems. Please note that this accrues costs, so remove them as soon as
+possible.
+
+It is recommended that you run the following in your lut directory:
+
+git update-index --assume-unchanged nodes/{checkerspot,cloak,dogface,hairstreak,monarch,spicebush,cloak}.json
+
+this will make it so git will ignore future changes to those .json
+files. Because of the way the AWS integration works, when the nodes are created
+an IP is allocated and automatically put into the node's json file. This means
+that these files change all the time and become unstaged changes in git, which
+can be a bit annoying. The above command only sets this for the local repository.
+
+To make changes to these files, run the above command again, but with
+--no-assume-unchanged instead.
+
+Errata
+------
+
+Due to the fact that platform 0.8 does not have fog support, it is not possible
+to do `leap vm` things when the platform is checked out for 0.8. So to get
+around this we have to have 0.9 checked out, and do a `leap node init` with the
+0.9 platform version. This is subobtimal, but will change in future releases now
+that fog is integrated.
+
+Also, because we change from submodules to subrepos, the upgrade process for
+doing this is a bit difficult because we need to be able to go back and forth
+between the two versions (due to the above issue). So, to deal with this, we
+check out a different platform version in two different directories and use
+those distinctly, instead of trying to do the migration to subrepos. This is
+also a bit suboptimal because it means we do not test that migration.