add README
[lut.git] / README.lut
1 LEAP Upgrade Test
2 -----------------
3
4 This is basically a provider directory, with a simple shell script to automate
5 upgrades from one Platform version to another. Ideally, this will be relatively
6 short-lived and we will integrate it into the CI, but for now, here it is.
7
8 The basic idea is to make an upgrade test provider that has a number of
9 different services configured, fires up different nodes in AWS to init and then
10 deploy those services from <old version>, then go through the process of
11 upgrading those nodes to <new version>.
12
13 The provider is configured to try and provide all the service node
14 configurations that might be picked:
15
16  . a monitor with a tor hidden service and a webapp
17  . a couchdb/soledad server
18  . a mx server
19  . an openvpn server would be nice, but we need an addition gateway address
20  . a static node, with a tor hidden service
21  . a tor exit node
22  . a single node with all of the above configured
23
24 In order to run the upgrades, you must first `apt install git-crypt` and then do
25 git-crypt unlock so that you have access to the AWS credentials in the
26 cloud.json file unlocked and available, then you just do:
27
28 bin/lut.sh <old version> <new version>
29
30 This process takes a long time (mostly because of AWS node startup happening in
31 serial, and waiting for the ssh host keys). If it fails, the nodes are stopped,
32 but *not removed* so you can start them again and investigate any
33 problems. Please note that this accrues costs, so remove them as soon as
34 possible.
35
36 It is recommended that you run the following in your lut directory:
37
38 git update-index --assume-unchanged nodes/{checkerspot,cloak,dogface,hairstreak,monarch,spicebush,cloak}.json
39
40 this will make it so git will ignore future changes to those .json
41 files. Because of the way the AWS integration works, when the nodes are created
42 an IP is allocated and automatically put into the node's json file. This means
43 that these files change all the time and become unstaged changes in git, which
44 can be a bit annoying. The above command only sets this for the local repository.
45
46 To make changes to these files, run the above command again, but with
47 --no-assume-unchanged instead.
48
49 Errata
50 ------
51
52 Due to the fact that platform 0.8 does not have fog support, it is not possible
53 to do `leap vm` things when the platform is checked out for 0.8. So to get
54 around this we have to have 0.9 checked out, and do a `leap node init` with the
55 0.9 platform version. This is subobtimal, but will change in future releases now
56 that fog is integrated.
57
58 Also, because we change from submodules to subrepos, the upgrade process for
59 doing this is a bit difficult because we need to be able to go back and forth
60 between the two versions (due to the above issue). So, to deal with this, we
61 check out a different platform version in two different directories and use
62 those distinctly, instead of trying to do the migration to subrepos. This is
63 also a bit suboptimal because it means we do not test that migration.