Deleting an environment (AWS account)
Note: This process is cannot be undone. All resources in an AWS account will be deleted.
In the Modernisation Platform, we run a pipeline to create AWS accounts using the aws_organizations_account Terraform resource.
The aws_organizations_account cannot, and does not, delete AWS accounts if removed from the configuration. It attempts to move the AWS account from AWS Organizations to a standalone account, which should fail.
Therefore, there are a few things to do to delete an environment, in this order:
- Get the AWS accounts root IAM user’s email address
- Remove the environment definition from
environments/*.json - Remove the AWS account from Modernisation Platform management
- Delete the
terraform workspacewherever it appears - Delete the actual AWS account
Getting the root IAM user’s email address
You need the root IAM user’s email address to delete the AWS account in the last step, so note it down.
You can get this from the SSO log on page if you have access to the account via SSO, if not it can be found in the Terraform state.
To do this, cd into terraform environments and find the resource in the state:
cd terraform/environmentsterraform state list
To find the email address, run:
terraform state show <resource reference>
$ cd terraform/environments
$ terraform state list
$ terraform state show 'module.environments.aws_organizations_account.accounts["core-vpc-non-live-data"]'
resource "aws_organizations_account" "accounts" {
...
email = "..." <- This will be the email address for the root IAM user
...
tags = {
"application" = "modernisation-platform"
"business-unit" = "Platforms"
"environment-name" = "production"
"is-production" = "true"
"owner" = "Modernisation Platform: modernisation-platform@digital.justice.gov.uk"
}
}
Removing the AWS account from Modernisation Platform management
You need to remove the resource from the Terraform state where it gets created so Terraform no longer has knowledge of it. You don’t need to remove the organisational unit, as Terraform will remove those if they’re not used by anything else.
To do this, cd into terraform environments and find the resource in the state:
cd terraform/environmentsterraform state list
To remove it, run:
terraform state rm <resource reference>
For example, to remove the environment for core-vpc-non-live-data:
$ cd terraform/environments
$ terraform state list
...
module.environments.aws_organizations_account.accounts["core-logging-production"]
module.environments.aws_organizations_account.accounts["core-network-services-production"]
module.environments.aws_organizations_account.accounts["core-sandbox-dev"]
module.environments.aws_organizations_account.accounts["core-security-production"]
module.environments.aws_organizations_account.accounts["core-shared-services-production"]
module.environments.aws_organizations_account.accounts["core-vpc-non-live-data"]
module.environments.aws_organizations_account.accounts["core-vpc-production"]
...
$ terraform state rm 'module.environments.aws_organizations_account.accounts["core-vpc-non-live-data"]'
Removed module.environments.aws_organizations_account.accounts["core-vpc-non-live-data"]
Successfully removed 1 resource instance(s).
Removing the environment definition
To ensure the account isn’t recreated after removing it from the terraform state, remove it from its environments/*.json file.
For example, to remove core-vpc-non-live-data from the core-vpc set of accounts:
{
"environments": [
{
"name": "production",
"access": []
},
{
"name": "non-live-data",
"access": []
}
],
"tags": {
"application": "modernisation-platform",
"business-unit": "Platforms",
"owner": "Modernisation Platform: modernisation-platform@digital.justice.gov.uk"
}
}
should become:
{
"environments": [
{
"name": "production",
"access": []
}
],
"tags": {
"application": "modernisation-platform",
"business-unit": "Platforms",
"owner": "Modernisation Platform: modernisation-platform@digital.justice.gov.uk"
}
}
Remove the accounts from the relevant environments-networking/business-environment.json file. (not required if non member account and not using shared networking)
Update the OPA polices to remove references to the environment.
Before merging in these changes, complete the rest of the steps in this document.
Find and delete the Terraform workspaces for the environment
For the following workspaces, switch to the workspace and run a terraform destroy to ensure any resources such as DNS entries created in shared accounts are deleted and not orphaned.
modernisation-platform-environments/terraform/environments/<application-name> (not required if non member account)
modernisation-platform/terraform/environments/<application-name>
After completing this, you will need to delete the application terraform workspaces in the following locations. Note, you will need to switch to the default workspace before deleting the workspace, see an example command below.
modernisation-platform/terraform/environments/bootstrap/delegate-access/
modernisation-platform/terraform/environments/bootstrap/secure-baselines/
modernisation-platform/terraform/environments/bootstrap/single-sign-on/
modernisation-platform/terraform/environments/bootstrap/member-bootstrap/
modernisation-platform-environments/terraform/environments/<application-name> (not required if non member account)
modernisation-platform/terraform/environments/<application-name>
For example:
terraform workspace select default
terraform workspace delete -force core-vpc-non-live-data
This will not delete the resources that are set up by the Terraform configuration. It will only delete the Terraform reference to the workspace. You will need to delete the AWS account properly.
If you delete the last environment and there are no more environments for the application, you should delete all of the environment files in the following folders:
modernisation-platform/terraform/environments/<application-name>
modernisation-platform-environments/terraform/environments/<application-name>
modernisation-platform-environments/.github/workflows/<application-name>
After following the above steps, you need to move the account to the closed accounts OU before deleting the actual AWS account that the environment was linked to.
Move the account to the root organizational unit
Note that a user with root account permissions will need to do this.
This is to move the account out of an organizational unit where there is an SCP preventing any actions by the root user.
Log into the AWS Console and navigate to AWS Organizations, find the account and move it to the root OU.
Now the AWS account can be deleted.
Delete the actual AWS account
This process cannot be undone. Proceed carefully.
Follow the AWS documentation on closing an AWS account. You will need:
- access to the AWS account’s root email address (not the AWS Organizations root account)
- the ability to read password reset emails
Move the account to the closed accounts organizational unit
Note that a user with root account permissions will need to do this. Please post in #ask-operations-engineering about it, or message the MP teams TA/Lead Webops Engineer.
Log into the AWS Console and navigate to AWS Oraganizations, find the account and move it to the Closed accounts OU.
Merge in your file changes
Merging in your file changes will trigger Terraform to perform the remaining clean up needed.
Delete Github environments
Navigate to https://github.com/ministryofjustice/modernisation-platform-environments/settings/environments and delete the relevant GitHub environments.