Add documentation for deployment, configuration, and testing
Change-Id: If4baed280a4de4470902d49b52554474a951dcd5
Signed-off-by: Avi Kondareddy <avikr@google.com>
diff --git a/README.md b/README.md
index 27f1e32..25c69af 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,5 @@
# Prow LKML email server for KUnit
-TODO(avikr@google.com): add a better description.
-
KUnit is an in-tree unit testing framework for the Linux kernel. In the Linux
kernel community, mailing lists are commonly used to propose and discuss
patches. In order to foster the utilization of KUnit, we are making a presubmit
@@ -11,3 +9,51 @@
the ability to trigger presubmit for Linux Kernel Mailing List patches on Prow
using KUnit and report back to the mailing lists.
+# Deployment / Configuration
+
+First need:
+ - GKE cluster
+ - GCS bucket: for storing/viewing job results/artifacts (see kunit/prow-presubmit)
+ - Service account key with read/write access (json file)
+
+config.yaml : contains the job configuration for the patches to be run against
+ should be the same as regular kunit except you should specify the mailing list
+ instead of the repo as the key for the job.
+
+service-account.json : need to include service account of gcloud account in
+secret called 'service-account'. Needed for uploading to the gcloud bucket.
+see kunit/prow-presubmit for more details
+
+deployment.yaml : standard barebones prow deployment
+
+service.yaml: exposes external port for smtp server and internal for git.
+Need to see deployed environment for external ip address assigned. Then by
+adding an mx record for the ip in your domain's dns configuration, you can send
+emails to {anyusername}@{yourdomain} and it will arrive at this component.
+
+lkml.yaml: Deploys lkml component. Need to specify repo, branch, and mailing
+list address associated with the job in config.
+
+crier.yaml: Deploys custom crier component for mail reporting at kunit/test-infra-prow.
+Need to specify from and to addresses and domain of msa agent. Provide a secret
+named "smtpsecret" mapping "password" to email password. For gmail, you can
+setup a custom app password independant of your login / two-factor
+authentication that will allow you to authenticate over smtp.
+
+# Testing
+First, set up cluster, mx records to forward emails to a specific domain to
+cluster's smtp load balancer, access to an email account for sending reports back.
+
+If debugging general cluster issues with lkml or crier, you can simply delete
+the replicaset for the
+corresponding deployment `kubectl delete replicaset lkml-{autocomplete}` to
+relaunch pods, repulling the latest images from gcr.io/kunit-presubmit.
+
+If debugging lkml specifically, it might be wise to setup to clone a smaller
+repo if testing job triggering / reporting. For job execution, if lkml can be
+relied on to keep a valid repo at deployed persistentVolumeClaim, then just
+deleting the replicaset should be sufficient. Otherwise, you should also
+recreate the volume.
+
+Sinker automatically clears out stale jobs / pods after a specified interval.
+You can alternatively manually delete prowjobs and job pods.
