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.
- 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.
- Select Other as a domain name provider and click the Add a CNAME record link.
- 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 theworkspace_domain_verification
section of locals.tf. For example, if your CNAME host wasabc1234.devel.cat.gcp.uis.cam.ac.uk
and the target wasgv-XXXXXX.dv.googlehosted.com
, setcname_host
toabc1234
andcname_target
togv-XXXXXX.dv.googlehosted.com
. - Apply the configuration so that the verification CNAME record is created.
- 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.
- 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. - Add
verified = true
to the workspace's domain verification state inworkspace_domain_verification
in locals.tf. - 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.
- 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.
- Select Other as a domain name provider and click the Add a CNAME record link.
- 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:
- Click Verify to verify ownership.
- 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. - Add
cat.apps.cam.ac.uk
to theworkspace_webapp_custom_dns_name
map in locals.tf. - 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.
- In vbox_ops, add "webapp.prod.gcp.uis.cam.ac.uk" as the vbox name, provide a descriptive purpose and click create.
- 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.