Skip to main content

Configuring the build pipeline

Typescript application secrets

If you are trying to create a Typescript application your deployment is probably failing. There are a few secrets that are only required by Typescript applications. Once these secrets are created your application should start deploying. It’s worth running the command kubectl -n <your-new-service-name>-dev get events to try and spot which secrets are missing.

session secret

The Typescript template project requires a secret which is used to sign session cookies. This is how it knows that cookies haven’t been tampered with when presented by a client. Using the Cloud Platform secrets guide update the secret <your-new-service-name> by adding a new key SESSION_SECRET followed by a random value (don’t forget to base64 encode the value).

Note: Please do not use / configure the Cloud Platform Secrets Manager, since this prevents scheduled secret rotation scripts from running successfully.

authorization_code client

Users sign in to the UI application using the Oauth2 authorization_grant flow. After a successful sign in the UI application calls hmpps-auth to receive a valid access token. We need a client and secret to prove to hmpps-auth that we are allowed to request access tokens. These secrets are stored in Kubernetes secrets API_CLIENT_ID and API_CLIENT_SECRET.

To request a new authorization code client from hmpps-auth raise a ticket on the DPS Tech Team JIRA board in this format. Then ask in MOJ Slack channel #hmpps-auth-audit-registers for the ticket to be prioritised. Once the clients have been created in hmpps-auth the DPS Tech team will copy the secrets into your namespace.

client_credentials client

When a UI application needs to call an API it must prove that it is authorised to call that API using the Oauth2 client_credentials flow. The UI application calls hmpps-auth to request an access token it can present to other APIs as authorisation. We need a client and secret to prove to hmpps-auth we can have an access token. These secrets are stored in Kubernetes secrets SYSTEM_CLIENT_ID and SYSTEM_CLIENT_SECRET.

To request a new client credentials client from hmpps-auth raise a ticket on the DPS Tech Team JIRA board in this format. Then ask in MOJ Slack channel #hmpps-auth-audit-registers for the ticket to be prioritised. Once the clients have been created in hmpps-auth the DPS Tech team will copy the secrets into your namespace.

Checking the application is healthy

We have now deployed the application to dev and need to check it is up and running as expected. Run command kubectl -n <your-new-service-name>-dev get ingress where you should find the host of your application. In a browser go to page https://<hostname>/health and you should see a health page with status UP.

Troubleshooting - Missing certificate

If you see an error such as Your connection is not private or Potential security risk ahead then it implies that the application is not using the certificate we generated with terraform earlier. Look in project file helm_deploy/<your-new-service-name>/values.yaml for property generic-service.ingress.tlsSecretName - this is the secret we copy the certificate from. Then run command kubectl -n <your-new-service>-dev get secrets to find a secret of type kubernetes.io/tls - this is the secret holding the certificate and should match the secret name in our project. If not then go back to the cloud-platform-environments project for dev and find the certificates yaml. Change the property spec.secretName to match the real secret name and issue a PR. You may also need to do this for preprod and prod.

Promoting to preprod

In the new project under the helm_deploy directory you should see a file called values-dev.yaml. This contains overrides to helm deployment configuration for the dev namespace. Create a values-preprod.yaml file in the same format. For Kotlin template projects this needs overrides to the generic-service.replicaCount, the generic-service.ingress.host and the generic-prometheus-alerts.alertSeverity properties. For Typescript template projects copy values-dev.yaml and update all properties in the generic-service section.

If you look at the project in Github Action workflow .github/workflows/pipeline.yml you should see that the last step in the jobs is deploy_dev is currently uncommented. In .github/workflows/pipeline.yml you will see a big section commented out - this contains extra steps to deploy to preprod and prod. Uncomment deploy_preprod deployment step.

Once these changes have been made raise a PR and merge when reviewed. Your Github Action build post deploy to dev completion, should show request approval to deploy to preprod. Approve the preprod approval in Github actions workflow runs. Once deployed check that the deployment is healthy in a similar way to checking the dev deployment but replacing dev with preprod.

If you are creating a Typescript application you may still have a failing deployment. Make sure you create the same secrets in preprod that you created for dev.

Adding an external health check to prod

For production we use an external health check monitor called pingdom. This checks the application is up and can be reached from outside of our networks.

  • In the cloud-platform-environments project add a pingdom health check for the application. Find another production namespace (e.g. hmpps-audit-prod) and copy file resources/pingdom.tf into your new directory. Update the name and change the url to match your certificate’s dnsName.
  • Add pingdom version details to the file resources/versions.tf (copy an existing production namespace such as hmpps-audit-prod).
  • Raise a PR, ask in MOJ Slack channel #ask-cloud-platform for a review and merge when approved.
  • As we haven’t deployed to prod yet we should receive an alert from pingdom saying that the application is down. This proves that the pingdom check is working so wait for the alert before promoting to prod.

Promoting to prod

In the new project under the helm_deploy directory you should see a file called values-dev.yaml. This contains overrides to helm deployment configuration for the dev namespace. Create a values-prod.yaml file in the same format. For Kotlin template projects this needs overrides to the generic-service.replicaCount, the generic-service.ingress.host and the generic-prometheus-alerts.alertSeverity properties. For Typescript template projects copy values-dev.yaml and update all properties in the generic-service section.

If you look at the project in Github Action workflow .github/workflows/pipeline.yml you should see that the last step in the jobs is deploy_dev is currently uncommented. In .github/workflows/pipeline.yml you will see a big section commented out - this contains extra steps to deploy to prod. Uncomment deploy_prod deployment step.

Once these changes have been made raise a PR and merge when reviewed. Your Github Action build post deploy to prod/dev completion based on steps in cluded in jobs section, should show request approval to deploy to prod. Approve the prod approval in Github actions workflow runs. Once deployed check that the deployment is healthy in a similar way to checking the dev deployment but replacing dev with preprod.