Domain verification for the Google Cloud platform

Important

This note serves as a companion to our description of deployments to Google Cloud.

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/.
  • "staging" will be deployed to https://webapp.test.cat.gcp.uis.cam.ac.uk/.
  • "production" will be deployed to https://cat.apps.cam.ac.uk/.

Note

It is possible to have "staging" and "development" hosted from custom domains and, depending on the application, that may be preferable. The additional steps for "production" below work equally well in "test" and "development" for configuring custom domains.

Prerequisites

Deployment to development is semi-automated but test and production deployments require the following in the Cambridge IP register database:

  • 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:

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 "staging", 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:

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, devops@uis.cam.ac.uk. 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. For example, if your CNAME host was abc1234.devel.cat.gcp.uis.cam.ac.uk and the target was gv-XXXXXX.dv.googlehosted.com, set cname_host to abc1234 and cname_target to gv-XXXXXX.dv.googlehosted.com.
  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 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:

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, devops@uis.cam.ac.uk. 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 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, add "webapp.prod.gcp.uis.cam.ac.uk" as the vbox name, provide a descriptive purpose and click create.
  2. In 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.