Creating AWS Accounts for Teams
Overview
This runbook outlines the procedure for creating AWS accounts for end users via the Modernisation Platform. It covers both the new semi-automated process and the existing manual method of creating pull requests (PRs) to implement the required changes.
All new account requests will be added to the To Do column of the Kanban board within the Modernisation Platform.
Semi-automated account creation process
The Modernisation Platform now provides a semi-automated process for account creation. This process is initiated by raising a new issue in the modernisation-platform repository.
Once initiated, the process will:
- Generate the required JSON configuration files.
- Update the relevant files in the
policiesdirectory. - Create a pull request in the modernisation-platform repository for review and approval.
This approach streamlines the account creation process, reduces the potential for manual error, and ensures greater consistency across environments.
Pull request review and approval
Before any pull request generated by the semi-automated process is merged, it must undergo a thorough review. This review is essential to ensure that the changes align with the customer’s original request and meet all relevant platform standards.
Reviewers should:
- Verify that all generated files are accurate and reflect the details provided in the original issue.
- Confirm that the account configuration adheres to established naming conventions, policies, and security requirements.
- Ensure that any additional manual changes required have been included.
- Seek clarification from the requester if any discrepancies or ambiguities are identified.
Only once the review has been completed and the changes approved should the pull request be merged into the main branch.
Making amendments to the pull request
If any changes are identified during the review, the corresponding branch should be checked out locally so that amendments can be made and committed before the pull request is approved. This ensures that all required updates are captured within the same branch and associated pull request, maintaining a clear and auditable history of changes.
Checking out the branch locally
To pull down the branch and make amendments, follow these steps:
- Ensure you have the latest version of the repository:
git fetch --all - Check out the branch associated with the pull request. Replace
with the actual branch name: git checkout <branch-name> - Make the necessary changes locally and commit them with a clear and descriptive commit message:
git add . git commit -m "Describe the changes made" - Push the updated branch to the remote repository:
git push
Once the changes have been pushed, the pull request will automatically update to reflect the new commits. The review can then be continued to ensure that the amendments address the identified issues before approval and merge.
Post-generation steps
After the pull request has been created by the semi-automated process, the subsequent steps mirror those described in the Manual account creation process. Specifically, you must still complete:
- Step 4: Merge the pull request created in the
modernisation-platformrepository. - Step 5: Merge the pull request generated in the
modernisation-platformrepository. - Step 6: Merge the pull request generated in the
modernisation-platform-environmentsrepository.
Note:
- The plan will fail on these PRs due to the networking not yet being complete. This is expected behaviour — the purpose of these PRs is to create the necessary files, not to trigger deployments.
- For isolated network environments, the setup process ends at this stage.
Networking pull request generation
Once the main environment pull request has been merged into the main branch, an additional workflow will run automatically. This workflow generates a new pull request containing updates to the networking JSON and network policy rego files required for the environment.
Unlike the initial environment pull request, this networking pull request is not automatically linked to the original GitHub issue. Users are therefore required to locate it manually within the modernisation-platform pull requests list.
This pull request must be reviewed and merged as part of the standard Networking Stage. The changes it contains are essential to ensure that networking is correctly configured for the new environment.
Note: This networking pull request is created automatically by the pipeline following the merge of the main PR. It is not linked to the issue, and no additional workflow needs to be triggered manually.
Manual account creation process
Here’s an example of an account request, and the steps that were taken in order to create it. There are links to pull requests and the stages they need to be opened and merged, as well as references and explanations as to why.
Information Required
Customers will fill out the new-environment template via our public repository here and supply the required information.
| Attribute | Description |
|---|---|
| Application name (file name) | The name must be in lowercase and a maximum of 30 characters. For our example we have data-and-insights-wepi
|
| isolated-network | If the user has requested an isolated network environment only complete the New Environment Files and stop when you reach the Networking Stage as this is not required. |
| SSO Group Name | This is the name of the Identity Center group used for SSO, which can be a GitHub team name 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. |
| Access | For our example, sandbox access has been requested. To read more about access levels, click here |
| Environment | This is one of the four valid environments, development, test, preproduction or production |
| Tags | application, business-unit and owner are in tags, and they are used to tag your AWS resources inside of your account. |
| Additional features | This example has no additional features, but things like VPN endpoints and extended DNS zones can be requested. |
New Environment Files
1. Create a new environment file
environments/$application-name.json
See an example file here.
Note - If you are adding an environment to an existing application you can add the new environment block to this file, you do not need to create another. Creating multiple environments in bulk is supported, but creating multiple application accounts is not.
By default the codeowners for the application teams folder in the modernisation-platform-environments repository will be the GitHub teams defined in the access block.
You can override this by defining codeowners as an attribute for that application.
"codeowners": ["<owner-name>"], Replace <owner-name> with a GitHub team such as modernisation-platform.
This will restrict code approval to only the SSO group names listed in the ‘codeowners’ attribute.
See #5957 for an example of the change required.
By default all teams listed in the access blocks for an environment can approve the corresponding Github action runs.
Alternatively, if you wish to specify the SSO group names that can approve the Github action runs for a specific environment, you can define github_action_reviewer as an attribute for that environment by setting "github_action_reviewer" : "true" in the access block for that environment/team.
"name": "development",
"access": [
{
"sso_group_name": "modernisation-platform",
"level": "developer",
"github_action_reviewer" : "true"
},
{
"sso_group_name": "some-other-team",
"level": "developer"
}
]
},
In this example, only the modernisation-platform team can approve the Github action runs for the development environment.
See #6338 for an example of the change required.
In a recent update to the JSON environment file we have added a new tag called critical-national-infrastructure, this tag exists to help us report on vital applications and infrastructure to the ministry of justice. This is a boolean input and the default is always false but if your application is critical then this should be set to true.
See #8191 for an example of the change required.
2. Update the expected.rego
Update the policies/environments/expected.rego file with the newly added application name.
This is to make sure that none of the json files gets accidentally deleted. This is going to be validated with the opa-policies GitHub Actions workflow.
3. Create a pull request for the changes made in steps 1 and 2
This will trigger the new-environment workflow, which will run its check-environments-deployment-plan. You can see what will change in the output from GitHub Actions.
4. Merge the pull request
This will run the new-environment workflow to create a new AWS account.
This will also run the new-environment-files workflow which generates two new pull requests if this is the first environment of the new application:
If the environment is being created for an account type of member-unrestricted it will not create the PR in the modernisation-platform-environments repository and this step can be ignored.
- Creating application files in the
modernisation-platformrepo. - Creating application files in the
modernisation-platform-environmentsrepo.
Note - These PRs are only created the first time an environment for an application is created, eg the first time you create a new application.json file. If you add to an existing environment the PRs will not be created.
The new-environment workflow may fail if the account alias is already in use. If this happens, add the environment name to the skip-alias local. Merging this PR will run the required jobs again.
5. Merge the pull request created in the modernisation-platform repo (step 4.1)
6. Merge the pull request created in the modernisation-platform-environments repo (step 4.2)
Note - The plan will fail on these PRs due to the networking not yet being complete. This is fine, the goal of these PRs is to create the necessary files, not make deployments.
Note - isolated network environment setup stops here and is completed.
Networking Stage
This stage sets up Resource Access Manager (RAM) sharing to share the relevant business unit subnet sets to the application account.
Business unit VPCs and subnet sets are already created for all the MoJ business units. If an additional VPC or subnet set is needed, see guidance here..
If the environment is being created for an account type of member-unrestricted this stage is not required and can be ignored.
1. Add the application to the relevant subnets
Add the application to the subnet sets in environments-networks.
Most applications will be added to the general subnet set. If they need something different see the above guidance on creating VPCs and subnet sets.
2. Update the OPA policies
Update the policies/networking/expected.rego file to include newly added environments. This is to ensure that none of the subnets get accidentally deleted. Here’s an example of a pull request for this stage.
Note remember to add the full environment names, eg
data-and-insights-wepi-developmentnot just the application name.
3. Create a pull request for the changes in step 1 and 2
This will then kick off core-vpc-<env>-deployment pipelines and run terraform plan, terraform apply and the scripts/member-account-ram-association.sh script for the RAM share.
This will run the RAM share successfully if you are adding environments for an existing application. If it is a new application the RAM share won’t successfully run until the next step.
The pipeline will also generate a PR for networking variables in both the modernisation-platform and modernisation-platform-environments repos. An example can be found here
4. Merge in the two generated PRs from step 3
This will run the RAM share script again (it needs to run in the previous step as if adding an environment the networking files will already be there, it need to run in this step as this is the first time adding the networking files)
If the RAM share script fails to run on the merge for any reason, it will have to be run manually in the relevant application folder here.
Checking its creation
You should be able to see the account or accounts created here
Logging into the account, you should be able to view the subnets, and be displayed with
Inform Customer
When you close the ticket in GitHub, the requester will receive a notification informing them that the requested accounts have been successfully created.