Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md).
# Deploying into AWS accounts and VPCs
Using [CodeCatalyst workflows](workflow.md), you can deploy applications and other resources to target AWS accounts and Amazon VPCs in the AWS cloud. To enable these deployments, you must set up CodeCatalyst environments.
A CodeCatalyst *environment*, not to be confused with a [Dev Environment](https://docs.aws.amazon.com/codecatalyst/latest/userguide/devenvironment.html), defines the target AWS account and optional Amazon VPC that a CodeCatalyst [workflow](workflow.md) connects to. An environment also defines the [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) that a workflow needs to access the AWS services and resources within the target account.
You can set up multiple environments and give them names such as development, test, staging, and production. When you deploy into these environments, information about the deployments appears on the CodeCatalyst **Deployment activity** and **Deployment targets** tabs in the environment.
## How do I get started with environments?
The high-level steps to add and use a CodeCatalyst environment are as follows:
1. In your CodeCatalyst space, **connect one or more AWS accounts**. During this process, add the IAM roles that your workflow requires to access resources in your AWS account. For more information, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md).
1. In your CodeCatalyst project, **create an environment** that includes one of the AWS accounts and IAM roles from step 1. For more information, see [Creating an environment](deploy-environments-creating-environment.md).
1. In your CodeCatalyst project, in a workflow, **add an [action](workflows-actions.md) that points to the environment** you created in step 2. For more information, see [Adding an action to a workflow](workflows-add-action.md).
You have now configured an environment. The action can now deploy resources into the AWS account specified in the environment.
**Note**
You can also add an Amazon VPC to the environment. For more information, see [Adding VPC connections for a space](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html) in the *CodeCatalyst Administration Guide* and [Associating a VPC with an environment](deploy-environments-associate-vpc.md).
## Can multiple environments exist within a single workflow?
Yes. If a workflow includes multiple actions, each of those actions can be assigned an environment. For example, you could have a workflow that includes two deploy actions, where one is assigned a `my-staging-enviroment` environment and another is assigned a `my-production-environment` environment.
## Which workflow actions support environments?
Any workflow action that deploys resources into the AWS cloud, or communicates with AWS services for other reasons (such as monitoring and reporting), supports environments.
## Which actions support having their deployment information displayed in CodeCatalyst?
Of the workflow actions that support environments, only a few support having their deployment information displayed on the **Deployment activity** and **Deployment targets** pages of the CodeCatalyst console.
The following workflow actions support having their deployment information displayed:
+ **Deploy CloudFormation stack** – For more information, see [Deploying an CloudFormation stack](deploy-action-cfn.md)
+ **Deploy to Amazon ECS** – For more information, see [Deploying to Amazon ECS with a workflow](deploy-action-ecs.md)
+ **Deploy to Kubernetes cluster** – For more information, see [Deploying to Amazon EKS with a workflow](deploy-action-eks.md)
+ **AWS CDK deploy** – For more information, see [Deploying an AWS CDK app with a workflow](cdk-dep-action.md)
## Supported Regions
The **Environments** page can display resources in any AWS Region.
## Is an environment mandatory?
An environment is mandatory if the workflow action to which it is assigned deploys resources into the AWS cloud, or communicates with AWS services for other reasons (such as monitoring and reporting).
For example, if you have a build action that builds an application but doesn't need to communicate with your AWS account or Amazon VPC, then you do not need to assign an environment to the action. If, however, the build action sends logs to the Amazon CloudWatch service in your AWS account, then the action must have an environment assigned.
**Topics**
+ [
## How do I get started with environments?
](#deploy-environments-get-started)
+ [
## Can multiple environments exist within a single workflow?
](#deploy-environments-multiple)
+ [
## Which workflow actions support environments?
](#deploy-environments-supported)
+ [
## Which actions support having their deployment information displayed in CodeCatalyst?
](#deploy-environments-supported-targets)
+ [
## Supported Regions
](#deploy-environments-supported-regions)
+ [
## Is an environment mandatory?
](#deploy-environments-optional-or-mandatory)
+ [
# Creating an environment
](deploy-environments-creating-environment.md)
+ [
# Associating an environment with an action
](deploy-environments-add-app-to-environment.md)
+ [
# Associating a VPC with an environment
](deploy-environments-associate-vpc.md)
+ [
# Associating an AWS account with an environment
](deploy-environments-associate-account.md)
+ [
# Changing the IAM role of an action
](deploy-environments-switch-role.md)
# Creating an environment
Use the following instructions to create an environment that you can later associate with a workflow action.
**Before you begin**
You need the following:
+ A CodeCatalyst space. For more information, see [Set up and sign in to CodeCatalystSet up and sign in to CodeCatalyst](setting-up-topnode.md).
+ A CodeCatalyst project. For more information, see [Creating a project with a blueprint](projects-create.md#projects-create-console-template).
+ An AWS account connection that includes the IAM roles your workflow action will need to access AWS. For information about creating an account connection, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). You can use a maximum of one account connection per environment.
**Note**
You can create an environment without an account connection; however, you will need to come back and add the connection later.
+ One of the following CodeCatalyst roles:
+ **Space administrator**
+ **Project administrator**
+ **Contributor**
**Note**
If you have the **Contributor role**, you'll be able to create an environment but you won't be able to associate it with an AWS account connection. You'll need to ask someone with the **Space administrator** or **Project administrator** role to associate the environment with an AWS account connection.
For more information about permissions and roles, see [Granting users project permissions](projects-members.md).
**To create an environment**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
1. In the navigation pane, choose **CI/CD**, and then choose **Environments**.
1. In **Environment name**, enter a name, such as **Production** or **Staging**.
1. In **Environment type**, select one of the following:
+ **Non-production** – An environment where you can test your application to make sure it's working as intended before moving it into production.
+ **Production** – A 'live' environment that is publicly-available and hosts your finalized application.
If you choose **Production**, a **Production** badge appears in the UI next to any actions that the environment is associated with. The badge helps you quickly see which actions are deploying to production. Other than the appearance of the badge, there are no differences between production and non-production environments.
1. (Optional) In **Description**, enter a description such as **Production environment for the hello-world app**.
1. In **AWS account connection - optional**, choose the AWS account connection you want to associate with this environment. Workflow actions that are assigned this environment will be able to connect to the associated AWS account. For more information about creating AWS account connections in CodeCatalyst, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md).
If the AWS account connection that you want to use is not listed, it might be because it's not allowed in your project. For more information, see [Configuring project-restricted account connections](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts-restriction.html) in the *Amazon CodeCatalyst Administrator Guide*.
1. In **Default IAM role**, choose the IAM role you want to associate with this environment. Workflow actions that are assigned this environment will inherit this IAM role, and will be able to use it to connect to services and resources in your AWS account.
If you need to assign the environment to multiple actions, and those actions need IAM roles that are different from the default one specified here, then you can specify the different roles on each action's **Configuration** tab, using the **Switch role** option. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).
If the IAM role that you want to use as the default is not listed, it might be because you have not added it to your AWS account connection yet. To add an IAM role to an account connection, see [Adding IAM roles to account connections](ipa-connect-account-addroles.md).
1. (Optional) In **VPC connection**, choose a VPC connection that you want to associate with this environment. For more information about creating VPC connections, see [ Managing Amazon Virtual Private Clouds](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.html) in the *Amazon CodeCatalyst Administrator Guide*.
If the VPC connection that you want to use is not listed, it might be because it includes an AWS account connection that's not allowed in your project. For more information, see [Configuring project-restricted account connections](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts-restriction.html) in the *Amazon CodeCatalyst Administrator Guide*.
1. Choose **Create environment**. CodeCatalyst creates an empty environment.
**Next steps**
+ Now that you have created an environment, you are ready to associate it with a workflow action. For more information, see [Associating an environment with an action](deploy-environments-add-app-to-environment.md).
# Associating an environment with an action
When you associate an environment with a [supported workflow action](deploy-environments.md#deploy-environments-supported), the environment's AWS account, default IAM role, and optional Amazon VPC become assigned to the action. The action can then connect and deploy to the AWS account using the IAM role, and also connect to the optional Amazon VPC.
Use the following instructions to associate an environment with an action.
## Step 1: Associate the environment with a workflow action
Use the following procedure to associate an environment with a workflow action.
------
#### [ Visual ]
**To associate an environment with a workflow action using the visual editor**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.
1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.
1. Choose **Edit**.
1. Choose **Visual**.
1. In the workflow diagram, choose an action that is supported with environments. For more information, see [Which actions support having their deployment information displayed in CodeCatalyst?](deploy-environments.md#deploy-environments-supported-targets).
1. Choose the **Configuration** tab, and specify information in the **Environment** field, as follows.
**Environment**
Specify the CodeCatalyst environment to use with the action. The action connects to the AWS account and optional Amazon VPC specified in the chosen environment. The action uses the default IAM role specified in the environment to connect to the AWS account, and uses the IAM role specified in the [Amazon VPC connection](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html) to connect to the Amazon VPC.
**Note**
If the default IAM role does not have the permissions required by the action, you can configure the action to use a different role. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).
For more information about environments, see [Deploying into AWS accounts and VPCs](deploy-environments.md) and [Creating an environment](deploy-environments-creating-environment.md).
1. (Optional) Change the IAM role associated with the action. You might want to change the role if it contains the wrong set of permissions for the action.
To change the role:
1. In the **What's in *my-environment* ?** box, and choose the vertical ellipsis icon (![\[Ellipsis.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/elipsis.png)).
1. Choose one of the following:
+ **Switch role**. Choose this option to change the IAM role used by this action, and only this action. Other actions continue to use the default IAM role specified in their associated environment. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).
+ **Edit environment**. Choose this option to change the default IAM role listed in your environment. When you choose this option, your action—and any other action associated with the same environment—begins using the new default IAM role.
**Important**
Use caution when updating the default IAM role. Changing the role might lead to action failures if the permissions in the role are not sufficient for all actions that share the environment.
1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.
1. Choose **Commit**, enter a commit message, and choose **Commit** again.
------
#### [ YAML ]
**To associate an environment with a workflow action using the YAML editor**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.
1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.
1. Choose **Edit**.
1. Choose **YAML**.
1. In the workflow action that you want to associate with an environment, add code similar to the following:
```
action-name:
Environment:
Name: environment-name
```
For more information, see the [Action types](workflows-actions.md#workflows-actions-types) topic. This topic has links into the documentation for each action, including its YAML reference.
1. (Optional) If you want the action to use a different role from the default IAM role that's listed in the environment, add a `Connections:` section that includes the role you want to use. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).
1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.
1. Choose **Commit**, enter a commit message, and choose **Commit** again.
------
## Step 2: Populate the deployment activity page
After associating an environment with a workflow action, you can populate the **Deployment activity** and **Deployment target** pages in the **Environments** section of the CodeCatalyst console with deployment information. Use the following instructions to populate these pages.
**Note**
Only a few actions support having their deployment information displayed in the CodeCatalyst console. For more information, see [Which actions support having their deployment information displayed in CodeCatalyst?](deploy-environments.md#deploy-environments-supported-targets).
**To add deployment information to CodeCatalyst**
1. If a workflow run did not start automatically when you committed your changes in [Step 1: Associate the environment with a workflow action](#deploy-environments-add-app-to-environment-assoc), manually start a run as follows:
1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.
1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.
1. Choose **Run**.
The workflow run starts a new deployment, which causes CodeCatalyst to add deployment information to CodeCatalyst.
1. Verify that deployment activity was added to the CodeCatalyst console:
1. In the navigation pane, choose **CI/CD**, and then choose **Environments**.
1. Choose your environment (for example, `Production`).
1. Choose the **Deployment activity** tab, and verify that a deployment appears with a **Status** of **SUCCEEDED**. This indicates that a workflow run successfully deployed your application resources.
1. Choose the **Deployment targets** tab, and verify that your application resources appear.
# Associating a VPC with an environment
When an action is configured with an environment that has a VPC connection, the action will run connected to the VPC, adhering to the network rules and access resources specified by the associated VPC. The same VPC connection can be used by one or more environments.
Use the following instructions to associate a VPC connection with an environment.
**To associate a VPC connection with an environment**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
1. In the navigation pane, choose **CI/CD**, and then choose **Environments**.
1. Choose your environment (for example, `Production`).
1. Choose the **Environment properties** tab.
1. Choose **Manage VPC connection**, choose your desired VPC connection, and choose **Confirm**. This associates your selected VPC connection with this environment.
**Note**
If the VPC connection that you want to use is not listed, it might be because it includes an AWS account connection that's not allowed in your project. For more information, see [Configuring project-restricted account connections](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts-restriction.html) in the *Amazon CodeCatalyst Administrator Guide*.
For more information, see [ Managing Amazon Virtual Private Clouds](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.html) in the *CodeCatalyst Administrator Guide*.
# Associating an AWS account with an environment
Use the following instructions to associate an AWS account with an environment. When you associate an AWS account with an environment, workflow actions that are assigned the environment will be able to connect to the AWS account.
For more information about account connections, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md).
**Before you begin**
You need the following:
+ An AWS account connection that includes the IAM roles your workflow action will need to access AWS. For information about creating an account connection, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). You can use a maximum of one account connection per environment.
+ One of the following CodeCatalyst roles: **Space administrator** or **Project administrator**. For more information, see [Granting users project permissions](projects-members.md).
**To associate an AWS account with an environment**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
1. In the navigation pane, choose **CI/CD**, and then choose **Environments**.
1. Choose your environment (for example, `Production`).
1. Choose **Edit environment**.
1. Under **Environment properties**, in the **AWS account connection - optional** drop-down list, choose your desired AWS account.
If the AWS account connection that you want to use is not listed, it might be because it's not allowed in your project. For more information, see [Configuring project-restricted account connections](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts-restriction.html) in the *Amazon CodeCatalyst Administrator Guide*.
1. In **Default IAM role**, choose the IAM role you want to associate with this environment. Workflow actions that are assigned this environment will inherit this IAM role, and will be able to use it to connect to services and resources in your AWS account.
If the IAM role that you want to use as the default is not listed, it might be because you have not added it to your AWS account connection yet. To add an IAM role to an account connection, see [Adding IAM roles to account connections](ipa-connect-account-addroles.md).
# Changing the IAM role of an action
By default, when you associate an [environment](deploy-environments.md) with a workflow [action](workflows-actions.md), the action inherits the default IAM role specified in the environment. You can change this behavior so that the action uses a different role. You might want an action to use a different role if the default IAM role is missing the permissions that the action needs to operate in the AWS cloud.
To assign a different IAM role to an action, you can use the **Switch role** option in the visual editor or the `Connections:` property in the YAML editor. The new role overrides the default IAM role specified in the environment, allowing you to keep the default IAM role as-is. You might want to keep the default IAM role as-is if there are other actions that use it.
Use the following instructions to configure an action to use a different IAM role from the one specified in its environment.
------
#### [ Visual ]
**To assign a different IAM role to an action (visual editor)**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.
1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.
1. Choose **Edit**.
1. Choose the box that represents the action whose IAM role you want to update.
1. Choose the **Configuration** tab.
1. In the **What's in *my-environment* ?** box, choose the vertical ellipsis icon (![\[Ellipsis.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/elipsis.png)).
1. Choose **Switch role**.
1. In the **Switch role** dialog box, in the **IAM role** drop-down list, choose the IAM role that you want the action to use. This role will override the default IAM role in the environment. If the role you want to use is not in the list, make sure you've added it to your space. For more information, see [Adding IAM roles to account connections](ipa-connect-account-addroles.md).
The chosen role now appears in the **What's in *my-environment*?** box along with a **Defined in workflow** badge. The role also appears in the workflow definition file, in the `Connections:` section.
1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.
1. Choose **Commit**, enter a commit message, and choose **Commit** again.
------
#### [ YAML ]
**To assign a different IAM role to an action (YAML editor)**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.
1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.
1. Choose **Edit**.
1. Choose **YAML**.
1. In the workflow action where you want to use a different IAM role, add a `Connections:` section, similar to the following:
```
action-name:
Environment:
Name: environment-name
Connections:
- Name: account-connection-name
Role: iam-role-name
```
In the preceding code, replace *account-connection-name* with the name of the [account connection](ipa-connect-account.md) that contains the IAM role, and replace *iam-role-name* with the name of the IAM role that you want the action to use. This role will override the default IAM role in the environment. Make sure you've added the role to your space. For more information, see [Adding IAM roles to account connections](ipa-connect-account-addroles.md).
For more information, see the [Action types](workflows-actions.md#workflows-actions-types) topic. This topic has links into the documentation for each action, including its YAML reference.
------