add notes on domain verification

Closes #33

docs/notes/google-domain-verification.md

+title: Domain verification
+
+# Domain verification for the Google Cloud platform
+
+!!! important
+    This note serves as a companion to our [description of deployments to Google
+    Cloud](./gcp-deployments.md).
+
+When deploying services to Google Cloud platform (GCP), you will usually want
+them accessible as "friendly" names under `cam.ac.uk`. In this note we'll
+consider how to deploy a new service called "ShareMyCat".
+
+As part of our standard deployment, you should have a "ShareMyCat" product
+folder in GCP and a standard terraform deployment template. Our standard
+terraform deployment is set up to deploy into three workspaces: "development",
+"test" and "production".
+
+Alongside the product folder, you should also have a *product DNS zone*. For
+"ShareMyCat" this might be `cat.gcp.uis.cam.ac.uk`.
+
+In this note we'll cover how to deploy the ShareMyCat service to the following
+locations:
+
+* "development" will be deployed to
+    **https://webapp.devel.cat.gcp.uis.cam.ac.uk/**.
+* "test" will be deployed to **https://webapp.test.cat.gcp.uis.cam.ac.uk/**.
+* "production" will be deployed to **https://cat.apps.cam.ac.uk/**.
+
+## Prerequisites
+
+Deployment to development is semi-automated but test and production deployments
+require the following in the Cambridge [IP register
+database](https://www.dns.cam.ac.uk/):
+
+* `cat.gcp.uis.cam.ac.uk` must be covered by an MZONE you have admin rights to.
+* `cat.apps.cam.ac.uk` must be covered by the same MZONE.
+
+You should also have deployed the terraform configuration for all the workspaces
+you want to verify. Refer to the README in each deployment configuration for any
+product-specific steps but usually this just entails running:
+
+```sh
+logan --workspace=[WORKSPACE] terraform apply
+```
+
+## Verification steps for all workspaces
+
+For all workspaces, it is useful to verify and deploy the application under
+`cat.gcp.uis.cam.ac.uk`. Verification under this domain is semi-automated and
+does not require hostmaster intervention.
+
+Follow these instructions for *all* workspaces. For "production", additionally
+follow instructions in later sections.
+
+!!! note
+    These instructions talk about the "development" workspace and
+    `devel.cat.gcp.uis.cam.ac.uk`. For "test", follow the same steps changing
+    the domain to `test.cat.gcp.uis.cam.ac.uk`.
+
+Once the workspace has been deployed via `terraform apply`, start domain
+verification using the [gcloud tool](https://cloud.google.com/sdk/install):
+
+```sh
+gcloud domains verify devel.cat.gcp.uis.cam.ac.uk
+```
+
+A browser window will appear with the Google Webmaster tools page shown.
+
+1. Click the avatar in the top-right corner and make sure that you are signed in
+   as the UIS DevOps bot user. Credentials for this user can be found in
+   1password.
+2. Select **Other** as a domain name provider and click the **Add a CNAME
+   record** link.
+3. You will be asked to add a CNAME record of the form
+   `[HOST].devel.cat.gcp.uis.cam.ac.uk` pointing to some target.
+   Add the `[HOST]` part and target to the `workspace_domain_verification`
+   section of locals.tf.
+4. Apply the configuration so that the verification CNAME record is created.
+5. It will take up to 5 minutes for Google's DNS to start serving the CNAME
+   record. Make a cup of coffee and then click **Verify** to verify ownership.
+6. When verification is successful, click **Add additional owners to
+   devel.cat.gcp.uis.cam.ac.uk.**, add add the *project admin
+   service account* email address. This is available in the
+   `project_admin_service_account_email` terraform output.
+7. Add `verified = true` to the workspace's domain verification state in the
+   `workspace_domain_verification` in locals.tf.
+8. Apply the configuration again to create the Cloud Run domain mapping and
+   associated records.
+
+It will take some time for Google to issue you a certificate but after issuance,
+the application will be available at
+**https://webapp.devel.cat.gcp.uis.cam.ac.uk/**.
+
+## Verification steps for production
+
+!!! important
+    Make sure to complete the common verification steps above, even for
+    production.
+
+Unfortunately, we cannot yet semi-automate the verification of domains outside
+of `gcp.uis.cam.ac.uk`. For the "production" workspace we need to manually
+verify the `cat.apps.cam.ac.uk` domain as well.
+
+Proceed as before via `gcloud`:
+
+```sh
+gcloud domains verify cat.apps.cam.ac.uk
+```
+
+A browser window will appear with the Google Webmaster tools page shown.
+
+1. Click the avatar in the top-right corner and make sure that you are signed in
+   as the UIS DevOps bot user. Credentials for this user can be found in
+   1password.
+2. Select **Other** as a domain name provider and click the **Add a CNAME
+   record** link.
+3. You will be asked to add a CNAME record of the form
+   `[HOST].cat.apps.cam.ac.uk` pointing to some target. Email the host and
+   target to [hostmaster@cam.ac.uk](mailto:hostmaster@cam.ac.uk) explaining that
+   the record is needed for verifying the domain to Google.
+
+Once hostmaster has added your records and they are being served, you can
+continue with verification:
+
+1. Click **Verify** to verify ownership.
+2. When verification is successful, click **Add additional owners to
+   cat.apps.cam.ac.uk.**, add add the *project admin
+   service account* email address. This is available in the
+   `project_admin_service_account_email` terraform output.
+3. Add `cat.apps.cam.ac.uk` to the `workspace_webapp_custom_dns_name` map in
+   locals.tf.
+4. Apply the terraform configuration.
+
+## DNS records for production
+
+!!! important
+    Remember that `cat.apps.cam.ac.uk` and `cat.gcp.uis.cam.ac.uk` must both be
+    in the same mzone and your account must have rights over that mzone to
+    register records via the IP register database.
+
+The process to configure the Cambridge DNS servers to serve the correct records
+for the `cat.apps.cam.ac.uk` service address is a little involved. We will make
+use of the fact that, in production, `webapp.prod.cat.gcp.uis.cam.ac.uk` has been
+set up with the correct hosting records. We can therefore add a CNAME record
+from `cat.apps.cam.ac.uk` to `webapp.prod.gcp.uis.cam.ac.uk` to serve the
+application.
+
+1. In [vbox_ops](https://jackdaw.cam.ac.uk/ipreg/vbox_ops), add
+   "webapp.prod.gcp.uis.cam.ac.uk" as the vbox name, provide a descriptive
+   purpose and click **create**.
+2. In [cname_ops](https://jackdaw.cam.ac.uk/ipreg/cname_ops), add
+   "cat.apps.cam.ac.uk" as the name, provide a descriptive purpose, add
+   "webapp.prod.gcp.uis.cam.ac.uk" as the target and click **create**.
+
+When the DNS servers next update your CNAME will be served. Google will then
+(eventually) notice, issue a certificate and your application will be live.

mkdocs.yml

@@ -12,6 +12,7 @@ nav:
     - notes/webapp-dev-environment.md
     - notes/automating-google-drive.md
     - notes/gcp-deployments.md
+    - notes/google-domain-verification.md
   - 'Workflow':
     - workflow/index.md
     - workflow/gitlab.md