End of support notice: On October 7, 2026, AWS will end support for AWS Proton. After October 7, 2026, you will no longer be able to access the AWS Proton console or AWS Proton resources. Your deployed infrastructure will remain intact. For more information, see [AWS Proton Service Deprecation and Migration Guide](https://docs.aws.amazon.com/proton/latest/userguide/proton-end-of-support.html).
# AWS Proton environments
For AWS Proton, an environment represents the set of shared resources and policies that AWS Proton [services](ag-services.md) are deployed into. They can contain any resources that are expected to be shared across AWS Proton service instances. These resources can include VPCs, clusters, and shared load balancers or API Gateways. An AWS Proton environment must be created before a service can be deployed to it.
This section describes how to manage environments using create, view, update, and delete operations. For >additional information, see the [The AWS Proton Service API Reference](https://docs.aws.amazon.com/proton/latest/APIReference/Welcome.html).
**Topics**
+ [IAM Roles](ag-environment-roles.md)
+ [Create an environment](ag-create-env.md)
+ [View environment data](ag-env-view.md)
+ [Update an environment](ag-env-update.md)
+ [Delete an environment](ag-env-delete.md)
+ [Environment account connections](ag-env-account-connections.md)
+ [Customer-managed environments](ag-env-customer-managed.md)
+ [CodeBuild provisioning role creation](ag-env-codebuild-provisioning-role-creation.md)
# IAM Roles
With AWS Proton, you supply the IAM roles and AWS KMS keys for the AWS resources that you own and manage. These are later applied to and used by resources owned and managed by developers. You create an IAM role to control your developer team's access to the AWS Proton API.
## AWS Proton service role
When you create a new environment, you provide a related IAM service role. The role contains all permissions that are necessary to update all provisioned infrastructure defined in both the environment templates and the service templates. For role examples, see [AWS Proton service role for provisioning using CloudFormation](security_iam_service-role-policy-examples.md#proton-svc-role). If you use environment account connections and environment accounts, you create the role in a selected environment account. For more information, see [Create an environment in one account and provision in another account](ag-create-env.md#ag-create-env-deploy-other) and [Environment account connections](ag-env-account-connections.md).
How you provide this service role, and who assumes the role, depends on your environment's provisioning method.
+ *AWS-managed provisioning* – You provide the role to AWS Proton, either directly while creating an environment, or indirectly through account connections. AWS Proton assumes the role in the relevant account to provision environment and service infrastructure.
+ *Self-managed provisioning* – It's your responsibility to configure your provisioning automation to assume an appropriate role using appropriate credentials when a pull request (PR) triggers a provisioning action. For an example GitHub Action that assumes a role, see [Assuming a Role](https://github.com/aws-actions/configure-aws-credentials#assuming-a-role) in the *"Configure AWS Credentials" Action For GitHub Actions* documentation.
For more information about provisioning methods, see [How AWS Proton provisions infrastructure](ag-works-prov-methods.md).
# Create an environment
Learn to create AWS Proton environments.
**You can create an AWS Proton environment in one of two ways:**
+ Create, manage, and provision a standard environment by using a *standard environment template*. AWS Proton provisions infrastructure for your environment.
+ Connect AWS Proton to customer-managed infrastructure by using a *customer-managed environment template*. You provision your own shared resources outside of AWS Proton, and then you provide provisioning outputs that AWS Proton can use.
**You can choose one of several provisioning approaches when you create an environment.**
+ *AWS managed provisioning* – Create, manage, and provision an environment in a single account. AWS Proton provisions your environment.
This method only supports CloudFormation infrastructure code (IaC) templates.
+ *AWS managed provisioning to another account* – In a single management account, create and manage an environment that's provisioned in another account with environment account connections. AWS Proton provisions your environment in the other account. For more information, see [Create an environment in one account and provision in another account](#ag-create-env-deploy-other) and [Environment account connections](ag-env-account-connections.md).
This method only supports CloudFormation IaC templates.
+ *Self-managed provisioning* – AWS Proton submits provisioning pull requests to a linked repository with your own provisioning infrastructure.
This method only supports Terraform IaC templates.
+ *CodeBuild provisioning* – AWS Proton uses AWS CodeBuild to run shell commands that you provide. Your commands can read inputs that AWS Proton provides, and are responsible for provisioning or deprovisioning infrastructure and generating output values. A template bundle for this method includes your commands in a manifest file and any programs, scripts, or other files that these commands may need.
As an example to using CodeBuild provisioning, you can include code that uses the AWS Cloud Development Kit (AWS CDK) to provision AWS resources, and a manifest that installs the CDK and runs your CDK code.
For more information, see [CodeBuild provisioning template bundle](ag-infrastructure-tmp-files-codebuild.md).
**Note**
You can use CodeBuild provisioning with environments and services. At this time you can't provision components this way.
With AWS managed provisioning (both in the same account and to another account), AWS Proton makes direct calls to provision your resources.
With self-managed provisioning, AWS Proton makes pull requests to provide compiled IaC files that your IaC engine uses to provision resources.
For more information, see [How AWS Proton provisions infrastructure](ag-works-prov-methods.md), [Template bundles](ag-template-authoring.md#ag-template-bundles), and [Schema requirements for environment template bundles](ag-schema.md#schema-req-env).
**Topics**
+ [Create and provision a standard environment in the same account](#ag-create-env-same-account)
+ [Create an environment in one account and provision in another account](#ag-create-env-deploy-other)
+ [Create and provision an environment using self-managed provisioning](#ag-create-env-pull-request)
## Create and provision a standard environment in the same account
Use the console or AWS CLI to create and provision an environment in a single account. Provisioning is managed by AWS.
------
#### [ AWS Management Console ]
**Use the console to create and provision an environment in a single account**
1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Environments**.
1. Choose **Create environment**.
1. In the **Choose an environment template** page, select a template and choose **Configure**.
1. In the **Configure environment** page, in the **Provisioning** section, choose **AWS managed provisioning**.
1. In the **Deployment account** section, choose **This AWS account**.
1. In the **Configure environment** page, in the **Environment settings** section, enter an **Environment name**.
1. (Optional) Enter a description for the environment.
1. In the **Environment roles** section, select the AWS Proton service role that you created as part of [Setting up AWS Proton service roles](ag-setting-up-iam.md#setting-up-cicd).
1. (Optional) In the **Component role** section, select a service role that enables directly defined components to run in the environment and scopes down the resources that they can provision. For more information, see [AWS Proton components](ag-components.md).
1. (Optional) In the **Tags** section, choose **Add new tag** and enter a key and value to create a customer managed tag.
1. Choose **Next**.
1. In the **Configure environment custom settings** page, you must enter values for the `required` parameters. You can enter values for the `optional` parameters or use the defaults when given.
1. Choose **Next** and review your inputs.
1. Choose **Create**.
View the environment details and status, as well as the AWS managed tags and customer managed tags for your environment.
1. In the navigation pane, choose **Environments**.
A new page displays a list of your environments along with the status and other environment details.
------
#### [ AWS CLI ]
**Use the AWS CLI to create and provision an environment in a single account.**
To create an environment, you specify the [AWS Proton service role](security_iam_service-role-policy-examples.md#proton-svc-role) ARN, path to your spec file, environment name, environment template ARN, the major and minor versions, and description (optional).
The next examples shows a YAML formatted spec file that specifies values for two inputs that are defined in the environment template schema file. You can use the `get-environment-template-minor-version` command to view the environment template schema.
```
proton: EnvironmentSpec
spec:
my_sample_input: "the first"
my_other_sample_input: "the second"
```
Create an environment by running the following command.
```
$ aws proton create-environment \
--name "MySimpleEnv" \
--template-name simple-env \
--template-major-version 1 \
--proton-service-role-arn "arn:aws:iam::123456789012:role/AWSProtonServiceRole" \
--spec "file://env-spec.yaml"
```
Response:
```
{
"environment": {
"arn": "arn:aws:proton:region-id:123456789012:environment/MySimpleEnv",
"createdAt": "2020-11-11T23:03:05.405000+00:00",
"deploymentStatus": "IN_PROGRESS",
"lastDeploymentAttemptedAt": "2020-11-11T23:03:05.405000+00:00",
"name": "MySimpleEnv",
"protonServiceRoleArn": "arn:aws:iam::123456789012:role/ProtonServiceRole",
"templateName": "simple-env"
}
}
```
After you create a new environment, you can view a list of AWS and customer managed tags as shown in the following example command. AWS Proton automatically generates AWS managed tags for you. You can also modify and create customer managed tags using the AWS CLI. For more information, see [AWS Proton resources and tagging](resources.md).
Command:
```
$ aws proton list-tags-for-resource \
--resource-arn "arn:aws:proton:region-id:123456789012:environment/MySimpleEnv"
```
------
## Create an environment in one account and provision in another account
Use the console or AWS CLI to create a standard environment in a management account that provisions environment infrastructure in another account. Provisioning is managed by AWS.
**Before using the console or CLI, complete the following steps.**
1. Identify the AWS account IDs for the management and environment account, and copy them for later use.
1. In the environment account, create an AWS Proton service role with minimum permissions for the environment to create. For more information, see [AWS Proton service role for provisioning using CloudFormation](security_iam_service-role-policy-examples.md#proton-svc-role).
------
#### [ AWS Management Console ]
**Use the console create an environment in one account and provision in another.**
1.
**In the environment account, create an environment account connection, and use it to send a request to connect to the management account.**
1. In [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Environment account connections** in the navigation pane.
1. In the **Environment account connections** page, choose **Request to connect**.
**Note**
Verify that the account ID that's listed in the **Environment account connection** page heading matches your pre-identified environment account ID.
1. In the **Request to connect** page, in the **Environment role** section, select **Existing service role** and the name of the service role that you created for the environment.
1. In the **Connect to management account** section, enter the **Management account ID** and an **Environment name** for your AWS Proton environment. Copy the name for later use.
1. Choose **Request to connect** at the lower right corner of the page.
1. Your request shows as pending in the **Environment connections sent to a management account** table and a modal shows how to accept the request from the management account.
1.
**In the management account, accept a request to connect from the environment account.**
1. Log in to your management account and choose **Environment account connections** in the AWS Proton console.
1. In the **Environment account connections** page, in the **Environment account connection requests** table, select the environment account connection with the environment account ID that matches your pre-identified environment account ID.
**Note**
Verify that the account ID that's listed in the **Environment account connection** page heading matches your pre-identified management account ID.
1. Choose **Accept**. The status changes from PENDING to CONNECTED.
1.
**In the management account, create an environment.**
1. In the navigation pane, choose **Environment templates**.
1. In the **Environment templates** page, choose **Create environment template**.
1. In the **Choose an environment template** page, choose an environment template.
1. In the **Configure environment** page, in the **Provisioning** section, choose **AWS managed provisioning**.
1. In the **Deployment account** section, choose **Another AWS account;**.
1. In the **Environment details** section, select your **Environment account connection** and **Environment name**.
1. Choose **Next**.
1. Fill out the forms and choose **Next** until you reach the **Review and Create** page.
1. Review and choose **Create environment**.
------
#### [ AWS CLI ]
**Use the AWS CLI to create an environment in one account and provision in another.**
In the environment account, create an environment account connection and request to connect by running the following command.
```
$ aws proton create-environment-account-connection \
--environment-name "simple-env-connected" \
--role-arn "arn:aws:iam::222222222222:role/service-role/env-account-proton-service-role" \
--management-account-id "111111111111"
```
Response:
```
{
"environmentAccountConnection": {
"arn": "arn:aws:proton:region-id:222222222222:environment-account-connection/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"environmentAccountId": "222222222222",
"environmentName": "simple-env-connected",
"id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"lastModifiedAt": "2021-04-28T23:13:50.847000+00:00",
"managementAccountId": "111111111111",
"requestedAt": "2021-04-28T23:13:50.847000+00:00",
"roleArn": "arn:aws:iam::222222222222:role/service-role/env-account-proton-service-role",
"status": "PENDING"
}
}
```
In the management account, accept the environment account connection request by running the following command.
```
$ aws proton accept-environment-account-connection \
--id "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
```
Response:
```
{
"environmentAccountConnection": {
"arn": "arn:aws:proton:region-id:222222222222:environment-account-connection/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"environmentAccountId": "222222222222",
"environmentName": "simple-env-connected",
"id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"lastModifiedAt": "2021-04-28T23:15:33.486000+00:00",
"managementAccountId": "111111111111",
"requestedAt": "2021-04-28T23:13:50.847000+00:00",
"roleArn": "arn:aws:iam::222222222222:role/service-role/env-account-proton-service-role",
"status": "CONNECTED"
}
}
```
View your environment account connection by running the following command.
```
$ aws proton get-environment-account-connection \
--id "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
```
Response:
```
{
"environmentAccountConnection": {
"arn": "arn:aws:proton:region-id:222222222222:environment-account-connection/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"environmentAccountId": "222222222222",
"environmentName": "simple-env-connected",
"id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"lastModifiedAt": "2021-04-28T23:15:33.486000+00:00",
"managementAccountId": "111111111111",
"requestedAt": "2021-04-28T23:13:50.847000+00:00",
"roleArn": "arn:aws:iam::222222222222:role/service-role/env-account-proton-service-role",
"status": "CONNECTED"
}
}
```
In the management account, create an environment by running the following command.
```
$ aws proton create-environment \
--name "simple-env-connected" \
--template-name simple-env-template \
--template-major-version "1" \
--template-minor-version "1" \
--spec "file://simple-env-template/specs/original.yaml" \
--environment-account-connection-id "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
```
Response:
```
{
"environment": {
"arn": "arn:aws:proton:region-id:111111111111:environment/simple-env-connected",
"createdAt": "2021-04-28T23:02:57.944000+00:00",
"deploymentStatus": "IN_PROGRESS",
"environmentAccountConnectionId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"environmentAccountId": "222222222222",
"lastDeploymentAttemptedAt": "2021-04-28T23:02:57.944000+00:00",
"name": "simple-env-connected",
"templateName": "simple-env-template"
}
}
```
------
## Create and provision an environment using self-managed provisioning
When you use self-managed provisioning, AWS Proton submits provisioning pull requests to a linked repository with your own provisioning infrastructure. The pull requests start your own workflow, which calls AWS services; to provision infrastructure.
**Self-managed provisioning considerations:**
+ Before you create an environment, set up a repository resource directory for self-managed provisioning. For more information, see [AWS Proton infrastructure as code files](ag-infrastructure-tmp-files.md).
+ After you create the environment, AWS Proton waits to receive asynchronous notifications regarding the status of your infrastructure provisioning. Your provisioning code must use the AWS Proton `NotifyResourceStateChange` API to send these asynchronous notifications to AWS Proton.
You can use self-managed provisioning in the console or with the AWS CLI. The following examples show how you can use self-managed provisioning with Terraform.
------
#### [ AWS Management Console ]
**Use the console to create a Terraform environment using self-managed provisioning.**
1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Environments**.
1. Choose **Create environment**.
1. In the **Choose an environment template** page, select a Terraform template and choose **Configure**.
1. In the **Configure environment** page, in the **Provisioning** section, choose **Self-managed provisioning**.
1. In the **Provisioning repository details** section:
1. If you haven't yet [linked your provisioning repository to AWS Proton](ag-create-repo.md), choose **New repository**, choose one of the repository providers, and then, for **CodeStar connection**, choose one of your connections.
**Note**
If you don't yet have a connection to the relevant repository provider account, choose **Add a new CodeStar connection**. Then, create a connection, and then choose the refresh button next to the **CodeStar connection** menu. You should now be able to choose your new connection in the menu.
If you've already linked your repository to AWS Proton, choose **Existing repository**.
1. For **Repository name**, choose a repository. The drop-down menu shows linked repositories for **Existing repository** or the list of repositories in the provider account for **New repository**.
1. For **Branch name**, choose one of the repository branches.
1. In the **Environment settings** section, enter an **Environment name**.
1. (Optional) Enter a description for the environment.
1. (Optional) In the **Tags** section, choose **Add new tag** and enter a key and value to create a customer managed tag.
1. Choose **Next**.
1. In the **Configure environment custom settings** page, you must enter values for the `required` parameters. You can enter values for the `optional` parameters or use the defaults when given.
1. Choose **Next** and review your inputs.
1. Choose **Create** to send a pull request.
+ If you approve the pull request, the deployment is in progress.
+ If you reject the pull request, the environment creation is cancelled.
+ If the pull request times out, environment creation *isn't* complete.
1. View the environment details and status, as well as the AWS managed tags and customer managed tags for your environment.
1. In the navigation pane, choose **Environments**.
A new page displays a list of your environments along with the status and other environment details.
------
#### [ AWS CLI ]
When you create an environment using self-managed provisioning, you *add* the `provisioningRepository` parameter and omit the `ProtonServiceRoleArn` and `environmentAccountConnectionId` parameters.
**Use the AWS CLI to create a Terraform environment with self-managed provisioning.**
1. Create an environment and send a pull request to the repository for review and approval.
The next examples shows a YAML formatted spec file that defines the values for two inputs based on the environment template schema file. You can use the `get-environment-template-minor-version` command to view the environment template schema.
Spec:
```
proton: EnvironmentSpec
spec:
ssm_parameter_value: "test"
```
Create an environment by running the following command.
```
$ aws proton create-environment \
--name "pr-environment" \
--template-name "pr-env-template" \
--template-major-version "1" \
--provisioning-repository="branch=main,name=myrepos/env-repo,provider=GITHUB" \
--spec "file://env-spec.yaml"
```
Response:>
```
{
"environment": {
"arn": "arn:aws:proton:region-id:123456789012:environment/pr-environment",
"createdAt": "2021-11-18T17:06:58.679000+00:00",
"deploymentStatus": "IN_PROGRESS",
"lastDeploymentAttemptedAt": "2021-11-18T17:06:58.679000+00:00",
"name": "pr-environment",
"provisioningRepository": {
"arn": "arn:aws:proton:region-id:123456789012:repository/github:myrepos/env-repo",
"branch": "main",
"name": "myrepos/env-repo",
"provider": "GITHUB"
},
"templateName": "pr-env-template"
}
```
1. Review the request.
+ If you approve the request, provisioning is in progress.
+ If you reject the request, the environment creation is cancelled.
+ If the pull request times out, environment creation *isn't* complete.
1. Asynchronously provide provisioning status to AWS Proton. The following example notifies AWS Proton of a successful provisioning.
```
$ aws proton notify-resource-deployment-status-change \
--resource-arn "arn:aws:proton:region-id:123456789012:environment/pr-environment" \
--status "SUCCEEDED"
```
------
# View environment data
You can view environment detail data using either the AWS Proton console or the AWS CLI.
------
#### [ AWS Management Console ]
**You can view lists of environments with details and individual environments with detail data by using the [AWS Proton console](https://console.aws.amazon.com//proton/).**
1. To view a list of your environments, choose **Environments** in the navigation pane.
1. To view detail data, choose the name of an environment.
View your environment detail data.
------
#### [ AWS CLI ]
**Use the AWS CLI *get* or *list* environment details.**
Run the following command:
```
$ aws proton get-environment \
--name "MySimpleEnv"
```
Response:
```
{
"environment": {
"arn": "arn:aws:proton:region-id:123456789012:environment/MySimpleEnv",
"createdAt": "2020-11-11T23:03:05.405000+00:00",
"deploymentStatus": "SUCCEEDED",
"lastDeploymentAttemptedAt": "2020-11-11T23:03:05.405000+00:00",
"lastDeploymentSucceededAt": "2020-11-11T23:03:05.405000+00:00",
"name": "MySimpleEnv",
"protonServiceRoleArn": "arn:aws:iam::123456789012:role/ProtonServiceRole",
"spec": "proton: EnvironmentSpec\nspec:\n my_sample_input: \"the first\"\n my_other_sample_input: \"the second\"\n",
"templateMajorVersion": "1",
"templateMinorVersion": "0",
"templateName": "simple-env"
}
}
```
------
# Update an environment
If the AWS Proton environment is associated with an environment account connection, *don't* update or include the `protonServiceRoleArn` parameter to update or connect to an environment account connection.
You can only update to a new environment account connection if both of the following is true:
+ The environment account connection was created in the same environment account that the current environment account connection was created in.
+ >The environment account connection is associated with the current environment.
If the environment *isn’t* associated with an environment account connection, *don’t* update or include the `environmentAccountConnectionId` parameter.
You can update either the `environmentAccountConnectionId` or `protonServiceRoleArn` parameter and value. You can’t update both.
If your environment uses self-managed provisioning, *don't* update the `provisioning-repository` parameter and *omit* the `environmentAccountConnectionId` and `protonServiceRoleArn` parameters.
There are four modes for updating an environment as described in the following list. When using the AWS CLI, the `deployment-type` field defines the mode. When using the console, these modes map to the **Edit**, **Update**, **Update minor**, and **Update major** actions that drop down from **Actions**.
`NONE`
In this mode, a deployment *doesn't* occur. Only the requested metadata parameters are updated.
`CURRENT_VERSION`
In this mode, the environment is deployed and updated with the new spec that you provide. Only requested parameters are updated. *Don’t* include minor or major version parameters when you use this `deployment-type`.
`MINOR_VERSION`
In this mode, the environment is deployed and updated with the published, recommended (latest) minor version of the current major version in use by default. You can also specify a different minor version of the current major version in use.
`MAJOR_VERSION`
In this mode, the environment is deployed and updated with the published, recommended (latest) major and minor version of the current template by default. You can also specify a different major version that is higher than the major version in use and a minor version (optional).
**Topics**
+ [Update an AWS managed provisioning environment](#ag-env-std-update)
+ [Update a self-managed provisioning environment](#ag-env-pr-update)
+ [Cancel an environment deployment in progress](#ag-env-cancel)
## Update an AWS managed provisioning environment
Standard provisioning is only supported by environments that provision with CloudFormation.
**Use the console or AWS CLI to update your environment.**
------
#### [ AWS Management Console ]
**Update an environment using the console as shown in the following steps.**
1.
**Choose 1 of the following 2 steps.**
1.
**In the list of environments.**
1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Environments**.
1. In the list of environments, choose the radio button to the left of the environment that you want to update.
1.
****In the console environment detail page.****
1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Environments**.
1. In the list of environments, choose the name of the environment that you want to update.
1.
**Choose 1 of the next 4 steps to update your environment.**
1.
**To make an edit that doesn't require environment deployment.**
1. For example, to change a description.
Choose **Edit**.
1. Fill out the form and choose **Next**.
1. Review your edit and choose **Update**.
1.
**To make updates to metadata inputs only.**
1. Choose **Actions** and then **Update**.
1. Fill out the form and choose **Edit**.
1. Fill out the forms and choose **Next** until you reach the **Review** page.
1. Review your updates and choose **Update**.
1.
**To make an update to a new minor version of its environment template.**
1. Choose **Actions** and then **Update minor**.
1. Fill out the form and choose **Next**.
1. Fill out the forms and choose **Next** until you reach the **Review** page.
1. Review your updates and choose **Update**.
1.
**To make an update to a new major version of its environment template.**
1. Choose **Actions** and then **Update major**.
1. Fill out the form and choose **Next**.
1. Fill out the forms and choose **Next** until you reach the **Review** page.
1. Review your updates and choose **Update**.
------
#### [ AWS CLI ]
**Use the AWS Proton AWS CLI to update an environment to a new minor version.**
Run the following command to update your environment:
```
$ aws proton update-environment \
--name "MySimpleEnv" \
--deployment-type "MINOR_VERSION" \
--template-major-version "1" \
--template-minor-version "1" \
--proton-service-role-arn arn:aws:iam::123456789012:role/service-role/ProtonServiceRole \
--spec "file:///spec.yaml"
```
Response:
```
{
"environment": {
"arn": "arn:aws:proton:region-id:123456789012:environment/MySimpleEnv",
"createdAt": "2021-04-02T17:29:55.472000+00:00",
"deploymentStatus": "IN_PROGRESS",
"lastDeploymentAttemptedAt": "2021-04-02T17:48:26.307000+00:00",
"lastDeploymentSucceededAt": "2021-04-02T17:29:55.472000+00:00",
"name": "MySimpleEnv",
"protonServiceRoleArn": "arn:aws:iam::123456789012:role/service-role/ProtonServiceRole",
"templateMajorVersion": "1",
"templateMinorVersion": "0",
"templateName": "simple-env"
}
}
```
Run the following command to get and confirm the status:
```
$ aws proton get-environment \
--name "MySimpleEnv"
```
Response:
```
{
"environment": {
"arn": "arn:aws:proton:region-id:123456789012:environment/MySimpleEnv",
"createdAt": "2021-04-02T17:29:55.472000+00:00",
"deploymentStatus": "SUCCEEDED",
"environmentName": "MySimpleEnv",
"lastDeploymentAttemptedAt": "2021-04-02T17:48:26.307000+00:00",
"lastDeploymentSucceededAt": "2021-04-02T17:48:26.307000+00:00",
"protonServiceRoleArn": "arn:aws:iam::123456789012:role/service-role/ProtonServiceRole",
"spec": "proton: EnvironmentSpec\n\nspec:\n my_sample_input: hello\n my_other_sample_input: everybody\n",
"templateMajorVersion": "1",
"templateMinorVersion": "1",
"templateName": "simple-env"
}
}
```
------
## Update a self-managed provisioning environment
Self-managed provisioning is only supported by environments that provision with Terraform.
**Use the console or AWS CLI to update your environment.**
------
#### [ AWS Management Console ]
**Update an environment using the console as shown in the following steps.**
1.
**Choose 1 of the following 2 steps.**
1.
**In the list of environments.**
1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Environments**.
1. In the list of environments, choose the radio button to the left of the environment template that you want to update.
1.
****In the console environment detail page.****
1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Environments**.
1. In the list of environments, choose the name of the environment that you want to update.
1.
**Choose 1 of the next 4 steps to update your environment.**
1.
**To make an edit that doesn't require environment deployment.**
1. For example, to change a description.
Choose **Edit**.
1. Fill out the form and choose **Next**.
1. Review your edit and choose **Update**.
1.
**To make updates to metadata inputs only.**
1. Choose **Actions** and then **Update**.
1. Fill out the form and choose **Edit**.
1. Fill out the forms and choose **Next** until you reach the **Review** page.
1. Review your updates and choose **Update**.
1.
**To make an update to a new minor version of its environment template.**
1. Choose **Actions** and then **Update minor**.
1. Fill out the form and choose **Next**.
1. Fill out the forms and choose **Next** until you reach the **Review** page.
1. Review your updates and choose **Update**.
1.
**To make an update to a new major version of its environment template.**
1. Choose **Actions** and then **Update major**.
1. Fill out the form and choose **Next**.
1. Fill out the forms and choose **Next** until you reach the **Review** page.
1. Review your updates and choose **Update**.
------
#### [ AWS CLI ]
**Use the AWS CLI to update a Terraform environment to a new minor version with self-managed provisioning.**
1. Run the following command to update your environment:
```
$ aws proton update-environment \
--name "pr-environment" \
--deployment-type "MINOR_VERSION" \
--template-major-version "1" \
--template-minor-version "1" \
--provisioning-repository "branch=main,name=myrepos/env-repo,provider=GITHUB" \
--spec "file://env-spec-mod.yaml"
```
Response:
```
{
"environment": {
"arn": "arn:aws:proton:region-id:123456789012:environment/pr-environment",
"createdAt": "2021-11-18T21:09:15.745000+00:00",
"deploymentStatus": "IN_PROGRESS",
"lastDeploymentAttemptedAt": "2021-11-18T21:25:41.998000+00:00",
"lastDeploymentSucceededAt": "2021-11-18T21:09:15.745000+00:00",
"name": "pr-environment",
"provisioningRepository": {
"arn": "arn:aws:proton:region-id:123456789012:repository/github:myrepos/env-repo",
"branch": "main",
"name": "myrepos/env-repo",
"provider": "GITHUB"
},
"templateMajorVersion": "1",
"templateMinorVersion": "0",
"templateName": "pr-env-template"
}
}
```
1. Run the following command to get and confirm the status:
```
$ aws proton get-environment \
--name "pr-environment"
```
Response:
```
{
"environment": {
"arn": "arn:aws:proton:region-id:123456789012:environment/pr-environment",
"createdAt": "2021-11-18T21:09:15.745000+00:00",
"deploymentStatus": "SUCCEEDED",
"lastDeploymentAttemptedAt": "2021-11-18T21:25:41.998000+00:00",
"lastDeploymentSucceededAt": "2021-11-18T21:25:41.998000+00:00",
"name": "pr-environment",
"provisioningRepository": {
"arn": "arn:aws:proton:region-id:123456789012:repository/github:myrepos/env-repo",
"branch": "main",
"name": "myrepos/env-repo",
"provider": "GITHUB"
},
"spec": "proton: EnvironmentSpec\nspec:\n ssm_parameter_value: \"test\"\n ssm_another_parameter_value: \"update\"\n",
"templateMajorVersion": "1",
"templateMinorVersion": "1",
"templateName": "pr-env-template"
}
}
```
1. Review the pull request that was sent by AWS Proton.
+ If you approve the request, provisioning is in progress.
+ If you reject the request, the environment creation is cancelled.
+ If the pull request times out, environment creation isn't complete.
1. Provide provisioning status to AWS Proton.
```
$ aws proton notify-resource-deployment-status-change \
--resource-arn "arn:aws:proton:region-id:123456789012:environment/pr-environment" \
--status "SUCCEEDED"
```
------
## Cancel an environment deployment in progress
You can attempt to cancel an environment update deployment if the `deploymentStatus` is in `IN_PROGRESS`. AWS Proton attempts to cancel the deployment. Successful cancellation *isn’t* guaranteed.
When you cancel an update deployment, AWS Proton attempts to cancel the deployment as listed in the following steps.
**With AWS-managed provisioning, AWS Proton does the following:**
+ Sets the deployment state to `CANCELLING`.
+ Stops the deployment in progress and deletes any new resources that were created by the deployment when `IN_PROGRESS`.
+ Sets the deployment state to `CANCELLED`.
+ Reverts the state of the resource to what it was before the deployment was started.
**With self-managed provisioning, AWS Proton does the following:**
+ Attempts to close the pull request to prevent merging the changes to your repository.
+ Sets the deployment state to `CANCELLED` if the pull request was successfully closed.
For instructions on how to cancel an environment deployment, see [CancelEnvironmentDeployment](https://docs.aws.amazon.com/proton/latest/APIReference/API_CancelEnvironmentDeployment.html) in the *AWS Proton API Reference*.
You can use the console or CLI to cancel environments that are in progress.
------
#### [ AWS Management Console ]
**Use the console to cancel an environment update deployment as shown in the following steps.**
1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Environments** in the navigation pane.
1. In the list of environments, choose the name of the environment with the deployment update that you want to cancel.
1. If your update deployment status is **In progress**, in the environment detail page, choose **Actions** and then **Cancel deployment**.
1. A modal prompts you to confirm that you want to cancel. Choose **Cancel deployment**.
1. Your update deployment status is set to **Cancelling** and then **Cancelled** to complete the cancellation.
------
#### [ AWS CLI ]
**Use the AWS Proton AWS CLI to cancel an IN\$1PROGRESS environment update deployment to a new minor version 2.**
A wait condition is included in the template used for this example so that the cancellation starts before the update deployment succeeds.
Run the following command to cancel the update:
```
$ aws proton cancel-environment-deployment \
--environment-name "MySimpleEnv"
```
Response:
```
{
"environment": {
"arn": "arn:aws:proton:region-id:123456789012:environment/MySimpleEnv",
"createdAt": "2021-04-02T17:29:55.472000+00:00",
"deploymentStatus": "CANCELLING",
"lastDeploymentAttemptedAt": "2021-04-02T18:15:10.243000+00:00",
"lastDeploymentSucceededAt": "2021-04-02T17:48:26.307000+00:00",
"name": "MySimpleEnv",
"protonServiceRoleArn": "arn:aws:iam::123456789012:role/service-role/ProtonServiceRole",
"spec": "proton: EnvironmentSpec\n\nspec:\n my_sample_input: hello\n my_other_sample_input: everybody\n",
"templateMajorVersion": "1",
"templateMinorVersion": "1",
"templateName": "simple-env"
}
}
```
Run the following command to get and confirm the status:"
```
$ aws proton get-environment \
--name "MySimpleEnv"
```
Response:
```
{
"environment": {
"arn": "arn:aws:proton:region-id:123456789012:environment/MySimpleEnv",
"createdAt": "2021-04-02T17:29:55.472000+00:00",
"deploymentStatus": "CANCELLED",
"deploymentStatusMessage": "User initiated cancellation.",
"lastDeploymentAttemptedAt": "2021-04-02T18:15:10.243000+00:00",
"lastDeploymentSucceededAt": "2021-04-02T17:48:26.307000+00:00",
"name": "MySimpleEnv",
"protonServiceRoleArn": "arn:aws:iam::123456789012:role/service-role/ProtonServiceRole",
"spec": "proton: EnvironmentSpec\n\nspec:\n my_sample_input: hello\n my_other_sample_input: everybody\n",
"templateMajorVersion": "1",
"templateMinorVersion": "1",
"templateName": "simple-env"
}
}
```
------
# Delete an environment
You can delete an AWS Proton environment by using the AWS Proton console or the AWS CLI.
**Note**
You can't delete an environment that has any associated component. To delete such an environment, you should first delete all components that are running in the environment. For more information about components, see [AWS Proton components](ag-components.md).
------
#### [ AWS Management Console ]
**Delete an environment using the console as described in the following two options.**
**In the list of environments.**
1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Environments**.
1. In the list of environments, select the radio button to the left of the environment that you want to delete.
1. Choose **Actions** and then **Delete**.
1. A modal prompts you to confirm the delete action.
1. Follow the instructions and choose **Yes, delete**.
**In the environment detail page.**
1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Environments**.
1. In the list of environments, choose the name of the environment that you want to delete.
1. In the environment detail page, choose **Actions** and then **Delete**.
1. A modal prompts you to confirm that you want to delete.
1. Follow the instructions and choose **Yes, delete**.
------
#### [ AWS CLI ]
**Use the AWS CLI to delete an environment.**
*Don't* delete an environment if services or service instances are deployed to the environment.
Run the following command:
```
$ aws proton delete-environment \
--name "MySimpleEnv"
```
Response:
```
{
"environment": {
"arn": "arn:aws:proton:region-id:123456789012:environment/MySimpleEnv",
"createdAt": "2021-04-02T17:29:55.472000+00:00",
"deploymentStatus": "DELETE_IN_PROGRESS",
"lastDeploymentAttemptedAt": "2021-04-02T17:48:26.307000+00:00",
"lastDeploymentSucceededAt": "2021-04-02T17:48:26.307000+00:00",
"name": "MySimpleEnv",
"protonServiceRoleArn": "arn:aws:iam::123456789012:role/ProtonServiceRole",
"templateMajorVersion": "1",
"templateMinorVersion": "1",
"templateName": "simple-env"
}
}
```
------
# Environment account connections
**Overview**
Learn how to create and manage an AWS Proton environment in one account and provision its infrastructure resources in another account. This can help improve visibility and efficiency at scale. Environment account connections only support standard provisioning with CloudFormation infrastructure as code.
**Note**
The information in this topic is relevant to environments that are configured with *AWS managed provisioning*. With environments configured with *self-managed provisioning*, AWS Proton doesn't directly provision your infrastructure. Instead, it sends pull requests (PRs) to your repository for provisioning. It's your responsibility to ensure that your automation code assumes the right identity and role.
For more information about provisioning methods, see [How AWS Proton provisions infrastructure](ag-works-prov-methods.md).
**Terminology**
![\[A diagram that describes AWS Proton resources within a single account (management account) that's in a single AWS Region. It also shows how AWS Proton environments in that account can use environment account connections to deploy to other accounts (environment accounts) in the same Region.\]](http://docs.aws.amazon.com/proton/latest/userguide/images/xaccount-diagram.png)
With AWS Proton *environment account connections*, you can create an AWS Proton environment from one account and provision its infrastructure in another account.
Management account
The single account where you, as an administrator, create an AWS Proton environment that provisions infrastructure resources in another *environment account*.
Environment account
An account that environment infrastructure is provisioned in, when you create an AWS Proton environment in another account.
Environment account connection
A secure bi-directional connection between a *management account* and an *environment account*. It maintains authorization and permissions as described further in the following sections.
When you create an environment account connection in an environment account in a specific Region, only the management accounts in the same Region can see and use the environment account connection. This means that the AWS Proton environment created in the management account and the environment infrastructure provisioned in the environment account must be in the same Region.
**Environment account connection considerations**
+ You need an environment account connection for each environment that you want to provision in an environment account.
+ For information about environment account connection quotas, see [AWS Proton quotas](ag-limits.md).
**Tagging**
In the environment account, use the console or the AWS CLI to view and manage environment account connection customer managed tags. AWS managed tags *aren't* generated for environment account connections. For more information, see [AWS Proton resources and tagging](resources.md).
## Create an environment in one account and provision its infrastructure in another account
To create and provision an environment from a single management account, set up an environment account for an environment that you plan to create.
**Start in the environment account and create connection.**
In the environment account, create an AWS Proton service role that's scoped down to only the permissions that are needed for provisioning your environment infrastructure resources. For more information, see [AWS Proton service role for provisioning using CloudFormation](security_iam_service-role-policy-examples.md#proton-svc-role).
Then, create and send an environment account connection request to your management account. When the request is accepted, AWS Proton can use the associated IAM role that permits environment resource provisioning in the associated environment account.
**In the management account, accept or reject the environment account connection.**
In the management account, accept or reject the environment account connection request. You *can’t* delete an environment account connection from your management account.
If you accept the request, the AWS Proton can use the associated IAM role that permits resource provisioning in the associated environment account.
The environment infrastructure resources are provisioned in the associated environment account. You can only use AWS Proton APIs to access and manage your environment and its infrastructure resources, from your management account. For more information, see [Create an environment in one account and provision in another account](ag-create-env.md#ag-create-env-deploy-other) and [Update an environment](ag-env-update.md).
After you reject a request, you *can’t* accept or use the rejected environment account connection.
**Note**
You *can’t* reject an environment account connection that's connected to an environment. To reject the environment account connection, you must first delete the associated environment.
**In the environment account, access the provisioned infrastructure resources.**
In the environment account, you can view and access the provisioned infrastructure resources. For example, you can use CloudFormation API actions to monitor and clean up stacks if needed. You can’t use the AWS Proton API actions to access or manage the AWS Proton environment that was used to provision the infrastructure resources.
In the environment account, you can delete environment account connections that you have created in the environment account. You *can’t* accept or reject them. If you delete an environment account connection that’s in use by an AWS Proton environment, AWS Proton won't be able to manage the environment infrastructure resources until a new environment connection is accepted for the environment account and named environment. You're responsible for cleaning up provisioned resources that remain without an environment connection.
## Use the console or CLI to manage environment account connections
You can use the console or CLI to create and manage environment account connections.
------
#### [ AWS Management Console ]
**Use the console to create an environment account connection and send a request to the management account as shown in the next steps.**
1. Decide on a name for the environment that you plan to create in your management account or choose the name of an existing environment that requires an environment account connection.
1. In an environment account, in the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Environment account connections** in the navigation pane.
1. In the **Environment account connections** page, choose **Request to connect**.
**Note**
Verify the account ID that's listed in the **Environment account connection** page heading. Make sure that it matches the account ID of the environment account that you want your named environment to provision in.
1. In the **Request to connect** page:
1. In the **Connect to management account** section, enter the **Management account ID** and the **Environment name** that you entered in step 1.
1. In the **Environment role** section, choose **New service role** and AWS Proton automatically creates a new role for you. Or, select **Existing service role** and the name of the service role that you created previously.
**Note**
The role that AWS Proton automatically creates for you has broad permissions. We recommend that you scope down the role to the permissions required to provision your environment infrastructure resources. For more information, see [AWS Proton service role for provisioning using CloudFormation](security_iam_service-role-policy-examples.md#proton-svc-role).
1. (Optional) In the **Tags** section, choose **Add new tag** to create a customer managed tag for your environment account connection.
1. Choose **Request to connect**.
1. Your request shows as pending in the **Environment connections sent to a management account** table and a modal lets you know how to accept the request from the management account.
**Accept or reject an environment account connection request.**
1. In a management account, in the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Environment account connections** in the navigation pane.
1. In the **Environment account connections** page, in the **Environment account connection requests** table, choose the environment connection request to accept or reject.
**Note**
Verify the account ID that's listed in the **Environment account connection** page heading. Make sure that it matches the account ID of the management account that's associated with the environment account connection to reject. After you reject this environment account connection, you *can’t* accept or use the rejected environment account connection.
1. Choose **Reject** or **Accept**.
+ If you selected **Reject**, the status changes from *pending* to *rejected*.
+ If you selected **Accept**, the status changes from *pending* to *connected*.
**Delete an environment account connection.**
1. In an environment account, in the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Environment account connections** in the navigation pane.
**Note**
Verify the account ID that's listed in the **Environment account connection** page heading. Make sure that it matches the account ID of the management account that's associated with the environment account connection to reject. After you delete this environment account connection, AWS Proton *can’t* manage the environment infrastructure resources in the environment account. It can only manage it after a new environment account connection for the environment account and named environment is accepted by the management account.
1. In the **Environment account connections** page, in the **Sent requests to connect to management account** section, choose **Delete**.
1. A modal prompts you to confirm that you want to delete. Choose **Delete**.
------
#### [ AWS CLI ]
Decide on a name for the environment that you plan to create in your management account or choose the name of an existing environment that requires an environment account connection.
**Create an environment account connection in an environment account.**
Run the following command:
```
$ aws proton create-environment-account-connection \
--environment-name "simple-env-connected" \
--role-arn "arn:aws:iam::222222222222:role/service-role/env-account-proton-service-role" \
--management-account-id "111111111111"
```
Response:
```
{
"environmentAccountConnection": {
"arn": "arn:aws:proton:region-id:222222222222:environment-account-connection/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"environmentAccountId": "222222222222",
"environmentName": "simple-env-connected",
"id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"lastModifiedAt": "2021-04-28T23:13:50.847000+00:00",
"managementAccountId": "111111111111",
"requestedAt": "2021-04-28T23:13:50.847000+00:00",
"roleArn": "arn:aws:iam::222222222222:role/service-role/env-account-proton-service-role",
"status": "PENDING"
}
}
```
**Accept or reject an environment account connection in a management account as shown in the following command and response.**
**Note**
If you reject this environment account connection, you won't be able to accept or use the rejected environment account connection.
If you specify **Reject**, the status changes from *pending* to *rejected*.
If you specify **Accept**, the status changes from *pending* to *connected*.
Run the following command to accept the environment account connection:
```
$ aws proton accept-environment-account-connection \
--id "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
```
Response:
```
{
"environmentAccountConnection": {
"arn": "arn:aws:proton:region-id:222222222222:environment-account-connection/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"environmentAccountId": "222222222222",
"environmentName": "simple-env-connected",
"id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"lastModifiedAt": "2021-04-28T23:15:33.486000+00:00",
"managementAccountId": "111111111111",
"requestedAt": "2021-04-28T23:13:50.847000+00:00",
"roleArn": "arn:aws:iam::222222222222:role/service-role/env-account-proton-service-role",
"status": "CONNECTED"
}
}
```
Run the following command to reject the environment account connection:
```
$ aws proton reject-environment-account-connection \
--id "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
```
Response:
```
{
"environmentAccountConnection": {
"arn": "arn:aws:proton:us-east-1:222222222222:environment-account-connection/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"status": "REJECTED",
"environmentAccountId": "222222222222",
"environmentName": "simple-env-reject",
"id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"lastModifiedAt": "2021-04-28T23:13:50.847000+00:00",
"managementAccountId": "111111111111",
"requestedAt": "2021-04-28T23:13:50.847000+00:00",
"roleArn": "arn:aws:iam::222222222222:role/service-role/env-account-proton-service-role"
}
}
```
**View an environment account's connections. You can *get* or *list* environment account connections**.
Run the following get command:
```
$ aws proton get-environment-account-connection \
--id "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
```
Response:
```
{
"environmentAccountConnection": {
"arn": "arn:aws:proton:region-id:222222222222:environment-account-connection/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"environmentAccountId": "222222222222",
"environmentName": "simple-env-connected",
"id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"lastModifiedAt": "2021-04-28T23:15:33.486000+00:00",
"managementAccountId": "111111111111",
"requestedAt": "2021-04-28T23:13:50.847000+00:00",
"roleArn": "arn:aws:iam::222222222222:role/service-role/env-account-proton-service-role",
"status": "CONNECTED"
}
}
```
**Delete an environment account connection in an environment account.**
**Note**
If you delete this environment account connection, AWS Proton won't be able to manage the environment infrastructure resources in the environment account until a new environment connection has been accepted for the environment account and named environment. You're responsible for cleaning up provisioned resources that remain without an environment connection.
Run the following command:
```
$ aws proton delete-environment-account-connection \
--id "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
```
Response:
```
{
"environmentAccountConnection": {
"arn": "arn:aws:proton:us-east-1:222222222222:environment-account-connection/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"environmentAccountId": "222222222222",
"environmentName": "simple-env-connected",
"id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"lastModifiedAt": "2021-04-28T23:13:50.847000+00:00",
"managementAccountId": "111111111111",
"requestedAt": "2021-04-28T23:13:50.847000+00:00",
"roleArn": "arn:aws:iam::222222222222:role/service-role/env-account-proton-service-role",
"status": "CONNECTED"
}
}
```
------
# Customer-managed environments
With customer-managed environments, you can use existing infrastructure, like a VPC, that you already have deployed as your AWS Proton environment. While using customer-managed environments, you can provision your own shared resources outside of AWS Proton. However, you can still allow AWS Proton to consume relevant provisioning outputs as inputs for AWS Proton services when they are deployed. If the outputs can change, AWS Proton is able to accept updates. AWS Proton is unable to change the environment directly, though, since the provisioning is managed outside of AWS Proton.
After the environment is created, you're responsible for providing the same outputs to AWS Proton that would have been created if AWS Proton had made the environment, such as Amazon ECS cluster names or Amazon VPC IDs.
With this functionality, you can deploy and update AWS Proton service resources from an AWS Proton service template to this environment. However, the environment itself isn't modified through template updates in AWS Proton. You're responsible for executing updates to the environment and updating those outputs in AWS Proton.
You can have multiple environments in a single account that are a mix of AWS Proton managed and customer-managed environments. You can also link a second account and use an AWS Proton template in the primary account to execute deployments and updates to environments and services in that second, linked account.
## How to use customer-managed environments
The first thing administrators need to do is register an imported, customer-managed environment template. Don't supply manifests or infrastructure files in the template bundle. Only supply the schema.
The schema below outlines a list of outputs using the open API format and replicates the outputs from an CloudFormation template.
**Important**
Only string inputs are allowed for the outputs.
The following example is a snippet of the output sections of an CloudFormation template for a corresponding Fargate template.
```
Outputs:
ClusterName:
Description: The name of the ECS cluster
Value: !Ref 'ECSCluster'
ECSTaskExecutionRole:
Description: The ARN of the ECS role
Value: !GetAtt 'ECSTaskExecutionRole.Arn'
VpcId:
Description: The ID of the VPC that this stack is deployed in
Value: !Ref 'VPC'
[...]
```
The schema for the corresponding AWS Proton imported environment is similar to the following. Don't supply default values in the schema.
```
schema:
format:
openapi: "3.0.0"
environment_input_type: "EnvironmentOutput"
types:
EnvironmentOutput:
type: object
description: "Outputs of the environment"
properties:
ClusterName:
type: string
description: "The name of the ECS cluster"
ECSTaskExecutionRole:
type: string
description: "The ARN of the ECS role"
VpcId:
type: string
description: "The ID of the VPC that this stack is deployed in"
[...]
```
At the time of registering the template, you indicate that this template is imported and provides the Amazon S3 bucket location for the bundle. AWS Proton validates that the schema only contains `environment_input_type` and no CloudFormation template parameters before putting the template in draft.
You provide the following to create an imported environment.
+ An IAM role to use when making deployments.
+ A specification with the values for the required outputs.
You can provide both of these through either the console or the AWS CLI using a process similar to the deployment of a regular environment.
# CodeBuild provisioning role creation
Infrastructure as a Code (IaaC) tools like CloudFormation and Terraform require permissions for the many different types of AWS resources. For example, if an IaaC template declares an Amazon S3 bucket, it needs permissions to create, read, update, and delete Amazon S3 buckets. It's considered a security best practice to limit roles to the minimal permissions required. Given the breadth of AWS resources, it’s challenging to create least-privilege policies for IaaC templates, especially when the resources being managed by those templates can change later. For example, in your latest edits to a template being managed by AWS Proton, you add an RDS database resource.
Configuring the right permissions helps make deployments of your IaC smooth. AWS Proton CodeBuild Provisioning executes arbitrary customer-supplied CLI commands in a CodeBuild project located in the customer’s account. Typically, these commands create and delete infrastructure using an Infrastructure as Code (IaaC) tool such as AWS CDK. When an AWS resource deploys whose template uses CodeBuild Provisioning, AWS will start a build in a CodeBuild project managed by AWS. A role is passed to CodeBuild, which CodeBuild assumes to execute commands. This role, called the CodeBuild Provisioning Role, is provided by the customer and contains permissions required to provision infrastructure. It's meant to be assumed only by CodeBuild and even AWS Proton can't assume it.
**Creating the role**
The CodeBuild Provisioning role can be created in the IAM console or in the AWS CLI. To create it in the AWS CLI:
```
aws iam create-role --role-name AWSProtonCodeBuildProvisioning --assume-role-policy-document '{"Version": "2012-10-17", "Statement":[{"Effect":"Allow","Principal":{"Service":"codebuild.amazonaws.com"},"Action":"sts:AssumeRole"}]}'
aws iam attach-role-policy --role-name AWSProtonCodeBuildProvisioning --policy-arn arn:aws:iam::aws:policy/AWSProtonCodeBuildProvisioningBasicAccess
```
This also attaches the `AWSProtonCodeBuildProvisioningBasicAccess`, which contains the minimal permissions needed by the CodeBuild service to run a build.
If you prefer to use the console, please ensure the following when you create the role:
1. For trusted entity, select AWS service and then select CodeBuild.
1. In the Add permissions step, select `AWSProtonCodeBuildProvisioningBasicAccess` and any other policies you want to attach.
**Administrator Access**
If you attach the `AdministratorAccess` policy to the CodeBuild Provisioning Role, it will guarantee that any IaaC template won't fail due to lack of permissions. It also means that anyone who can create an Environment Template or Service Template can perform administrator-level actions, even if that user isn't an administrator. AWS Proton doesn't recommend using `AdministatorAccess` with the CodeBuild Provisioning Role. If you decide to use `AdministratorAccess` with the CodeBuild Provisioning Role, do so in a sandbox environment.
You can create a role with `AdministratorAccess` in the IAM console or by executing this command:
```
aws iam create-role --role-name AWSProtonCodeBuildProvisioning --assume-role-policy-document '{"Version": "2012-10-17", "Statement":[{"Effect":"Allow","Principal":{"Service":"codebuild.amazonaws.com"},"Action":"sts:AssumeRole"}]}'
aws iam attach-role-policy --role-name AWSProtonCodeBuildProvisioning --policy-arn arn:aws:iam::aws:policy/AdministratorAccess
```
**Creating a Minimally-Scoped Role**
If you want to create a role with minimum permissions, there are multiple approaches:
+ Deploy with admin permissions, then scope down the role. We recommend using [IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/what-is-access-analyzer.html).
+ Use managed policies to give access to the services you plan on using.
**AWS CDK**
If you're using AWS CDK with AWS Proton, and you’ve run `cdk bootstrap` on each environment account/Region, then there already exists a role for `cdk deploy`. In this case, attach the following policy to the CodeBuild Provisioning Role:
```
{
"Action": "sts:AssumeRole",
"Resource": [
"arn:aws:iam::account-id:role/cdk-*-deploy-role-*",
"arn:aws:iam::account-id:role/cdk-*-file-publishing-role-*"
],
"Effect": "Allow"
}
```
**Custom VPC**
If you decide to run CodeBuild in a [custom VPC](https://docs.aws.amazon.com/proton/latest/userguide/vpc-codebuild-custom-support.html), you’ll need the following permissions in your CodeBuild role:
```
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface"
],
"Resource": [
"arn:aws:ec2:region:account-id:network-interface/*",
"arn:aws:ec2:region:account-id:subnet/*",
"arn:aws:ec2:region:account-id:security-group/*"
]
},
{
"Effect": "Allow",
"Action": [
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:region:account-id:*/*"
]
},
{
"Effect": "Allow",
"Action": [
"ec2:DescribeDhcpOptions",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeSubnets",
"ec2:DescribeSecurityGroups",
"ec2:DescribeVpcs"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:region:account-id:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:AuthorizedService": "codebuild.amazonaws.com"
}
}
}
```
You could also use the `[AmazonEC2FullAccess](https://us-east-1.console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AmazonEC2FullAccess)` managed policy, although that includes permissions that you may not need. To attach the managed policy using the CLI:
```
aws iam create-role --role-name AWSProtonCodeBuildProvisioning --assume-role-policy-document '{"Version": "2012-10-17", "Statement":[{"Effect":"Allow","Principal":{"Service":"codebuild.amazonaws.com"},"Action":"sts:AssumeRole"}]}'
aws iam attach-role-policy --role-name AWSProtonCodeBuildProvisioning --policy-arn arn:aws:iam::aws:policy/AdministratorAccess
```