Skip to main content

Creating resources in Cloud Platform

Namespaces

Cloud Platforms host a Kubernetes cluster which is logically divided into namespaces aka environments. We deploy applications into these namespaces using Helm. Each application will eventually require three namespaces:

  • dev must never contain real data
  • preprod environments generally contain real data that may be slightly stale - prison services tends to referesh data from live to production every two weeks for instance
  • prod environments represent the live service.

There’s a requirement that you must have appropriate clearance to be able to access real data.

Sometimes it makes sense to group applications together into a single namespace, for example you may have a related UI and API that belong together. This is fine but we would still require multiple environment namespaces for dev, preprod and prod.

Sometimes we need additional environment namespaces, for example some probation applications also have a staging namespace to work with the Delius staging environment. This is fine but will mean some extra work in the helm configurations when copying the template applications.

There is a plan to incorporate into the bootstrap process the creation of new namespaces (or updating of existing ones) for new applications.

Note

Initially teams should only create a dev or proof of concept environment. You need to talk to a Principal Technical architect before you can promote a service to environments that contain live data.

Requirements

Do I need a new namespace?

If your application is in a new service area you will definitely need namespaces for the dev, preprod and prod environments. If your application fits nicely alongside existing application(s) you can skip creating a new namespace and reuse the existing ones. However, you will probably need to create a Kubernetes certificate resource for your new application.

Creating new namespaces

If you do need new namespaces then you will need to add some terraform to the cloud-platform-environments git repository.

Each new namespace needs new Kubernetes resources such as an ingress (to allow inbound traffic), access roles (to give humans and build tools access to the namespace), a certificate (to use TLS) amongst others.

dev namespace

Initially we will create a dev namespace. We’ll refer to this as <your-new-service-name>-dev where <your-new-service-name> is whatever you’ve called your new service.

  • In the cloud-platform-environments repo create a new branch
  • Look in directory namespaces/live-1.cloud-platform.service.justice.gov.uk
  • The github Kotlin and Typescript template projects are both configured to use the hmpps-templates-dev directory, and it can be used as the basis of your project’s namespace configuration for the -dev, -preprod and -prod environments with appropriate changes.
  • Create a copy of this template directory, and rename it, appending dev to your new service name, e.g. <your-new-service-name>-dev

You will now have a bunch of Kubernetes definition files in your new directory. There will be several places that need updating:

  • Change the defaults under directory resources/variables so they are appropriate to your project.
  • Replace the template namespace references with your new namespace name (e.g. replace all instances of hmpps-template-kotlin with <your-new-service-name>-dev). Some projects will not have a github repository at this point, the following stages after creating the namespaces will create this for you. The cloud-platform.justice.gov.uk/source-code: for you project will be https://github.com/ministryofjustice/<your-new-service-name>.git
  • When finished perform a quick search for the word template in your new directory in case you missed any
  • Add your GitHub team to the rbac yaml - copy the existing subject of kind Group but replace hmpps-sre with your GitHub team. (Note: please copy, do not replace the hmpps-sre Group - it is required for administration tasks on the namespace).
  • Update the certificate’s DNS name. By convention we prefer <your-new-service-name>-dev.hmpps|prison|probation.service.justice.gov.uk - where you choose one of hmpps, prison or probation
  • Check that the certificate’s DNS name isn’t longer than 63 characters - if it is you’ll need to choose a shorter name
  • Make sure the certificate’s property spec.secretName doesn’t include the word dev. This secret name should be the same for all namespaces/environments.

Once your updates are complete push your branch back to the repo and raise a new Pull Request. You’ll then need to ask on MOJ Slack channel #ask_cloud_platform for a review of the PR.

Once approved, merge the PR.

A Concourse job will run in the background which should eventually create your new namespace. When the namespace is ready the command kubectl get namespaces | grep <your-new-service-name>-dev should return your new namespace.

Updating Cloud Platform namespaces

The key to being able to deploy with Github Actions is storing Kubernetes credentials within Github itself. The good news is that Cloud Platforms can facilitate this by creating service accounts that can populate the environments section of Github, and both apply permissions for approval/deployment and store the secrets so that they can be referred to by Github Actions.

Furthermore, these secrets can automatically be rotated, improving security. This section details how to create the service account and populate the environments

Namespaces and mappings

It is assumed that each deployment environment has its own namespace, but this namespace can be shared by a number of components within a product (eg. ui and api).

This is the important bit: for this to make sense, the environments should all match: (links show examples within the template repo)

There are also three configurations required to be added to the namespace - these can all be found under the hmpps-templates-dev/resources folder:

  • Github service account (resources/serviceaccount-github.tf)
  • Application Insights secret (resources/applicationinsights.tf)
  • Time definition (additional lines within resources/versions.tf)

HMPPS Cloud Platform Terraform Template

Within the hmpps-templates-dev namespace definition there are two files - template-kotlin.tf and template-typescript.tf

The environment configuration for each repo that will deploy to this namespace can be easily set up using these templates. Copy the appropriate one to your namespace, rename it to the first of the repositories to which you wish to deploy, and set the following fields:

Mandatory fields
  • github_repo = “your github repository”
  • application = “your application”
  • github_team = “your github team”
  • application_insights_instance = "dev, preprod or prod
  • source_template_repo = “hmpps-template-typescript or hmpps-template-kotlin” This is required to deploy the correct Application Insights configuration
Default fields
  • is_production = var.is_production
    This inherits the is_production namespace variable
  • environment = var.environment namespace variable for the environment; this must match the environment name used in helm values file e.g. values-dev.yaml
Optional fields

  • reviewer_teams = [“List”, “Of”, “Github”, “Teams”] If this is set, only the teams listed will be allowed to deploy to this environment. Comment it out if it’s not needed

  • selected_branch_patterns = ["branch, "patterns/"] If this is set, the selected branches will be allowed to be deployed.

  • protected_branches_only = true Comment this out if selected branches is in use
    Note: One or other of the above needs to be set.

Further information on the Cloud Platform HMPPS Template can be found here

This page was last reviewed on 27-Jan-2025, next review will be on 01-Jul-2025.
Edit this page here.