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 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 The options are as follows:

view-only

• Log into the console
• See resources and basic metadata. You cannot see the content of resources such as logs or S3 buckets.

read-only

• Log into the console
• Comprehensive read-only visibility of the AWS environment. As this role provides access to contents of S3 and others, it is designed for users for whom view-only is insufficient.
• Role makes use of AWS ReadOnly managed policy and is not at present configurable beyond that.

developer

• Log into the console
• Read only access to resources including things like logs and S3 buckets
• View and Edit Secrets Manager secrets and Parameter Store values
• Create and rotate access keys for the application deployment CI user
• Connect to instances via SSM
• Start, stop and reboot EC2 instances
• Create and copy Snapshots
• Put and delete S3 objects
• Import certificates to ACM
• Switch roles to view shared resources
• Raise AWS Support cases

sandbox

The sandbox access can only be used on a development environment account.

• Log into the console
• Same console read and write permissions as the pipelines have
• This permission can only be attached to development accounts
• Once a week the account will be cleared with AWS Nuke and then rebuilt from Terraform

The idea of sandbox access is that it gives you the freedom to experiment and modify things in the console to assist with creating your Terraform code.

Anything not in code will be lost at the end of the week.

migration

The migration role is a temporary role, given to assist with AWS managed migration services

• Log into the console
• Developer permissions
• Permissions to use AWS Migration services

Once the migration is complete for an environment this role should be removed.

instance-management

The instance-management role is a role given to assist database administrators.

• Log into the console
• Read only access to resources including things like logs and S3 buckets
• Start, stop and reboot EC2 instances
• Create and copy Snapshots
• Connect to instances via SSM
• Active Directory permissions

security-audit

• Log into the console
• See resources and metadata useful to security operations teams and security audit teams
• Makes use of AWS managed SecurityAudit policy

reporting-operations

• DMS Start, stop
• SQL Workbench
• Athena
• Glue
• Redshift

data-engineering

Created for data engineers to have developer permissions as well as glue and athena permissions all in one policy.

• Log into the console.
• Data engineering permissions.

administrator

• Full admin access

This is a legacy role and will not be generally available.

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.
• github_action_reviewers is an optional list of GitHub slugs if you want specific teams to approve GitHub action runs.
• 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
• 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.

Blank example

filename: application-name.json

{
  "account-type": "",
  "isolated-network": "",
  "codeowners": [""],
  "github_action_reviewers": [""],
  "environments": [
    {
      "name": ""
      "access": [
        {
          "github_slug": "",
          "level": "",
          "nuke": ""
        }
      ]
    }
  ],
  "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": "",
    "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 20 March 2024. It needs to be reviewed again on 20 September 2024 by the page owner #modernisation-platform .

This page was set to be reviewed before 20 September 2024 by the page owner #modernisation-platform. This might mean the content is out of date.