Skip to main content

Using a custom domain

Background

Every application running on the Cloud Platform is able to use a hostname for its HTTP endpoints, using a pre-defined domain:

*.apps.live-1.cloud-platform.service.justice.gov.uk

This works automatically, using a wildcard TLS certificate.

Most applications will need their own, application-specific gov.uk hostname. These hostnames (or usually, entire domains) are managed individually and a number of actions are required to set them up.

Setup

Domains are managed inside DNS zones. You can read more about the structure of the Domain Name System in this page. It is recommended that applications use their own DNS zones, to provide better isolation, and make management simpler.

Defining the DNS zone

To create the zone, you define it as a resource in your environment. Make sure to read the guidance on naming domains first, and follow the instructions to create the Route53 zone.

To simplify management, we recommend that you only define a single zone, as part of the resources for your production environment, if possible. You can still use subdomains of that zone for different environments.

Once the zone is created, you will need to setup the necessary name server (NS) records in the parent DNS zone, before you can use it. For more information on how this delegation method works, you can read about authoritative name servers in this page.

If your zone is for a subdomain of service.justice.gov.uk (eg.: https://myapp.service.justice.gov.uk), the Cloud Platform team can help you set it up; please create a support ticket.

For any other domains (including any subdomain of gov.uk, eg.: https://myservice.gov.uk), you will need to contact the parent zone’s administrators (usually GDS) to set this up. If in doubt, don’t hesitate to get in touch with us in #ask-cloud-platform.

Please note, once you setup the NS records, you’ll be delegating control of the zone to the Cloud Platform. Hostnames used by your services (using Ingresses) will be automatically managed by the cluster.

If you wish to create custom records in your zone you can do so by defining them in the environments repository using the terraform aws_route53_record resource.

Obtaining a certificate

  1. Create the Certificate resource, filling in any placeholders with your details. The secretName attribute defines the name of a kubernetes secret in your namespace where the certificate and key material will be stored.

Please add the certificate by defining it in your namespace folder in the environments repository. Doing so means it will automatically be restored in the event of any problems with our certificate/DNS systems.

   ---
   apiVersion: cert-manager.io/v1alpha3
   kind: Certificate
   metadata:
     name: <my-cert>
     namespace: <my-namespace>
   spec:
     secretName: <my-cert-secret>
     issuerRef:
       name: letsencrypt-production
       kind: ClusterIssuer
     dnsNames:
     - <hostname>
  1. Make sure the certificate has been issued correctly, by checking its Status:
   $ kubectl describe certificate <my-cert>

The certificate status of type "Ready" should be True:

   Status:
     Conditions:
       Last Transition Time:  2019-06-05T10:16:43Z
       Message:               Certificate is up to date and has not expired
       Reason:                Ready
       Status:                True
       Type:                  Ready
     Not After:               2019-09-03T09:16:42Z
   Events:
     Type    Reason         Age   From          Message
     ----    ------         ----  ----          -------
     Normal  Generated      3m    cert-manager  Generated new private key
     Normal  OrderCreated   3m    cert-manager  Created Order resource "<my-cert>-3189350212"
     Normal  OrderComplete  1m    cert-manager  Order "<my-cert>-3189350212" completed successfully
     Normal  CertIssued     1m    cert-manager  Certificate issued successfully

It generally takes just a few minutes for the certificate to be prepared and the events displayed should indicate if there is a problem, or it simply needs more time. If you cannot obtain a certificate, please get in touch with us in #ask-cloud-platform.

  1. You will need to update your Ingress spec to include the new hostname.
     apiVersion: networking.k8s.io/v1beta1
     kind: Ingress
     metadata:
       name: <my-ingress>
       namespace: <my-namespace>
       annotations:
         kubernetes.io/ingress.class: <my-namespace>
     spec:
       tls:
       - hosts:
         - my-app.apps.live-1.cloud-platform.service.justice.gov.uk
   +   - hosts:
   +     - <hostname>
   +     secretName: <my-cert-secret>
       rules:
       - host: my-app.apps.live-1.cloud-platform.service.justice.gov.uk
         http:
           paths:
           - path: /
             backend:
               serviceName: <my-svc>
               servicePort: 80
   +   - host: <hostname>
   +     http:
   +       paths:
   +       - path: /
   +         backend:
   +           serviceName: <my-svc>
   +           servicePort: 80

Once you’ve made the changes to your Ingress, the cluster (and more specifically, external-dns) will update the necessary records defined in it. This usually takes less than a minute until you are able to access your endpoint. However, depending on the DNS name servers your workstation uses, you might need to wait longer or try to “flush” your local DNS cache in order to speed up the process. You should search online for the proper method to do so, based on your operating system and/or browser.

This page was last reviewed on 19 May 2021. It needs to be reviewed again on 19 August 2021 .
This page was set to be reviewed before 19 August 2021. This might mean the content is out of date.