Skip to main content

Creating environments in the Modernisation Platform

Overview

In the Modernisation Platform, we define environments (AWS accounts) via a JSON file in the environments directory of the Modernisation Platform repository.

When we receive your request we will create a new JSON file and submit a pull request to the Modernisation Platform repository. On merging the Modernisation Platform will automatically provision your environments. Each environment defined represents an AWS account, see the example below for more information.

Requesting an environment

To request a new environment, simply create an issue using the New Modernisation Platform Environment template.

This issue will go into the Modernisation Platform backlog and be prioritised along with other issues. Normally new environment requests are taken into the next sprint (we work in 2 week sprints) and once picked up are completed within a day. You can see which sprint your issue has been assigned to on the issue, and follow progress once it is in a sprint here

This will ask you for the following information:

Application name

Please follow MoJ guidance for naming things The name must be in lowercase and a maximum of 30 characters. If you need to use a separator use -.

GitHub team slug

This is the name of your GitHub team that will be accessing the environment. Environments are accessed via single sign-on (SSO), so to give people permissions to access your environment you just have to add them to your GitHub team.

Users who are not part of the MoJ GitHub organisation will need to be added as collaborators separately once the account has been created. Please contact the Modernisation Platform team to do this.

If you wish to add additional deployment reviewers from outside your GitHub team you can specify these per an environment in the application.json file (See: “additional_reviewers” in Another example for an example).

GitHub code owner team slug

By default members of the GitHub team/s specified can both access the AWS environments and approve pull requests to release changes.

If required you can separate the permissions so that a different GitHub team acts as a code owner, this way PRs will require a review from this team before changes are released.

GitHub action reviewers team slug

By default all teams listed in the access blocks for an environment can approve the corresponding GitHub action runs.

If required you can separate the permissions so that a different GitHub team is the approver. In this case all Github action runs requiring approval, such as terraform applies, will need to be approved by a member of the team provided.

Access

This is the level of access for the GitHub team to the Modernisation Platform. A full list of permissions for the different access levels can be found here (previously within bootstrap/delegate-access) You can read documentation on available roles here.

Environment name

Which environments you wish to use, we provide core networking for up to 4 accounts as standard. Usually, two environments per application will be enough, a production account and a development account.

  • development
  • test
  • preproduction
  • production

As these environments are identical, and controlled via code, we would recommend you try to use as few environments as possible. We can provide more environments if there is a genuine need for them.

Tags

These will be used to tag your AWS resources, for further guidance on tagging please see here

The is-production tag will be inferred if the environment is production.

tag value
application Find a solicitor
business-unit LAA
owner find-a-solicitor@ministryofjustice.gov.uk

Valid business-unit values HQ,HMPPS,OPG,LAA,HMCTS,CICA,Platforms,CJSE

Additional features

In addition to the core networking provided, you can request bastion access, additional VPC endpoints, extended DNS zones or an isolated network environment.

See creating networking for more information on additional features.

Architecture

You can view our architecture for Environments (AWS accounts) on the dedicated Environments (AWS accounts) architecture page, which also explains what you get by doing this.

Example JSON files

Here are some examples of the environments JSON file that the Modernisation Platform team will create.

Schema

  • account-type determines if this is a core modernisation platform account or a user member account.
  • isolated-network is an optional field which can be set to ‘true’ if you require an isolated environment with no internet or shared network connectivity.
  • codeowners is an optional list of GitHub slugs if you want specific teams to review code changes before they are released into environments. It is NOT generally used. Compare the Blank example with Another example below, to see it is unused.
  • environments should be an array of objects for environments required. If the environment is production, retention periods, backup frequency, and similar will be different compared to non-production environments.
  • the name key and access object are required, see: Another example
  • github_action_reviewer is an optional true/false for each team listed and determines if the team should be the approver for GitHub action runs.
  • the nuke key is optional and is only read if the access.level is sandbox.
  • tags should be an object of the mandatory tags defined in the MoJ Tagging Guidance. You can omit is-production as we infer this from the environment name. Note that the infrastructure-support tag must contain a valid email address.

Blank example

filename: application-name.json

{
  "account-type": "",
  "isolated-network": "",
  "codeowners": [""],
  "environments": [
    {
      "name": ""
      "access": [
        {
          "github_slug": "",
          "level": "",
          "nuke": "",
          "github_action_reviewer": "true"
        }
      ]
    }
  ],
  "tags": {
    "application": "",
    "business-unit": "",
    "infrastructure-support": "",
    "owner": ""
  },
  "github-oidc-team-repositories": [""],
  "go-live-date": ""
}

Another example

An JSON definition for a nonsensical application called glados, that needs two environments: development with sandbox permissions and production, and want to give the GitHub team glados-team access to each environment. If a develoment account with sandbox permissions has no nuke key defined, it will automatically be wiped on a weekly basis. The nuke value of rebuild indicates that the development account will be automatically rebuilt from code after it is nuked.

filename: glados.json

{
  "account-type": "member",
  "environments": [
    {
      "name": "development",
      "access": [
        {
          "github_slug": "glados-team",
          "level": "sandbox",
          "nuke": "rebuild"
        }
      ],
      "additional_reviewers": ["GitHubUsername1", "GitHubUsername2"]
    },
    {
      "name": "production",
      "access": [
        {
          "github_slug": "glados-team",
          "level": "view-only"
        }
      ],
      "additional_reviewers": ["GitHubUsername3", "GitHubUsername4"]
    }
  ],
  "tags": {
    "application": "GLaDOS",
    "business-unit": "Platforms",
    "infrastructure-support": "aperture-science@digital.justice.gov.uk",
    "owner": "GLaDOS (Genetic Lifeform and Disk Operating System): aperture-science@digital.justice.gov.uk"
  },
  "github-oidc-team-repositories": [""],
  "go-live-date": ""
}

This will provision two AWS accounts, which will be called: glados-development, and glados-production.

This page was last reviewed on 22 July 2024. It needs to be reviewed again on 22 January 2025 by the page owner #modernisation-platform .
This page was set to be reviewed before 22 January 2025 by the page owner #modernisation-platform. This might mean the content is out of date.