# Working with instances for CodeDeploy
CodeDeploy supports deployments to instances running Amazon Linux, Ubuntu Server, Red Hat Enterprise Linux (RHEL), and Windows Server.
You can use CodeDeploy to deploy to both Amazon EC2 instances and on-premises instances. An on-premises instance is any physical device that is not an Amazon EC2 instance that can run the CodeDeploy agent and connect to public AWS service endpoints. You can use CodeDeploy to simultaneously deploy an application to Amazon EC2 instances in the cloud and to desktop PCs in your office or servers in your own data center.
## Comparing Amazon EC2 instances to on-premises instances
The following table compares Amazon EC2 instances and on-premises instances:
| **Subject** | **Amazon EC2 instances** | **On-premises instances** |
| --- | --- | --- |
| Requires you to install and run a version of the CodeDeploy agent that's compatible with the operating system running on the instance. | Yes | Yes |
| Requires the instance to be able to connect to CodeDeploy. | Yes | Yes |
| Requires an IAM instance profile to be attached to the instance. The IAM instance profile must have permissions to participate in CodeDeploy deployments. For information, see [Step 4: Create an IAM instance profile for your Amazon EC2 instances](getting-started-create-iam-instance-profile.md). | Yes | No |
| Requires you to do one of the following to authenticate and register instances: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/instances.html) | No | Yes |
| Requires you to register each instance with CodeDeploy before you can deploy to it. | No | Yes |
| Requires you to tag each instance before CodeDeploy can deploy to it. | Yes | Yes |
| Can participate in Amazon EC2 Auto Scaling and Elastic Load Balancing scenarios as part of CodeDeploy deployments. | Yes | No |
| Can be deployed from Amazon S3 buckets and GitHub repositories. | Yes | Yes |
| Can support triggers that prompt the sending of SMS or email notifications when specified events occur in deployments or instances. | Yes | Yes |
| Is subject to being billed for associated deployments. | No | Yes |
## Instance tasks for CodeDeploy
To launch or configure instances for use in deployments, choose from the following instructions:
| | |
| --- |--- |
| I want to launch a new Amazon Linux or Windows Server Amazon EC2 instance. | To launch the Amazon EC2 instance with the least amount of effort, see [Create an Amazon EC2 instance for CodeDeploy (CloudFormation template)](instances-ec2-create-cloudformation-template.md). To launch the Amazon EC2 instance mostly on your own, see [Create an Amazon EC2 instance for CodeDeploy (AWS CLI or Amazon EC2 console)](instances-ec2-create.md). |
| I want to launch a new Ubuntu Server or RHEL Amazon EC2 instance. | See [Create an Amazon EC2 instance for CodeDeploy (AWS CLI or Amazon EC2 console)](instances-ec2-create.md). |
| I want to configure an Amazon Linux, Windows Server, Ubuntu Server, or RHEL Amazon EC2 instance. | See [Configure an Amazon EC2 instance to work with CodeDeploy](instances-ec2-configure.md). |
| I want to configure a Windows Server, Ubuntu Server, or RHEL on-premises instance (physical devices that are not Amazon EC2 instances). | See [Working with on-premises instances for CodeDeploy](instances-on-premises.md). |
| I want CodeDeploy to provision a replacement fleet of instances during a blue/green deployment. | See [Working with deployments in CodeDeploy](deployments.md). |
To prepare Amazon EC2 instances in Amazon EC2 Auto Scaling groups, you must follow some additional steps. For more information, see [Integrating CodeDeploy with Amazon EC2 Auto Scaling](integrations-aws-auto-scaling.md).
**Topics**
+ [Tagging Instances for Deployments](instances-tagging.md)
+ [Working with Amazon EC2 Instances](instances-ec2.md)
+ [Working with On-Premises Instances](instances-on-premises.md)
+ [View Instance Details](instances-view-details.md)
+ [Instance Health](instances-health.md)
# Tagging instances for deployment groups in CodeDeploy
To help manage your Amazon EC2 instances and on-premises instances, you can use tags to assign your own metadata to each resource. Tags enable you to categorize your instances in different ways (for example, by purpose, owner, or environment). This is useful when you have many instances. You can quickly identify an instance or group of instances based on the tags you've assigned to them. Each tag consists of a key and an optional value, both of which you define. For more information, see [Tagging your Amazon EC2 resources](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html).
To specify which instances are included in a CodeDeploy deployment group, you specify tags in one or more *tag groups*. Instances that meet your tag criteria are the ones that the latest application revision is installed on when a deployment to that deployment group is created.
**Note**
You can also include Amazon EC2 Auto Scaling groups in deployment groups, but they are identified by their names rather than by tags applied to instances. For information, see [Integrating CodeDeploy with Amazon EC2 Auto Scaling](integrations-aws-auto-scaling.md).
The criteria for instances in a deployment group can be as simple as a single tag in a single tag group. It can be as complex as 10 tags each in a maximum of three tag groups.
If you use a single tag group, any instance identified by at least one tag in the group is included in the deployment group. If you use multiple tag groups, only instances that are identified by at least one tag in *each* of the tag groups are included.
The following examples illustrate how tags and tag groups can be used to select the instances for a deployment group.
**Topics**
+ [Example 1: Single tag group, single tag](#instances-tagging-example-1)
+ [Example 2: Single tag group, multiple tags](#instances-tagging-example-2)
+ [Example 3: Multiple tag groups, single tags](#instances-tagging-example-3)
+ [Example 4: Multiple tag groups, multiple tags](#instances-tagging-example-4)
## Example 1: Single tag group, single tag
You can specify a single tag in a single tag group:
**Tag group 1**
| Key | Value |
| --- | --- |
| Name | AppVersion-ABC |
Each instance that is tagged with `Name=AppVersion-ABC` is part of the deployment group, even if it has other tags applied.
CodeDeploy console setup view:
![\[The CodeDeploy console showing one tag group with one tag.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/TaggingExample1-polaris.png)
JSON structure:
```
"ec2TagSet": {
"ec2TagSetList": [
[
{
"Type": "KEY_AND_VALUE",
"Key": "Name",
"Value": "AppVersion-ABC"
}
]
]
},
```
## Example 2: Single tag group, multiple tags
You can also specify multiple tags in a single tag group:
**Tag group 1**
| Key | Value |
| --- | --- |
| Region | North |
| Region | South |
| Region | East |
An instance that is tagged with any of these three tags is part of the deployment group, even if it has other tags applied. If, for example, you had other instances tagged with `Region=West`, they would not be included in the deployment group.
CodeDeploy console setup view:
![\[The CodeDeploy console showing one tag group with three tags.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/TaggingExample2-polaris.png)
JSON structure:
```
"ec2TagSet": {
"ec2TagSetList": [
[
{
"Type": "KEY_AND_VALUE",
"Key": "Region",
"Value": "North"
},
{
"Type": "KEY_AND_VALUE",
"Key": "Region",
"Value": "South"
},
{
"Type": "KEY_AND_VALUE",
"Key": "Region",
"Value": "East"
}
]
]
},
```
## Example 3: Multiple tag groups, single tags
You can also use multiple sets of tag groups with a single key-value pair in each to specify the criteria for instances in a deployment group. When you use multiple tag groups in a deployment group, only instances that are identified by all the tag groups are included in the deployment group.
**Tag group 1**
| Key | Value |
| --- | --- |
| Name | AppVersion-ABC |
**Tag group 2**
| Key | Value |
| --- | --- |
| Region | North |
**Tag group 3**
| Key | Value |
| --- | --- |
| Type | t2.medium |
You might have instances in many regions and of various instance types tagged with `Name=AppVersion-ABC`. In this example, only the instances also tagged with `Region=North` and `Type=t2.medium` are part of the deployment group.
CodeDeploy console setup view:
![\[The CodeDeploy console showing three tag groups with one tag in each.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/TaggingExample3-polaris.png)
JSON structure:
```
"ec2TagSet": {
"ec2TagSetList": [
[
{
"Type": "KEY_AND_VALUE",
"Key": "Name",
"Value": "AppVersion-ABC"
}
],
[
{
"Type": "KEY_AND_VALUE",
"Key": "Region",
"Value": "North"
}
],
[
{
"Type": "KEY_AND_VALUE",
"Key": "Type",
"Value": "t2.medium"
}
],
]
},
```
## Example 4: Multiple tag groups, multiple tags
When you use multiple tag groups with multiple tags in one or more group, an instance must match at least one of the tags in each of the groups.
**Tag group 1**
| Key | Value |
| --- | --- |
| Environment | Beta |
| Environment | Staging |
**Tag group 2**
| Key | Value |
| --- | --- |
| Region | North |
| Region | South |
| Region | East |
**Tag group 3**
| Key | Value |
| --- | --- |
| Type | t2.medium |
| Type | t2.large |
In this example, to be included in the deployment group, an instance must be tagged with (1) `Environment=Beta` or `Environment=Staging`, with (2) `Region=North`, `Region=South`, or `Region=East`, and with (3) `Type=t2.medium` or `Type=t2.large`.
To illustrate, instances with the following tag groups *would* be among those included in the deployment group:
+ `Environment=Beta`, `Region=North`,`Type=t2.medium`
+ `Environment=Staging`,`Region=East`,`Type=t2.large`
+ `Environment=Staging`,`Region=South`,`Type=t2.large`
Instances with the following tag groups would *not* be included in the deployment group. The **highlighted** key values cause the instances to be excluded:
+ `Environment=Beta`, Region=**West**,`Type=t2.medium`
+ `Environment=Staging`,`Region=East`,Type=**t2.micro**
+ Environment=**Production**,`Region=South`,`Type=t2.large`
CodeDeploy console setup view:
![\[The CodeDeploy console showing three tag groups with multiple tags in each.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/TaggingExample4-polaris.png)
JSON structure:
```
"ec2TagSet": {
"ec2TagSetList": [
[
{
"Type": "KEY_AND_VALUE",
"Key": "Environment",
"Value": "Beta"
},
{
"Type": "KEY_AND_VALUE",
"Key": "Environment",
"Value": "Staging"
}
],
[
{
"Type": "KEY_AND_VALUE",
"Key": "Region",
"Value": "North"
},
{
"Type": "KEY_AND_VALUE",
"Key": "Region",
"Value": "South"
},
{
"Type": "KEY_AND_VALUE",
"Key": "Region",
"Value": "East"
}
],
[
{
"Type": "KEY_AND_VALUE",
"Key": "Type",
"Value": "t2.medium"
},
{
"Type": "KEY_AND_VALUE",
"Key": "Type",
"Value": "t2.large"
}
],
]
},
```
# Working with Amazon EC2 instances for CodeDeploy
An Amazon EC2 instance is a virtual computing environment that you create and configure using Amazon Elastic Compute Cloud. Amazon EC2 provides scalable computing capacity in the AWS Cloud. You can use Amazon EC2 to launch as many or as few virtual servers as you need for your CodeDeploy deployments.
For more information about Amazon EC2, see [https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/).
The instructions in this section show you how to create and configure Amazon EC2 instances for use in your CodeDeploy deployments.
**Topics**
+ [Create an Amazon EC2 instance for CodeDeploy](instances-ec2-create.md)
+ [Create an Amazon EC2 instance (CloudFormation template)](instances-ec2-create-cloudformation-template.md)
+ [Configure an Amazon EC2 instance](instances-ec2-configure.md)
# Create an Amazon EC2 instance for CodeDeploy (AWS CLI or Amazon EC2 console)
These instructions show you how to launch a new Amazon EC2 instance that is configured for use in CodeDeploy deployments.
You can use our CloudFormation template to launch an Amazon EC2 instance running Amazon Linux or Windows Server that is already configured for use in CodeDeploy deployments. We do not provide an CloudFormation template for Amazon EC2 instances running Ubuntu Server or Red Hat Enterprise Linux (RHEL). For alternatives to the use of the template, see [Working with instances for CodeDeploy](instances.md).
You can use the Amazon EC2 console, AWS CLI, or Amazon EC2 APIs to launch an Amazon EC2 instance.
## Launch an Amazon EC2 instance (console)
### Prerequisites
If you have not done so already, follow the instructions in [Getting started with CodeDeploy](getting-started-codedeploy.md) to set up and configure the AWS CLI and create an IAM instance profile.
### Launch an Amazon EC2 instance
1. Sign in to the AWS Management Console and open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**, and then choose **Launch Instance**.
1. On the **Step 1: Choose an Amazon Machine Image (AMI)** page, from the **Quick Start** tab, locate the operating system and version you want to use, and then choose **Select**. You must choose an Amazon EC2 AMI operating systems supported by CodeDeploy. For more information, see [Operating systems supported by the CodeDeploy agent](codedeploy-agent.md#codedeploy-agent-supported-operating-systems).
1. On the **Step 2: Choose an Instance Type** page, choose any available Amazon EC2 instance type, and then choose **Next: Configure Instance Details**.
1. On the **Step 3: Configure Instance Details** page, in the **IAM role** list, choose the IAM instance role you created in [Step 4: Create an IAM instance profile for your Amazon EC2 instances](getting-started-create-iam-instance-profile.md). If you used the suggested role name, then choose **CodeDeployDemo-EC2-Instance-Profile**. If you created your own role name, choose that.
**Note**
If a default virtual private cloud (VPC) is not displayed in the **Network** list, you must choose or create an Amazon VPC and subnet. Choose **Create new VPC** or **Create new subnet** or both. For more information, see [Your VPC and subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html).
1. Choose **Next: Add Storage**.
1. Leave the **Step 4: Add Storage** page unchanged, and choose **Next: Add Tags**.
1. On the **Step 5: Add Tags** page, choose **Add Tag**.
1. In the **Key** box, type **Name**. In the **Value** box type **CodeDeployDemo**.
**Important**
The contents of the **Key** and **Value** boxes are case-sensitive.
1. Choose **Next: Configure Security Group**.
1. On the **Step 6: Configure Security Group** page, leave the **Create a new security group** option selected.
A default SSH role is configured for Amazon EC2 instances running Amazon Linux, Ubuntu Server, or RHEL. A default RDP role is configured for Amazon EC2 instances running Windows Server.
1. If you want to open the HTTP port, choose the **Add Rule** button, and from the **Type** drop-down list, choose **HTTP**. Accept the default **Source** value of **Custom 0.0.0.0/0**, and then choose **Review and Launch**.
**Note**
In a production environment, we recommend restricting access to the SSH, RDP, and HTTP ports, instead of specifying **Anywhere 0.0.0.0/0**. CodeDeploy does not require unrestricted port access and does not require HTTP access. For more information, see [Tips for securing your Amazon EC2 instance](https://aws.amazon.com/articles/1233).
If a **Boot from General Purpose (SSD)** dialog box appears, follow the instructions, and then choose **Next**.
1. Leave the **Step 7: Review Instance Launch** page unchanged, and choose **Launch**.
1. In the **Select an existing key pair or create a new key pair** dialog box, choose either **Choose an existing key pair** or **Create a new key pair**. If you've already configured an Amazon EC2 instance key pair, you can choose it here.
If you don't already have an Amazon EC2 instance key pair, choose **Create a new key pair** and give it a recognizable name. Choose **Download Key Pair** to download the Amazon EC2 instance key pair to your computer.
**Important**
You must have a key pair if you want to access your Amazon EC2 instance with SSH or RDP.
1. Choose **Launch Instances**.
1. Choose the ID for your Amazon EC2 instance. Do not continue until the instance has been launched and passed all checks.
### Install the CodeDeploy agent
The CodeDeploy agent must be installed on your Amazon EC2 instance before using it in CodeDeploy deployments. For more information, see [Install the CodeDeploy agent](codedeploy-agent-operations-install.md).
**Note**
You can configure automatic installation and updates of the CodeDeploy agent when you create your deployment group in the console.
## Launch an Amazon EC2 instance (CLI)
### Prerequisites
If you have not done so already, follow the instructions in [Getting started with CodeDeploy](getting-started-codedeploy.md) to set up and configure the AWS CLI and create an IAM instance profile.
### Launch an Amazon EC2 instance
1. **For Windows Server only** If you are creating an Amazon EC2 instance running Windows Server, call the **create-security-group** and **authorize-security-group-ingress** commands to create a security group that allows RDP access (which is not allowed by default) and, alternatively, HTTP access. For example, to create a security group named *CodeDeployDemo-Windows-Security-Group*, run the following commands, one at a time:
```
aws ec2 create-security-group --group-name CodeDeployDemo-Windows-Security-Group --description "For launching Windows Server images for use with CodeDeploy"
```
```
aws ec2 authorize-security-group-ingress --group-name CodeDeployDemo-Windows-Security-Group --to-port 3389 --ip-protocol tcp --cidr-ip 0.0.0.0/0 --from-port 3389
```
```
aws ec2 authorize-security-group-ingress --group-name CodeDeployDemo-Windows-Security-Group --to-port 80 --ip-protocol tcp --cidr-ip 0.0.0.0/0 --from-port 80
```
**Note**
For demonstration purposes, these commands create a security group that allows unrestricted access for RDP through port 3389 and, alternatively, HTTP through port 80. As a best practice, we recommend restricting access to the RDP and HTTP ports. CodeDeploy does not require unrestricted port access and does not require HTTP access. For more information, see [Tips for securing your Amazon EC2 instance](https://aws.amazon.com/articles/1233).
1. Call the **run-instances** command to create and launch the Amazon EC2 instance.
Before you call this command, you need to collect the following:
+ The ID of an Amazon Machine Image (AMI) (*ami-id*) you use for the instance. To get the ID, see [Finding a suitable AMI](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/finding-an-ami.html).
+ The name of the type of Amazon EC2 instance (*instance-type*) you create, such as `t1.micro`. For a list, see [Amazon EC2 instance types](https://aws.amazon.com/ec2/instance-types/).
+ The name of an IAM instance profile with permission to access the Amazon S3 bucket where the CodeDeploy agent installation files for your region are stored.
For information about creating an IAM instance profile, see [Step 4: Create an IAM instance profile for your Amazon EC2 instances](getting-started-create-iam-instance-profile.md).
+ The name of an Amazon EC2 instance key pair (*key-name*) to enable SSH access to an Amazon EC2 instance running Amazon Linux, Ubuntu Server, or RHEL or RDP access to an Amazon EC2 instance running Windows Server.
**Important**
Type the key pair name only, not the key pair file extension. For example, *my-keypair*, not *my-keypair.pem*.
To find a key pair name, open the Amazon EC2 console at [https://console.aws.amazon.com/ec2](https://console.aws.amazon.com/ec2). In the navigation pane, under **Network & Security**, choose **Key Pairs**, and note the key pair name in the list.
To generate a key pair, see [Creating your key pair using Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#having-ec2-create-your-key-pair). Be sure you create the key pair in one of the regions listed in [Region and endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#codedeploy_region) in *AWS General Reference*. Otherwise, you won't be able to use the Amazon EC2 instance key pair with CodeDeploy.
**For Amazon Linux, RHEL, and Ubuntu Server**
To call the **run-instances** command to launch an Amazon EC2 instance running Amazon Linux, Ubuntu Server, or RHEL and attach the IAM instance profile you created in [Step 4: Create an IAM instance profile for your Amazon EC2 instances](getting-started-create-iam-instance-profile.md). For example:
```
aws ec2 run-instances \
--image-id ami-id \
--key-name key-name \
--count 1 \
--instance-type instance-type \
--iam-instance-profile Name=iam-instance-profile
```
**Note**
This command creates a default security group for the Amazon EC2 instance that allows access to several ports, including unrestricted access for SSH through port 22 and, alternatively, HTTP through port 80. As a best practice, we recommend restricting access to the SSH and HTTP ports only. CodeDeploy does not require unrestricted port access and does not require HTTP port access. For more information, see [Tips for securing your Amazon EC2 instance](https://aws.amazon.com/articles/1233).
**For Windows Server**
To call the **run-instances** command to launch an Amazon EC2 instance running Windows Server and attach the IAM instance profile you created in [Step 4: Create an IAM instance profile for your Amazon EC2 instances](getting-started-create-iam-instance-profile.md), and specify the name of the security group you created in Step 1. For example:
```
aws ec2 run-instances --image-id ami-id --key-name key-name --count 1 --instance-type instance-type --iam-instance-profile Name=iam-instance-profile --security-groups CodeDeploy-Windows-Security-Group
```
These commands launch a single Amazon EC2 instance with the specified AMI, key pair, and instance type, with the specified IAM instance profile, and run the specified script during launch.
1. Note the value of the `InstanceID` in the output. If you forget this value, you can get it later by calling the **describe-instances** command against the Amazon EC2 instance key pair.
```
aws ec2 describe-instances --filters "Name=key-name,Values=keyName" --query "Reservations[*].Instances[*].[InstanceId]" --output text
```
Use the instance ID to call the **create-tags** command, which tags the Amazon EC2 instance so that CodeDeploy can find it later during a deployment. In the following example, the tag is named **CodeDeployDemo**, but you can specify any Amazon EC2 instance tag you want.
```
aws ec2 create-tags --resources instance-id --tags Key=Name,Value=CodeDeployDemo
```
You can apply multiple tags to an instance at the same time. For example:
```
aws ec2 create-tags --resources instance-id --tags Key=Name,Value=testInstance Key=Region,Value=West Key=Environment,Value=Beta
```
To verify the Amazon EC2 instance has been launched and passed all checks, use the instance ID to call the **describe-instance-status** command.
```
aws ec2 describe-instance-status --instance-ids instance-id --query "InstanceStatuses[*].InstanceStatus.[Status]" --output text
```
If the instance has been launched and passed all checks, `ok` appears in the output.
### Install the CodeDeploy agent
The CodeDeploy agent must be installed on your Amazon EC2 instance before using it in CodeDeploy deployments. For more information, see [Install the CodeDeploy agent](codedeploy-agent-operations-install.md).
**Note**
You can configure automatic installation and updates of the CodeDeploy agent when you create your deployment group in the console.
# Create an Amazon EC2 instance for CodeDeploy (CloudFormation template)
You can use our CloudFormation template to quickly launch an Amazon EC2 instance running Amazon Linux or Windows Server. You can use the AWS CLI, the CodeDeploy console, or the AWS APIs to launch the instance with the template. In addition to launching the instance, the template does the following:
+ Instructs CloudFormation to give the instance permission to participate in CodeDeploy deployments.
+ Tags the instance so CodeDeploy can find it during a deployment.
+ Installs and runs the CodeDeploy agent on the instance.
You don't have to use our CloudFormation to set up an Amazon EC2 instance. For alternatives, see [Working with instances for CodeDeploy](instances.md).
We do not provide an CloudFormation template for Amazon EC2 instances running Ubuntu Server or Red Hat Enterprise Linux (RHEL).
**Topics**
+ [Before you begin](#instances-ec2-create-cloudformation-template-before)
+ [Launch an Amazon EC2 instance with the CloudFormation template (console)](#instances-ec2-create-cloudformation-template-console)
+ [Launch an Amazon EC2 instance with the CloudFormation template (AWS CLI)](#instances-ec2-create-cloudformation-template-cli)
## Before you begin
Before you can use the CloudFormation template to launch Amazon EC2 instances, make sure you complete the following steps.
1. Make sure you have created an administrative user, as described in [Step 1: Setting up](getting-started-setting-up.md). Double-check that the user has the following minimum permissions and add any that are not present:
+ cloudformation:\$1
+ codedeploy:\$1
+ ec2:\$1
+ iam:AddRoleToInstanceProfile
+ iam:CreateInstanceProfile
+ iam:CreateRole
+ iam:DeleteInstanceProfile
+ iam:DeleteRole
+ iam:DeleteRolePolicy
+ iam:GetRole
+ iam:DeleteRolePolicy
+ iam:PutRolePolicy
+ iam:RemoveRoleFromInstanceProfile
1. Make sure you have an instance key pair to enable SSH access to the Amazon EC2 instance running Amazon Linux or RDP access to the instance running Windows Server.
To find a key pair name, open the Amazon EC2 console at [https://console.aws.amazon.com/ec2](https://console.aws.amazon.com/ec2). In the navigation pane, under **Network & Security**, choose **Key Pairs**, and note the key pair name in the list.
To generate a new key pair, see [Creating your key pair using Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#having-ec2-create-your-key-pair). Be sure the key pair is created in one of the regions listed in [Region and endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#codedeploy_region) in *AWS General Reference*. Otherwise, you can't use the instance key pair with CodeDeploy.
## Launch an Amazon EC2 instance with the CloudFormation template (console)
1. Sign in to the AWS Management Console and open the CloudFormation console at [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
**Important**
Sign in to the AWS Management Console with the same account you used in [Getting started with CodeDeploy](getting-started-codedeploy.md). On the navigation bar, in the region selector, choose one of the regions listed in [Region and endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#codedeploy_region) in *AWS General Reference*. CodeDeploy supports these regions only.
1. Choose **Create Stack**.
1. In **Choose a template**, choose **Specify an Amazon S3 template URL**. In the box, type the location of the CloudFormation template for your region, and then choose **Next**.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/instances-ec2-create-cloudformation-template.html)
1. In the **Stack name** box, type a name for the stack (for example, **CodeDeployDemoStack**).
1. In **Parameters**, type the following, and then choose **Next**.
+ For **InstanceCount**, type the number of instances you want to launch. (We recommend you leave the default of **1**.)
+ For **InstanceType**, type the instance type you want to launch (or leave the default of **t1.micro**).
+ For **KeyPairName**, type the instance key pair name. Type the key pair name only, not the key pair file extension.
+ For **OperatingSystem** box, type **Windows** to launch instances running Windows Server (or leave the default of **Linux**).
+ For **SSHLocation**, type the IP address range to use for connecting to the instance with SSH or RDP (or leave the default of **0.0.0.0/0**).
**Important**
The default of **0.0.0.0/0** is provided for demonstration purposes only. CodeDeploy does not require Amazon EC2 instances to have unrestricted access to ports. As a best practice, we recommend restricting access to SSH (and HTTP) ports. For more information, see [Tips for securing your Amazon EC2 instance](https://aws.amazon.com/articles/1233).
+ For **TagKey**, type the instance tag key CodeDeploy will use to identify the instances during deployment (or leave the default of **Name**).
+ For **TagValue**, type the instance tag value CodeDeploy will use to identify the instances during deployment (or leave the default of **CodeDeployDemo**).
1. On the **Options** page, leave the option boxes blank, and choose **Next**.
**Important**
CloudFormation tags are different from CodeDeploy tags. CloudFormation uses tags to simplify administration of your infrastructure. CodeDeploy uses tags to identify Amazon EC2 instances. You specified CodeDeploy tags on the **Specify Parameters** page.
1. On the **Review** page, in **Capabilities**, select the **I acknowledge that CloudFormation might create IAM resources** box, and then choose **Create**.
After CloudFormation has created the stack and launched the Amazon EC2 instances, in the CloudFormation console, **CREATE\$1COMPLETE** will be displayed in the **Status** column. This process can take several minutes.
To verify the CodeDeploy agent is running on the Amazon EC2 instances, see [Managing CodeDeploy agent operations](codedeploy-agent-operations.md), and then proceed to [Create an application with CodeDeploy](applications-create.md).
## Launch an Amazon EC2 instance with the CloudFormation template (AWS CLI)
1. Use our CloudFormation template in a call to the **create-stack** command. This stack will launch a new Amazon EC2 instance with the CodeDeploy agent installed.
To launch an Amazon EC2 instance running Amazon Linux:
```
aws cloudformation create-stack \
--stack-name CodeDeployDemoStack \
--template-url templateURL \
--parameters ParameterKey=InstanceCount,ParameterValue=1 ParameterKey=InstanceType,ParameterValue=t1.micro \
ParameterKey=KeyPairName,ParameterValue=keyName ParameterKey=OperatingSystem,ParameterValue=Linux \
ParameterKey=SSHLocation,ParameterValue=0.0.0.0/0 ParameterKey=TagKey,ParameterValue=Name \
ParameterKey=TagValue,ParameterValue=CodeDeployDemo \
--capabilities CAPABILITY_IAM
```
To launch an Amazon EC2 instance running Windows Server:
```
aws cloudformation create-stack --stack-name CodeDeployDemoStack --template-url template-url --parameters ParameterKey=InstanceCount,ParameterValue=1 ParameterKey=InstanceType,ParameterValue=t1.micro ParameterKey=KeyPairName,ParameterValue=keyName ParameterKey=OperatingSystem,ParameterValue=Windows ParameterKey=SSHLocation,ParameterValue=0.0.0.0/0 ParameterKey=TagKey,ParameterValue=Name ParameterKey=TagValue,ParameterValue=CodeDeployDemo --capabilities CAPABILITY_IAM
```
*keyName* is the instance key pair name. Type the key pair name only, not the key pair file extension.
*template-url* is the location of the CloudFormation template for your region:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/instances-ec2-create-cloudformation-template.html)
This command creates an CloudFormation stack named **CodeDeployDemoStack**, using the CloudFormation template in the specified Amazon S3 bucket. The Amazon EC2 instance is based on the t1.micro instance type, but you can use any type. It is tagged with the value **CodeDeployDemo**, but you can tag it with any value. It has the specified instance key pair applied.
1. Call the **describe-stacks** command to verify the CloudFormation stack named **CodeDeployDemoStack** was successfully created:
```
aws cloudformation describe-stacks --stack-name CodeDeployDemoStack --query "Stacks[0].StackStatus" --output text
```
Do not proceed until the value `CREATE_COMPLETE` is returned.
To verify the CodeDeploy agent is running on the Amazon EC2 instance, see [Managing CodeDeploy agent operations](codedeploy-agent-operations.md), and then proceed to [Create an application with CodeDeploy](applications-create.md).
# Configure an Amazon EC2 instance to work with CodeDeploy
These instructions show you how to configure an Amazon EC2 instance running Amazon Linux, Ubuntu Server, Red Hat Enterprise Linux (RHEL), or Windows Server for use in CodeDeploy deployments.
**Note**
If you do not have an Amazon EC2 instance, you can use the CloudFormation template to launch one running Amazon Linux or Windows Server. We do not provide a template for Ubuntu Server or RHEL.
## Step 1: Verify an IAM instance profile is attached to your Amazon EC2 instance
1. Sign in to the AWS Management Console and open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, under **Instances**, choose **Instances**.
1. Browse to and choose your Amazon EC2 instance in the list.
1. In the details pane, on the **Description** tab, note the value in the **IAM role** field, and then proceed to the next section.
If the field is empty, you can attach an IAM instance profile to the instance. For information, see [Attaching an IAM role to an instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#attach-iam-role).
## Step 2: Verify the attached IAM instance profile has the correct access permissions
1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane, choose **Roles**.
1. Browse to and choose the IAM role name you noted in step 4 of the previous section.
**Note**
If you want to use the service role generated by the CloudFormation template instead of one you created by following the instructions in [Step 2: Create a service role for CodeDeploy](getting-started-create-service-role.md), note the following:
In some versions of our CloudFormation template, the display name of the IAM instance profile generated and attached to the Amazon EC2 instances is not the same as the display name in the IAM console. For example, the IAM instance profile might have a display name of `CodeDeploySampleStack-expnyi6-InstanceRoleInstanceProfile-IK8J8A9123EX`, while the IAM instance profile in the IAM console might have a display name of `CodeDeploySampleStack-expnyi6-InstanceRole-C5P33V1L64EX`.
To help you identify the instance profile in the IAM console, you'll see the prefix of `CodeDeploySampleStack-expnyi6-InstanceRole` is the same for both. For information about why these display names might be different, see [Instance profiles](https://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html).
1. Choose the **Trust Relationships** tab. If there is no entry in **Trusted Entities** that reads **The identity provider(s) ec2.amazonaws.com**, you cannot use this Amazon EC2 instance. Stop and create an Amazon EC2 instance using the information in [Working with instances for CodeDeploy](instances.md).
If there is an entry that reads **The identity provider(s) ec2.amazonaws.com**, and you are storing your applications in GitHub repositories only, then skip ahead to [Step 3: Tag the Amazon EC2 instance](#instances-ec2-configure-3-tag-instance).
If there is an entry that reads **The identity provider(s) ec2.amazonaws.com**, and you are storing your applications in Amazon S3 buckets, choose the **Permissions** tab.
1. If there is a policy in the **Permissions policies** area, expand the policy, then choose **Edit policy**.
1. Choose the **JSON** tab. If you are storing your applications in Amazon S3 buckets, make sure `"s3:Get*"` and `"s3:List*"` are in the list of specified actions.
It may look something like this:
```
{"Statement":[{"Resource":"*","Action":[
... Some actions may already be listed here ...
"s3:Get*","s3:List*"
... Some more actions may already be listed here ...
],"Effect":"Allow"}]}
```
Or it may look something like this:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:Get*",
"s3:List*"
],
"Resource": "*"
}
]
}
```
------
If `"s3:Get*"` and `"s3:List*"` are not in the list of specified actions, choose **Edit** to add them, and then choose **Save**. (If neither `"s3:Get*"` or `"s3:List*"` is the last action in the list, be sure to add a comma after the action, so the policy document validates.)
**Note**
We recommend that you restrict this policy to only those Amazon S3 buckets your Amazon EC2 instances must access. Make sure to give access to the Amazon S3 buckets that contain the CodeDeploy agent. Otherwise, an error might occur when the CodeDeploy agent is installed or updated on the instances. To grant the IAM instance profile access to only some CodeDeploy resource kit buckets in Amazon S3, use the following policy, but remove the lines for buckets you want to prevent access to:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:Get*",
"s3:List*"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/*",
"arn:aws:s3:::aws-codedeploy-us-east-2/*",
"arn:aws:s3:::aws-codedeploy-us-east-1/*",
"arn:aws:s3:::aws-codedeploy-us-west-1/*",
"arn:aws:s3:::aws-codedeploy-us-west-2/*",
"arn:aws:s3:::aws-codedeploy-ca-central-1/*",
"arn:aws:s3:::aws-codedeploy-eu-west-1/*",
"arn:aws:s3:::aws-codedeploy-eu-west-2/*",
"arn:aws:s3:::aws-codedeploy-eu-west-3/*",
"arn:aws:s3:::aws-codedeploy-eu-central-1/*",
"arn:aws:s3:::aws-codedeploy-eu-central-2/*",
"arn:aws:s3:::aws-codedeploy-eu-north-1/*",
"arn:aws:s3:::aws-codedeploy-eu-south-1/*",
"arn:aws:s3:::aws-codedeploy-eu-south-2/*",
"arn:aws:s3:::aws-codedeploy-il-central-1/*",
"arn:aws:s3:::aws-codedeploy-ap-east-1/*",
"arn:aws:s3:::aws-codedeploy-ap-northeast-1/*",
"arn:aws:s3:::aws-codedeploy-ap-northeast-2/*",
"arn:aws:s3:::aws-codedeploy-ap-northeast-3/*",
"arn:aws:s3:::aws-codedeploy-ap-southeast-1/*",
"arn:aws:s3:::aws-codedeploy-ap-southeast-2/*",
"arn:aws:s3:::aws-codedeploy-ap-southeast-3/*",
"arn:aws:s3:::aws-codedeploy-ap-southeast-4/*",
"arn:aws:s3:::aws-codedeploy-ap-south-1/*",
"arn:aws:s3:::aws-codedeploy-ap-south-2/*",
"arn:aws:s3:::aws-codedeploy-me-central-1/*",
"arn:aws:s3:::aws-codedeploy-me-south-1/*",
"arn:aws:s3:::aws-codedeploy-sa-east-1/*"
]
}
]
}
```
## Step 3: Tag the Amazon EC2 instance
For instructions about how to tag the Amazon EC2 instance so that CodeDeploy can find it during a deployment, see [Working with tags in the console](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#Using_Tags_Console), and then return to this page.
**Note**
You can tag the Amazon EC2 instance with any key and value you like. Just make sure to specify this key and value when you deploy to it.
## Step 4: Install the AWS CodeDeploy agent on the Amazon EC2 instance
For instructions about how to install the CodeDeploy agent on the Amazon EC2 instance and verify it is running, see [Managing CodeDeploy agent operations](codedeploy-agent-operations.md), and then proceed to [Create an application with CodeDeploy](applications-create.md).
# Working with on-premises instances for CodeDeploy
An on-premises instance is any physical device that is not an Amazon EC2 instance that can run the CodeDeploy agent and connect to public AWS service endpoints.
Deploying a CodeDeploy application revision to an on-premises instance involves two major steps:
+ **Step 1** – Configure each on-premises instance, register it with CodeDeploy, and then tag it.
+ **Step 2** – Deploy application revisions to the on-premises instance.
**Note**
To experiment with creating and deploying a sample application revision to a correctly configured and registered on-premises instance, see [Tutorial: Deploy an application to an on-premises instance with CodeDeploy (Windows Server, Ubuntu Server, or Red Hat Enterprise Linux)](tutorials-on-premises-instance.md). For information about on-premises instances and how they work with CodeDeploy, see [Working with on-premises instances for CodeDeploy](#instances-on-premises).
If you don't want an on-premises instance to be used in deployments anymore, you can remove the on-premises instance tags from the deployment groups. For a more robust approach, remove the on-premises instance tags from the instance. You can also explicitly deregister an on-premises instance so it can no longer be used in any deployments. For more information, see [Managing on-premises instances operations in CodeDeploy](on-premises-instances-operations.md).
The instructions in this section show you how to configure an on-premises instance and then register and tag it with CodeDeploy so it can be used in deployments. This section also describes how to use CodeDeploy to get information about on-premises instances and deregister an on-premises instance after you're no longer planning to deploy to it.
**Topics**
+ [Prerequisites for configuring an on-premises instance](instances-on-premises-prerequisites.md)
+ [Register an on-premises instance](on-premises-instances-register.md)
+ [Managing on-premises instances operations](on-premises-instances-operations.md)
# Prerequisites for configuring an on-premises instance
The following prerequisites must be met before you can register an on-premises instance.
**Important**
If you are using the [register-on-premises-instance](https://docs.aws.amazon.com/cli/latest/reference/deploy/register-on-premises-instance.html) command and periodically refreshed temporary credentials generated with the AWS Security Token Service (AWS STS), there are other prerequisites. For information, see [IAM session ARN registration prerequisites](register-on-premises-instance-iam-session-arn.md#register-on-premises-instance-iam-session-arn-prerequisites).
**Device requirements**
The device you want to prepare, register, and tag as an on-premises instance with CodeDeploy must be running a supported operating system. For a list, see [Operating systems supported by the CodeDeploy agent](codedeploy-agent.md#codedeploy-agent-supported-operating-systems).
If your operating system is not supported, the CodeDeploy agent is available as open source for you to adapt to your needs. For more information, see the [CodeDeploy agent](https://github.com/aws/aws-codedeploy-agent) repository in GitHub.
**Outbound communication**
The on-premises instance must be able to connect to public AWS service endpoints to communicate with CodeDeploy.
The CodeDeploy agent communicates outbound using HTTPS over port 443.
**Administrative control**
The local or network account used on the on-premises instance to configure the on-premises instance must be able to run either as `sudo` or `root` (for Ubuntu Server) or as an administrator (for Windows Server).
**IAM permissions**
The IAM identity you use to register the on-premises instance must be granted permissions to complete the registration (and to deregister the on-premises instance, as needed).
In addition to the policy described in [Step 3: Limit the CodeDeploy user's permissions](getting-started-policy.md), make sure the calling IAM identity has the following additional policy attached.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:CreateAccessKey",
"iam:CreateUser",
"iam:DeleteAccessKey",
"iam:DeleteUser",
"iam:DeleteUserPolicy",
"iam:ListAccessKeys",
"iam:ListUserPolicies",
"iam:PutUserPolicy",
"iam:GetUser"
],
"Resource": "*"
}
]
}
```
------
For information on how to attach IAM policies, see [Managing IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage.html).
# Register an on-premises instance with CodeDeploy
To register an on-premises instance, you must use an IAM identity to authenticate your requests. You can choose from the following options for the IAM identity and registration method you use:
+ Use an IAM role ARN to authenticate requests.
+ Use the [register-on-premises-instance](https://docs.aws.amazon.com/cli/latest/reference/deploy/register-on-premises-instance.html) command and periodically refreshed temporary credentials generated with the AWS Security Token Service (AWS STS) to manually configure most registration options. This option offers the highest level of security, because authentication occurs using a temporary token that times out and must be refreshed periodically. This option is recommended for production deployments of any size. For information, see [Use the register-on-premises-instance command (IAM Session ARN) to register an on-premises instance](register-on-premises-instance-iam-session-arn.md).
+ (Not recommended) Use an IAM user ARN to authenticate requests.
+ Use the [register](https://docs.aws.amazon.com/cli/latest/reference/deploy/register.html) command for the most automated registration process. This option should only be used for non-production deployments where security is less of a concern. This option is less secure because it uses static (permanent) credentials for authentication. This option works well for registering a single on-premises instance. For information, see [Use the register command (IAM user ARN) to register an on-premises instance](instances-on-premises-register-instance.md).
+ Use the [register-on-premises-instance](https://docs.aws.amazon.com/cli/latest/reference/deploy/register-on-premises-instance.html) command to manually configure most registration options. Suitable for registering a small number of on-premises instances. For information, see [Use the register-on-premises-instance command (IAM user ARN) to register an on-premises instance](register-on-premises-instance-iam-user-arn.md).
**Topics**
+ [Use the register-on-premises-instance command (IAM Session ARN) to register an on-premises instance](register-on-premises-instance-iam-session-arn.md)
+ [Use the register command (IAM user ARN) to register an on-premises instance](instances-on-premises-register-instance.md)
+ [Use the register-on-premises-instance command (IAM user ARN) to register an on-premises instance](register-on-premises-instance-iam-user-arn.md)
# Use the register-on-premises-instance command (IAM Session ARN) to register an on-premises instance
For maximum control over the authentication and registration of your on-premises instances, you can use the [register-on-premises-instance](https://docs.aws.amazon.com/cli/latest/reference/deploy/register-on-premises-instance.html) command and periodically refreshed temporary credentials generated with the AWS Security Token Service (AWS STS). A static IAM role for the instance assumes the role of these refreshed AWS STS credentials to perform CodeDeploy deployment operations.
This method is most useful when you need to register a large number of instances. It allows you to automate the registration process with CodeDeploy. You can use your own identity and authentication system to authenticate on-premises instances and distribute IAM session credentials from the service to the instances for use with CodeDeploy.
**Note**
Alternatively, you can use a shared IAM user distributed to all on-premises instances to call the AWS STS [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API to retrieve session credentials for on-premises instances. This method is less secure and not recommended for production or mission-critical environments.
Use the information in the following topics to configure an on-premises instance using temporary security credentials generated with AWS STS.
**Topics**
+ [IAM session ARN registration prerequisites](#register-on-premises-instance-iam-session-arn-prerequisites)
+ [Step 1: Create the IAM role that on-premises instances will assume](#register-on-premises-instance-iam-session-arn-1)
+ [Step 2: Generate temporary credentials for an individual instance using AWS STS](#register-on-premises-instance-iam-session-arn-2)
+ [Step 3: Add a configuration file to the on-premises instance](#register-on-premises-instance-iam-session-arn-3)
+ [Step 4: Prepare an on-premises instance for CodeDeploy deployments](#register-on-premises-instance-iam-session-arn-4)
+ [Step 5: Register the on-premises instance with CodeDeploy](#register-on-premises-instance-iam-session-arn-5)
+ [Step 6: Tag the on-premises instance](#register-on-premises-instance-iam-session-arn-6)
+ [Step 7: Deploy application revisions to the on-premises instance](#register-on-premises-instance-iam-session-arn-7)
+ [Step 8: Track deployments to the on-premises instance](#register-on-premises-instance-iam-session-arn-8)
## IAM session ARN registration prerequisites
In addition to the prerequisites listed in [Prerequisites for configuring an on-premises instance](instances-on-premises-prerequisites.md), the following additional requirements must be met:
**IAM permissions**
The IAM identity you use to register an on-premises instance must be granted permissions to perform CodeDeploy operations. Make sure the **AWSCodeDeployFullAccess** managed policy is attached to the IAM identity. For information, see [AWS managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) in the *IAM User Guide*.
**System to refresh temporary credentials**
If you use an IAM session ARN to register on-premises instances, you must have a system in place to periodically refresh the temporary credentials. Temporary credentials expire after one hour or sooner if a shorter period is specified when the credentials are generated. There are two methods for refreshing the credentials:
+ **Method 1**: Use the identity and authentication system in place in your corporate network with a CRON script that periodically polls the identity and authentication system and copies the latest session credentials to the instance. This enables you to integrate your authentication and identity structure with AWS without needing to make changes to the CodeDeploy agent or service to support authentication types you use in your organization.
+ **Method 2**: Periodically run a CRON job on the instance to call the AWS STS [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) action and write the session credentials to a file that the CodeDeploy agent can access. This method still requires using an IAM user and copying credentials to the on-premises instance, but you can re-use the same IAM user and credentials across your fleet of on-premises instances.
**Note**
Regardless of whether you're using method 1 or 2, you must set up a process to restart the CodeDeploy agent after the temporary session credentials are updated so that the new credentials take effect.
For information about creating and working with AWS STS credentials, see [AWS Security Token Service API Reference](https://docs.aws.amazon.com/STS/latest/APIReference/) and [Using temporary security credentials to request access to AWS resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html).
## Step 1: Create the IAM role that on-premises instances will assume
You can use the AWS CLI or the IAM console to create an IAM role that will be used by your on-premises instances to authenticate and interact with CodeDeploy.
You only need to create a single IAM role. Each one of your on-premises instances can assume this role to retrieve the temporary security credentials that provide the permissions granted to this role.
The role you create will require the following permissions to access the files required to install the CodeDeploy agent:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"s3:Get*",
"s3:List*"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
------
We recommend that you restrict this policy to only those Amazon S3 buckets your on-premises instance needs to access. If you restrict this policy, make sure to give access to the Amazon S3 buckets that contain the CodeDeploy agent. Otherwise, an error might occur whenever the CodeDeploy agent is installed or updated on the on-premises instance. For information about controlling access to Amazon S3 buckets, see [Managing access permissions to your Amazon S3 resources](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-access-control.html).
**To create the IAM role**
1. Call the [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) command using the `--role-name` option to specify a name for the IAM role (for example, `CodeDeployInstanceRole`) and the `--assume-role-policy-document` option to provide the permissions.
When you create the IAM role for this instance, you might give it the name `CodeDeployInstanceRole` and include the required permissions in a file named `CodeDeployRolePolicy.json`:
```
aws iam create-role --role-name CodeDeployInstanceRole --assume-role-policy-document file://CodeDeployRolePolicy.json
```
1. In the output of the call to the **create-role** command, note the value of the ARN field. For example:
```
arn:aws:iam::123456789012:role/CodeDeployInstanceRole
```
You will need the role ARN when you use the AWS STS [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API to generate short-term credentials for each instance.
For more information about creating IAM roles, see [Creating a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) in *IAM User Guide*.
For information about assigning permissions to an existing role, see [put-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/put-role-policy.html) in [AWS CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/).
## Step 2: Generate temporary credentials for an individual instance using AWS STS
Before you generate the temporary credentials that will be used for registering an on-premises instance, you must create or choose the IAM identity (user or role) that you will generate the temporary credentials for. The `sts:AssumeRole` permission must be included in the policy settings for this IAM identity.
For information about granting `sts:AssumeRole` permissions to an IAM identity, see [Creating a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) and [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html).
There are two ways to generate the temporary credentials:
+ Use the [assume-role](https://docs.aws.amazon.com/cli/latest/reference/sts/assume-role.html) command with the AWS CLI. For example:
```
aws sts assume-role --role-arn arn:aws:iam::12345ACCOUNT:role/role-arn --role-session-name session-name
```
Where:
+ *12345ACCOUNT* is the 12-digit account number for your organization.
+ *role-arn* is the ARN of the role to be assumed, which you generated in [Step 1: Create the IAM role that on-premises instances will assume](#register-on-premises-instance-iam-session-arn-1).
+ *session-name* is the name you want to give to the role session you are creating now.
**Note**
If you use a CRON script that periodically polls the identity and authentication system and copies the latest session credentials to the instance (method 1 for refreshing temporary credentials described in [IAM session ARN registration prerequisites](#register-on-premises-instance-iam-session-arn-prerequisites)), you can instead use any supported AWS SDK to call [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html).
+ Use a tool provided by AWS.
The aws-codedeploy-session-helper tool generates AWS STS credentials and writes them to a file you place on the instance. This tool is best suited to method 2 for refreshing temporary credentials described in [IAM session ARN registration prerequisites](#register-on-premises-instance-iam-session-arn-prerequisites). In this method, the aws-codedeploy-session-helper tool is placed on each instance and executes the command using an IAM user’s permissions. Each instance uses the same IAM user’s credentials in conjunction with this tool.
For more information, see the [aws-codedeploy-session-helper](https://github.com/awslabs/aws-codedeploy-samples/tree/master/utilities/aws-codedeploy-session-helper) GitHub repository.
**Note**
After you have created the IAM session credentials, place them in any location on the on-premises instance. In the next step, you will configure the CodeDeploy agent to access the credentials in this location.
Before continuing, make sure the system you will use to periodically refresh the temporary credentials is in place. If the temporary credentials are not refreshed, deployments to the on-premises instance will fail. For more information, see "System to refresh temporary credentials" in [IAM session ARN registration prerequisites](#register-on-premises-instance-iam-session-arn-prerequisites).
## Step 3: Add a configuration file to the on-premises instance
Add a configuration file to the on-premises instance, using root or administrator permissions. This configuration file is used to declare the IAM credentials and the target AWS region to be used for CodeDeploy. The file must be added to a specific location on the on-premises instance. The file must include the IAM temporary session ARN, its secret key ID and secret access key, and the target AWS region.
**To add a configuration file**
1. Create a file named `codedeploy.onpremises.yml` (for an Ubuntu Server or RHEL on-premises instance) or `conf.onpremises.yml` (for a Windows Server on-premises instance) in the following location on the on-premises instance:
+ For Ubuntu Server: `/etc/codedeploy-agent/conf`
+ For Windows Server: `C:\ProgramData\Amazon\CodeDeploy`
1. Use a text editor to add the following information to the newly created `codedeploy.onpremises.yml` file (Linux) or `conf.onpremises.yml` file (Windows):
```
---
iam_session_arn: iam-session-arn
aws_credentials_file: credentials-file
region: supported-region
```
Where:
+ *iam-session-arn* is the IAM session ARN you noted in [Step 2: Generate temporary credentials for an individual instance using AWS STS](#register-on-premises-instance-iam-session-arn-2).
+ *credentials-file* is the location of the credentials file for the temporary session ARN, as noted in [Step 2: Generate temporary credentials for an individual instance using AWS STS](#register-on-premises-instance-iam-session-arn-2).
+ *supported-region* is one of the regions that CodeDeploy supports, as listed in [Region and endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#codedeploy_region) in *AWS General Reference*.
## Step 4: Prepare an on-premises instance for CodeDeploy deployments
**Install and configure the AWS CLI **
Install and configure the AWS CLI on the on-premises instance. (The AWS CLI will be used to download and install the CodeDeploy agent on the on-premises instance.)
1. To install the AWS CLI on the on-premises instance, follow the instructions in [Getting set up with the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-set-up.html) in the *AWS Command Line Interface User Guide*.
**Note**
CodeDeploy commands for working with on-premises instances became available in version 1.7.19 of the AWS CLI. If you have a version of the AWS CLI already installed, you can check its version by calling **aws --version**.
1. To configure the AWS CLI on the on-premises instance, follow the instructions in [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) in the *AWS Command Line Interface User Guide*.
**Important**
As you configure the AWS CLI (for example, by calling the **aws configure** command), be sure to specify the secret key ID and secret access key of an IAM user that has, at minimum, the permissions described in [IAM session ARN registration prerequisites](#register-on-premises-instance-iam-session-arn-prerequisites).
**Set the AWS\$1REGION Environment Variable (Ubuntu Server and RHEL Only)**
If you are not running Ubuntu Server or RHEL on your on-premises instance, skip this step and go directly to "Install the CodeDeploy agent ."
Install the CodeDeploy agent on an Ubuntu Server or RHEL on-premises instance and enable instance to update the CodeDeploy agent whenever a new version becomes available. You do this by setting the `AWS_REGION` environment variable on the instance to the identifier of one of the regions supported by CodeDeploy. We recommend that you set the value to the region where your CodeDeploy applications, deployment groups, and application revisions are located (for example, `us-west-2`). For a list of regions, see [Region and endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#codedeploy_region) in the *AWS General Reference*.
To set the environment variable, call the following from the terminal:
```
export AWS_REGION=supported-region
```
Where *supported-region* is the region identifier (for example, `us-west-2`).
**Install the CodeDeploy agent**
+ For an Ubuntu Server on-premises instance, follow the instructions in [Install the CodeDeploy agent for Ubuntu Server](codedeploy-agent-operations-install-ubuntu.md), and then return to this page.
+ For a RHEL on-premises instance, follow the instructions in [Install the CodeDeploy agent for Amazon Linux or RHEL](codedeploy-agent-operations-install-linux.md), and then return to this page.
+ For a Windows Server on-premises instance, follow the instructions in [Install the CodeDeploy agent for Windows Server](codedeploy-agent-operations-install-windows.md), and then return to this page.
## Step 5: Register the on-premises instance with CodeDeploy
The instructions in this step assume you are registering the on-premises instance from the on-premises instance itself. You can register an on-premises instance from a separate device or instance that has the AWS CLI installed and configured.
Use the AWS CLI to register the on-premises instance with CodeDeploy so that it can be used in deployments.
Before you can use the AWS CLI, you will need the ARN of the temporary session credentials you created in [Step 3: Add a configuration file to the on-premises instance](#register-on-premises-instance-iam-session-arn-3). For example, for an instance you identify as `AssetTag12010298EX`:
```
arn:sts:iam::123456789012:assumed-role/CodeDeployInstanceRole/AssetTag12010298EX
```
Call the [register-on-premises-instance](https://docs.aws.amazon.com/cli/latest/reference/deploy/register-on-premises-instance.html) command, specifying:
+ A name that uniquely identifies the on-premises instance (with the `--instance-name` option).
**Important**
To help identify the on-premises instance, especially for debugging purposes, we strongly recommend that you specify a name that maps to some unique characteristic of the on-premises instance (for example, the session-name of the STS credentials and the serial number or an internal asset identifier, if applicable). If you specify a MAC address as a name, be aware that MAC addresses contain characters that CodeDeploy does not allow, such as colon (:). For a list of allowed characters, see [CodeDeploy quotas](limits.md).
+ The IAM session ARN that you set up to authenticate multiple on-premises instances in [Step 1: Create the IAM role that on-premises instances will assume](#register-on-premises-instance-iam-session-arn-1).
For example:
```
aws deploy register-on-premises-instance --instance-name name-of-instance --iam-session-arn arn:aws:sts::account-id:assumed-role/role-to-assume/session-name
```
Where:
+ *name-of-instance* is the name you use to identify the on-premises instance, such as `AssetTag12010298EX`.
+ *account-id* is the 12-digit account ID for your organization, such as `111222333444`.
+ *role-to-assume* is the name of the IAM role you created for the instance, such as `CodeDeployInstanceRole`.
+ *session-name* is the name of the session role you specified in [Step 2: Generate temporary credentials for an individual instance using AWS STS](#register-on-premises-instance-iam-session-arn-2).
## Step 6: Tag the on-premises instance
You can use either the AWS CLI or the CodeDeploy console to tag the on-premises instance. (CodeDeploy uses on-premises instance tags to identify the deployment targets during a deployment.)
**To tag the on-premises instance (CLI)**
+ Call the [add-tags-to-on-premises-instances](https://docs.aws.amazon.com/cli/latest/reference/deploy/add-tags-to-on-premises-instances.html) command, specifying:
+ The name that uniquely identifies the on-premises instance (with the `--instance-names` option).
+ The name of the on-premises instance tag key and tag value you want to use (with the `--tags` option). You must specify both a name and value. CodeDeploy does not allow on-premises instance tags that have values only.
For example:
```
aws deploy add-tags-to-on-premises-instances --instance-names AssetTag12010298EX --tags Key=Name,Value=CodeDeployDemo-OnPrem
```
**To tag the on-premises instance (console)**
1. Sign in to the AWS Management Console and open the CodeDeploy console at [https://console.aws.amazon.com/codedeploy](https://console.aws.amazon.com/codedeploy).
**Note**
Sign in with the same user that you set up in [Getting started with CodeDeploy](getting-started-codedeploy.md).
1. In the navigation pane, expand **Deploy**, and choose **On-premises instances**.
1. In the list of on-premises instances, choose name of the on-premises instance you want to tag.
1. In the list of tags, select or enter the desired tag key and tag value. After you enter the tag key and tag value, another row appears. You can repeat this for up to 10 tags. To remove a tag, choose **Remove**.
1. After you have added tags, choose **Update Tags**.
## Step 7: Deploy application revisions to the on-premises instance
You are now ready to deploy application revisions to the registered and tagged on-premises instance.
You deploy application revisions to on-premises instances in a way that's similar to deploying application revisions to Amazon EC2 instances. For instructions, see [Create a deployment with CodeDeploy](deployments-create.md). These instructions include a link to prerequisites, including creating an application, creating a deployment group, and preparing an application revision. If you need a simple sample application revision to deploy, you can create the one described in [Step 2: Create a sample application revision](tutorials-on-premises-instance-2-create-sample-revision.md) in the [Tutorial: Deploy an application to an on-premises instance with CodeDeploy (Windows Server, Ubuntu Server, or Red Hat Enterprise Linux)](tutorials-on-premises-instance.md).
**Important**
If you reuse a CodeDeploy service role as part of creating a deployment group that targets on-premises instances, you must include `Tag:get*` to the `Action` portion of the service role's policy statement. For more information, see [Step 2: Create a service role for CodeDeploy](getting-started-create-service-role.md).
## Step 8: Track deployments to the on-premises instance
After you deploy an application revision to registered and tagged on-premises instances, you can track the deployment's progress.
You track deployments to on-premises instances in a way that's similar to tracking deployments to Amazon EC2 instances. For instructions, see [View CodeDeploy deployment details](deployments-view-details.md).
# Use the register command (IAM user ARN) to register an on-premises instance
**Important**
Registering an instance using an IAM user is not recommended because it uses static (permanent) credentials for authentication. For improved security, we recommend registering an instance using temporary credentials for authentication. For more information, see [Use the register-on-premises-instance command (IAM Session ARN) to register an on-premises instance](register-on-premises-instance-iam-session-arn.md).
**Important**
Make sure you have a plan in place to rotate the IAM user's access keys (permanent credentials). For more information, see [Rotating access keys](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_credentials_access-keys.html#Using_RotateAccessKey).
This section describes how to configure an on-premises instance and register and tag it with CodeDeploy with the least amount of effort. The **register** command is most useful when you are working with single or small fleets of on-premises instances. You can use the **register** command only when you are using an IAM user ARN to authenticate an instance. You cannot use the **register** command with an IAM session ARN for authentication.
When you use the **register** command, you can let CodeDeploy do the following:
+ Create an IAM user in AWS Identity and Access Management for the on-premises instance, if you do not specify one with the command.
+ Save the IAM user's credentials to an on-premises instance configuration file.
+ Register the on-premises instance with CodeDeploy.
+ Add tags to the on-premises instance, if you specify them as part of the command.
**Note**
The [register-on-premises-instance](https://docs.aws.amazon.com/cli/latest/reference/deploy/register-on-premises-instance.html) command is an alternative to the [register](https://docs.aws.amazon.com/cli/latest/reference/deploy/register.html) command. You use the **register-on-premises-instance** command if you want to configure an on-premises instance and register and tag it with CodeDeploy mostly on your own. The **register-on-premises-instance** command also gives you the option to use an IAM session ARN to register instances instead of an IAM user ARN. This approach provides a major advantage if you have large fleets of on-premises instances. Specifically, you can use a single IAM session ARN to authenticate multiple instances instead of having to create an IAM user for each on-premises instance one by one. For more information, see [Use the register-on-premises-instance command (IAM user ARN) to register an on-premises instance](register-on-premises-instance-iam-user-arn.md) and [Use the register-on-premises-instance command (IAM Session ARN) to register an on-premises instance](register-on-premises-instance-iam-session-arn.md).
**Topics**
+ [Step 1: Install and configure the AWS CLI on the on-premises instance](#instances-on-premises-register-instance-1-install-cli)
+ [Step 2: Call the register command](#instances-on-premises-register-instance-2-register-command)
+ [Step 3: Call the install command](#instances-on-premises-register-instance-3-install-command)
+ [Step 4: Deploy application revisions to the on-premises instance](#instances-on-premises-register-instance-4-deploy-revision)
+ [Step 5: Track deployments to the on-premises instance](#instances-on-premises-register-instance-5-track-deployment)
## Step 1: Install and configure the AWS CLI on the on-premises instance
1. Install the AWS CLI on the on-premises instance. Follow the instructions in [Getting set up with the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-set-up.html) in the *AWS Command Line Interface User Guide*.
**Note**
CodeDeploy commands for working with on-premises instances are available in AWS CLI version 1.7.19 and later. If you have the AWS CLI already installed, call **aws --version** to check its version.
1. Configure the AWS CLI on the on-premises instance. Follow the instructions in [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) in *AWS Command Line Interface User Guide*.
**Important**
As you configure the AWS CLI (for example, by calling the **aws configure** command), be sure to specify the secret key ID and secret access key of an IAM user who has, at minimum, the following AWS access permissions in addition to the permissions specified in [Prerequisites for configuring an on-premises instance](instances-on-premises-prerequisites.md). This makes it possible to download and install the CodeDeploy agent on the on-premises instance. The access permissions might look similar to this:
****
```
{
"Version":"2012-10-17",
"Statement" : [
{
"Effect" : "Allow",
"Action" : [
"codedeploy:*",
"iam:CreateAccessKey",
"iam:CreateUser",
"iam:DeleteAccessKey",
"iam:DeleteUser",
"iam:DeleteUserPolicy",
"iam:ListAccessKeys",
"iam:ListUserPolicies",
"iam:PutUserPolicy",
"iam:GetUser",
"tag:getTagKeys",
"tag:getTagValues",
"tag:GetResources"
],
"Resource" : "*"
},
{
"Effect" : "Allow",
"Action" : [
"s3:Get*",
"s3:List*"
],
"Resource" : [
"arn:aws:s3:::amzn-s3-demo-bucket/*",
"arn:aws:s3:::amzn-s3-demo-bucket1/*"
]
}
]
}
```
If you see access denied errors when trying to access one of the Amazon S3 buckets shown previously, try omitting the `/*` portion of the bucket's resource ARN, for example, `arn:aws:s3:::aws-codedeploy-sa-east-1`.
****
```
{
"Version":"2012-10-17",
"Statement" : [
{
"Effect" : "Allow",
"Action" : [
"codedeploy:*",
"iam:CreateAccessKey",
"iam:CreateUser",
"iam:DeleteAccessKey",
"iam:DeleteUser",
"iam:DeleteUserPolicy",
"iam:ListAccessKeys",
"iam:ListUserPolicies",
"iam:PutUserPolicy",
"iam:GetUser",
"tag:GetResources"
],
"Resource" : "*"
},
{
"Effect" : "Allow",
"Action" : [
"s3:Get*",
"s3:List*"
],
"Resource" : [
"arn:aws:s3:::amzn-s3-demo-bucket/*",
"arn:aws:s3:::amzn-s3-demo-bucket2/*"
]
}
]
}
```
## Step 2: Call the register command
For this step, we assume you are registering the on-premises instance from the on-premises instance itself. You can also register an on-premises instance from a separate device or instance that has the AWS CLI installed and configured as described in the preceding step.
Use the AWS CLI to call the [register](https://docs.aws.amazon.com/cli/latest/reference/deploy/register.html) command, specifying:
+ A name that uniquely identifies the on-premises instance to CodeDeploy (with the `--instance-name` option).
**Important**
To help identify the on-premises instance later, especially for debugging purposes, we strongly recommend that you use a name that maps to some unique characteristic of the on-premises instance (for example, the serial number or some unique internal asset identifier, if applicable). If you specify a MAC address for a name, be aware that MAC addresses contain characters that CodeDeploy does not allow, such as colon (`:`). For a list of allowed characters, see [CodeDeploy quotas](limits.md).
+ Optionally, the ARN of an existing IAM user that you want to associate with this on-premises instance (with the `--iam-user-arn` option). To get the ARN of an IAM user, call the [get-user](https://docs.aws.amazon.com/cli/latest/reference/iam/get-user.html) command, or choose the IAM user name in the **Users** section of the IAM console and then find the **User ARN** value in the **Summary** section. If this option is not specified, CodeDeploy will create an IAM user on your behalf in your AWS account and associate it with the on-premises instance.
**Important**
If you specify the `--iam-user-arn` option, you must also manually create the on-premises instance configuration file, as described in [Step 4: Add a configuration file to the on-premises instance](register-on-premises-instance-iam-user-arn.md#register-on-premises-instance-iam-user-arn-4).
You can associate only one IAM user with only one on-premises instance. Trying to associate a single IAM user with multiple on-premises instances can result in errors, failed deployments to those on-premises instances, or deployments to those on-premises instances that are stuck in a perpetual pending state.
+ Optionally, a set of on-premises instance tags (with the `--tags` option) that CodeDeploy will use to identify the set of Amazon EC2 instances to which to deploy. Specify each tag with `Key=tag-key,Value=tag-value` (for example, `Key=Name,Value=Beta Key=Name,Value=WestRegion`). If this option is not specified, no tags will be registered. To register tags later, call the [add-tags-to-on-premises-instances](https://docs.aws.amazon.com/cli/latest/reference/deploy/add-tags-to-on-premises-instances.html) command.
+ Optionally, the AWS region where the on-premises instance will be registered with CodeDeploy (with the `--region` option). This must be one of the supported regions listed in [Region and endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#codedeploy_region) in *AWS General Reference* (for example, `us-west-2`). If this option is not specified, the default AWS region associated with the calling IAM user will be used.
For example:
```
aws deploy register --instance-name AssetTag12010298EX --iam-user-arn arn:aws:iam::444455556666:user/CodeDeployUser-OnPrem --tags Key=Name,Value=CodeDeployDemo-OnPrem --region us-west-2
```
The **register** command does the following:
1. If no existing IAM user is specified, creates an IAM user, attaches the required permissions to it, and generates a corresponding secret key and secret access key. The on-premises instance will use this IAM user and its permissions and credentials to authenticate and interact with CodeDeploy.
1. Registers the on-premises instance with CodeDeploy.
1. If specified, associates in CodeDeploy the tags that are specified with the `--tags` option with the registered on-premises instance name.
1. If an IAM user was created, also creates the required configuration file in the same directory from which the **register** command was called.
If this command encounters any errors, an error message appears, describing how you can manually complete the remaining steps. Otherwise, a success message appears, describing how to call the **install** command as listed in the next step.
## Step 3: Call the install command
From the on-premises instance, use the AWS CLI to call the [install](https://docs.aws.amazon.com/cli/latest/reference/deploy/install.html) command, specifying:
+ The path to the configuration file (with the `--config-file` option).
+ Optionally, whether to replace the configuration file that already exists on the on-premises instance (with the `--override-config` option). If not specified, the existing configuration file will not be replaced.
+ Optionally, the AWS region where the on-premises instance will be registered with CodeDeploy (with the `--region` option). This must be one of the supported regions listed in [Region and endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#codedeploy_region) in *AWS General Reference* (for example, `us-west-2`). If this option is not specified, the default AWS region associated with the calling IAM user will be used.
+ Optionally, a custom location from which to install the CodeDeploy agent (with the `--agent-installer` option). This option is useful for installing a custom version of the CodeDeploy agent that CodeDeploy does not officially support (such as a custom version based on the [CodeDeploy agent](https://github.com/aws/aws-codedeploy-agent) repository in GitHub). The value must be the path to an Amazon S3 bucket that contains either:
+ A CodeDeploy agent installation script (for Linux- or Unix-based operating systems, similar to the install file in the [CodeDeploy agent](https://github.com/aws/aws-codedeploy-agent/blob/master/bin/install) repository in GitHub).
+ A CodeDeploy agent installer package (.msi) file (for Windows-based operating systems).
If this option is not specified, CodeDeploy will make its best attempt to install from its own location an officially supported version of the CodeDeploy agent that is compatible with the operating system on the on-premises instance.
For example:
```
aws deploy install --override-config --config-file /tmp/codedeploy.onpremises.yml --region us-west-2 --agent-installer s3://aws-codedeploy-us-west-2/latest/codedeploy-agent.msi
```
The **install** command does the following:
1. Checks whether the on-premises instance is an Amazon EC2 instance. If it is, an error message appears.
1. Copies the on-premises instances configuration file from the specified location on the instance to the location where the CodeDeploy agent expects to find it, provided that the file is not already in that location.
For Ubuntu Server and Red Hat Enterprise Linux (RHEL)), this is `/etc/codedeploy-agent/conf`/`codedeploy.onpremises.yml`.
For Windows Server, this is `C:\ProgramData\Amazon\CodeDeploy`\$1`conf.onpremises.yml`.
If the `--override-config` option was specified, creates or overwrites the file.
1. Installs the CodeDeploy agent on the on-premises instance and then starts it.
## Step 4: Deploy application revisions to the on-premises instance
You are now ready to deploy application revisions to the registered and tagged on-premises instance.
You deploy application revisions to on-premises instances in a way that's similar to deploying application revisions to Amazon EC2 instances. For instructions, see [Create a deployment with CodeDeploy](deployments-create.md). These instructions link to prerequisites, including creating an application, creating a deployment group, and preparing an application revision. If you need a simple sample application revision to deploy, you can create the one described in [Step 2: Create a sample application revision](tutorials-on-premises-instance-2-create-sample-revision.md) in the [Tutorial: Deploy an application to an on-premises instance with CodeDeploy (Windows Server, Ubuntu Server, or Red Hat Enterprise Linux)](tutorials-on-premises-instance.md).
**Important**
If you reuse an existing CodeDeploy service role as part of creating a deployment group that targets on-premises instances, you must include `Tag:get*` to the `Action` portion of the service role's policy statement. For more information, see [Step 2: Create a service role for CodeDeploy](getting-started-create-service-role.md).
## Step 5: Track deployments to the on-premises instance
After you deploy an application revision to registered and tagged on-premises instances, you can track the deployment's progress.
You track deployments to on-premises instances in a way that's similar to tracking deployments to Amazon EC2 instances. For instructions, see [View CodeDeploy deployment details](deployments-view-details.md).
For more options, see [Managing on-premises instances operations in CodeDeploy](on-premises-instances-operations.md).
# Use the register-on-premises-instance command (IAM user ARN) to register an on-premises instance
**Important**
Registering an instance using an IAM user is not recommended because it uses static (permanent) credentials for authentication. For improved security, we recommend registering an instance using temporary credentials for authentication. For more information, see [Use the register-on-premises-instance command (IAM Session ARN) to register an on-premises instance](register-on-premises-instance-iam-session-arn.md).
**Important**
Make sure you have a plan in place to rotate the IAM user's access keys (permanent credentials). For more information, see [Rotating access keys](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_credentials_access-keys.html#Using_RotateAccessKey).
Follow these instructions to configure an on-premises instance and register and tag it with CodeDeploy mostly on your own, using static IAM user credentials for authentication.
**Topics**
+ [Step 1: Create an IAM user for the on-premises instance](#register-on-premises-instance-iam-user-arn-1)
+ [Step 2: Assign permissions to the IAM user](#register-on-premises-instance-iam-user-arn-2)
+ [Step 3: Get the IAM user credentials](#register-on-premises-instance-iam-user-arn-3)
+ [Step 4: Add a configuration file to the on-premises instance](#register-on-premises-instance-iam-user-arn-4)
+ [Step 5: Install and configure the AWS CLI](#register-on-premises-instance-iam-user-arn-5)
+ [Step 6: Set the AWS\$1REGION environment variable (Ubuntu Server and RHEL only)](#register-on-premises-instance-iam-user-arn-6)
+ [Step 7: Install the CodeDeploy agent](#register-on-premises-instance-iam-user-arn-7)
+ [Step 8: Register the on-premises instance with CodeDeploy](#register-on-premises-instance-iam-user-arn-8)
+ [Step 9: Tag the on-premises instance](#register-on-premises-instance-iam-user-arn-9)
+ [Step 10: Deploy application revisions to the on-premises instance](#register-on-premises-instance-iam-user-arn-10)
+ [Step 11: Track deployments to the on-premises instance](#register-on-premises-instance-iam-user-arn-11)
## Step 1: Create an IAM user for the on-premises instance
Create an IAM user that the on-premises instance will use to authenticate and interact with CodeDeploy.
**Important**
You must create a separate IAM user for each participating on-premises instance. If you try to reuse an individual IAM user for multiple on-premises instances, you might not be able to successfully register or tag those on-premises instances with CodeDeploy. Deployments to those on-premises instances might be stuck in a perpetual pending state or fail altogether.
We recommend that you assign the IAM user a name that identifies its purpose, such as CodeDeployUser-OnPrem.
You can use the AWS CLI or the IAM console to create an IAM user. For information, see [Creating an IAM user in your AWS account](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html).
**Important**
Whether you use the AWS CLI or the IAM console to create a new IAM user, make a note of the user ARN provided for the user. You will need this information later in [Step 4: Add a configuration file to the on-premises instance](#register-on-premises-instance-iam-user-arn-4) and [Step 8: Register the on-premises instance with CodeDeploy](#register-on-premises-instance-iam-user-arn-8).
## Step 2: Assign permissions to the IAM user
If your on-premises instance will be deploying application revisions from Amazon S3 buckets, you must assign to the IAM user the permissions to interact with those buckets. You can use the AWS CLI or the IAM console to assign permissions.
**Note**
If you will be deploying application revisions only from GitHub repositories, skip this step and go directly to [Step 3: Get the IAM user credentials](#register-on-premises-instance-iam-user-arn-3). (You will still need information about the IAM user you created in [Step 1: Create an IAM user for the on-premises instance](#register-on-premises-instance-iam-user-arn-1). It will be used in later steps.)
**To assign permissions (CLI)**
1. Create a file with the following policy contents on the Amazon EC2 instance or device you are using to call the AWS CLI. Name the file something like **CodeDeploy-OnPrem-Permissions.json**, and then save the file.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:Get*",
"s3:List*"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
**Note**
We recommend that you restrict this policy to only those Amazon S3 buckets your on-premises instance needs to access. If you restrict this policy, make sure to also give access to the Amazon S3 buckets that contain the AWS CodeDeploy agent. Otherwise, an error might occur whenever the CodeDeploy agent is installed or updated on the associated on-premises instance.
For example:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:Get*",
"s3:List*"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/*",
"arn:aws:s3:::aws-codedeploy-us-east-2/*",
"arn:aws:s3:::aws-codedeploy-us-east-1/*",
"arn:aws:s3:::aws-codedeploy-us-west-1/*",
"arn:aws:s3:::aws-codedeploy-us-west-2/*",
"arn:aws:s3:::aws-codedeploy-ca-central-1/*",
"arn:aws:s3:::aws-codedeploy-eu-west-1/*",
"arn:aws:s3:::aws-codedeploy-eu-west-2/*",
"arn:aws:s3:::aws-codedeploy-eu-west-3/*",
"arn:aws:s3:::aws-codedeploy-eu-central-1/*",
"arn:aws:s3:::aws-codedeploy-eu-central-2/*",
"arn:aws:s3:::aws-codedeploy-eu-north-1/*",
"arn:aws:s3:::aws-codedeploy-eu-south-1/*",
"arn:aws:s3:::aws-codedeploy-eu-south-2/*",
"arn:aws:s3:::aws-codedeploy-il-central-1/*",
"arn:aws:s3:::aws-codedeploy-ap-east-1/*",
"arn:aws:s3:::aws-codedeploy-ap-northeast-1/*",
"arn:aws:s3:::aws-codedeploy-ap-northeast-2/*",
"arn:aws:s3:::aws-codedeploy-ap-northeast-3/*",
"arn:aws:s3:::aws-codedeploy-ap-southeast-1/*",
"arn:aws:s3:::aws-codedeploy-ap-southeast-2/*",
"arn:aws:s3:::aws-codedeploy-ap-southeast-3/*",
"arn:aws:s3:::aws-codedeploy-ap-southeast-4/*",
"arn:aws:s3:::aws-codedeploy-ap-south-1/*",
"arn:aws:s3:::aws-codedeploy-ap-south-2/*",
"arn:aws:s3:::aws-codedeploy-me-central-1/*",
"arn:aws:s3:::aws-codedeploy-me-south-1/*",
"arn:aws:s3:::aws-codedeploy-sa-east-1/*"
]
}
]
}
```
1. Call the [put-user-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/put-user-policy.html) command, specifying the name of the IAM user (with the `--user-name` option), a name for the policy (with the `--policy-name` option), and the path to the newly created policy document (with the `--policy-document` option). For example, assuming that the **CodeDeploy-OnPrem-Permissions.json** file is in the same directory (folder) from which you're calling this command:
**Important**
Be sure to include `file://` before the file name. It is required in this command.
```
aws iam put-user-policy --user-name CodeDeployUser-OnPrem --policy-name CodeDeploy-OnPrem-Permissions --policy-document file://CodeDeploy-OnPrem-Permissions.json
```
**To assign permissions (console)**
1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane, choose **Policies**, and then choose **Create Policy**. (If a **Get Started** button appears, choose it, and then choose **Create Policy**.)
1. Next to **Create Your Own Policy**, choose **Select**.
1. In the **Policy Name** box, type a name for this policy (for example, **CodeDeploy-OnPrem-Permissions**).
1. In the **Policy Document** box, type or paste the following permissions expression, which allows AWS CodeDeploy to deploy application revisions from any Amazon S3 bucket specified in the policy to the on-premises instance on behalf of the IAM user:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:Get*",
"s3:List*"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
1. Choose **Create Policy**.
1. In the navigation pane, choose **Users**.
1. In the list of users, browse to and choose the name of the IAM user you created in [Step 1: Create an IAM user for the on-premises instance](#register-on-premises-instance-iam-user-arn-1).
1. On the **Permissions** tab, in **Managed Policies**, choose **Attach Policy**.
1. Select the policy named **CodeDeploy-OnPrem-Permissions**, and then choose **Attach Policy**.
## Step 3: Get the IAM user credentials
Get the secret key ID and the secret access key for the IAM user. You will need them for [Step 4: Add a configuration file to the on-premises instance](#register-on-premises-instance-iam-user-arn-4). You can use the AWS CLI or the IAM console to get the secret key ID and the secret access key.
**Note**
If you already have the secret key ID and the secret access key, skip this step and go directly to [Step 4: Add a configuration file to the on-premises instance](#register-on-premises-instance-iam-user-arn-4).
Users need programmatic access if they want to interact with AWS outside of the AWS Management Console. The way to grant programmatic access depends on the type of user that's accessing AWS.
To grant users programmatic access, choose one of the following options.
****
| Which user needs programmatic access? | To | By |
| --- | --- | --- |
| IAM | (Recommended) Use console credentials as temporary credentials to sign programmatic requests to the AWS CLI, AWS SDKs, or AWS APIs. | Following the instructions for the interface that you want to use. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/register-on-premises-instance-iam-user-arn.html) |
| Workforce identity (Users managed in IAM Identity Center) | Use temporary credentials to sign programmatic requests to the AWS CLI, AWS SDKs, or AWS APIs. | Following the instructions for the interface that you want to use. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/register-on-premises-instance-iam-user-arn.html) |
| IAM | Use temporary credentials to sign programmatic requests to the AWS CLI, AWS SDKs, or AWS APIs. | Following the instructions in [Using temporary credentials with AWS resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html) in the IAM User Guide. |
| IAM | (Not recommended)Use long-term credentials to sign programmatic requests to the AWS CLI, AWS SDKs, or AWS APIs. | Following the instructions for the interface that you want to use. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/register-on-premises-instance-iam-user-arn.html) |
**To get the credentials (CLI)**
1. Call the [list-access-keys](https://docs.aws.amazon.com/cli/latest/reference/iam/list-access-keys.html) command, specifying the name of the IAM user (with the `--user-name` option) and querying for just the access key IDs (with the `--query` and `--output` options). For example:
```
aws iam list-access-keys --user-name CodeDeployUser-OnPrem --query "AccessKeyMetadata[*].AccessKeyId" --output text
```
1. If no keys appear in the output or information about only one key appears in the output, call the [create-access-key](https://docs.aws.amazon.com/cli/latest/reference/iam/create-access-key.html) command, specifying the name of the IAM user (with the `--user-name` option):
```
aws iam create-access-key --user-name CodeDeployUser-OnPrem
```
In the output of the call to the **create-access-key** command, note the value of the `AccessKeyId` and `SecretAccessKey` fields. You will need this information in [Step 4: Add a configuration file to the on-premises instance](#register-on-premises-instance-iam-user-arn-4).
**Important**
This will be the only time you will have access to this secret access key. If you forget or lose access to this secret access key, you will need to generate a new one by following the steps in [Step 3: Get the IAM user credentials](#register-on-premises-instance-iam-user-arn-3).
1. If two access keys are already listed, you must delete one of them by calling the [delete-access-key](https://docs.aws.amazon.com/cli/latest/reference/iam/delete-access-key.html) command, specifying the name of the IAM user (with the `--user-name` option), and the ID of the access key to delete (with the `--access-key-id` option). Then call the **create-access-key** command, as described earlier in this step. Here's an example of calling the **delete-access-key** command:
```
aws iam delete-access-key --user-name CodeDeployUser-OnPrem --access-key-id access-key-ID
```
**Important**
If you call the **delete-access-key** command to delete one of these access keys, and an on-premises instance is already using this access key as described in [Step 4: Add a configuration file to the on-premises instance](#register-on-premises-instance-iam-user-arn-4), you will need to follow the instructions in [Step 4: Add a configuration file to the on-premises instance](#register-on-premises-instance-iam-user-arn-4) again to specify a different access key ID and secret access key associated with this IAM user. Otherwise, any deployments to that on-premises instance might be stuck in a perpetual pending state or fail altogether.
**To get the credentials (console)**
1.
1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. If the list of users is not displayed, in the navigation pane, choose **Users**.
1. In the list of users, browse to and choose the name of the IAM user you created in [Step 1: Create an IAM user for the on-premises instance](#register-on-premises-instance-iam-user-arn-1).
1. On the **Security credentials** tab, if no keys or only one key is listed, choose **Create access key**.
If two access keys are listed, you must delete one of them. Choose **Delete** next to one of the access keys, and then choose **Create access key**.
**Important**
If you choose **Delete** next to one of these access keys, and an on-premises instance is already using this access key as described in [Step 4: Add a configuration file to the on-premises instance](#register-on-premises-instance-iam-user-arn-4), you will need to follow the instructions in [Step 4: Add a configuration file to the on-premises instance](#register-on-premises-instance-iam-user-arn-4) again to specify a different access key ID and secret access key associated with this IAM user. Otherwise, deployments to that on-premises instance might be stuck in a perpetual pending state or fail altogether.
1. Choose **Show** and note the access key ID and secret access key. You will need this information for the next step. Alternatively, you can choose **Download .csv file** to save a copy of the access key ID and the secret access key.
**Important**
Unless you make a note of or download the credentials, this will be the only time you will have access to this secret access key. If you forget or lose access to this secret access key, you will need to generate a new one by following the steps in [Step 3: Get the IAM user credentials](#register-on-premises-instance-iam-user-arn-3).
1. Choose **Close** to return to the **Users > *IAM User Name*** page.
## Step 4: Add a configuration file to the on-premises instance
Add a configuration file to the on-premises instance, using root or administrator permissions. This configuration file will be used to declare the IAM user credentials and the target AWS region to be used for CodeDeploy. The file must be added to a specific location on the on-premises instance. The file must include the IAM user's ARN, secret key ID, secret access key, and the target AWS region. The file must follow a specific format.
1. Create a file named `codedeploy.onpremises.yml` (for an Ubuntu Server or RHEL on-premises instance) or `conf.onpremises.yml` (for a Windows Server on-premises instance) in the following location on the on-premises instance:
+ For Ubuntu Server: `/etc/codedeploy-agent/conf`
+ For Windows Server: `C:\ProgramData\Amazon\CodeDeploy`
1. Use a text editor to add the following information to the newly created `codedeploy.onpremises.yml` or `conf.onpremises.yml` file:
```
---
aws_access_key_id: secret-key-id
aws_secret_access_key: secret-access-key
iam_user_arn: iam-user-arn
region: supported-region
```
Where:
+ *secret-key-id* is the corresponding IAM user's secret key ID you noted in [Step 1: Create an IAM user for the on-premises instance](#register-on-premises-instance-iam-user-arn-1) or [Step 3: Get the IAM user credentials](#register-on-premises-instance-iam-user-arn-3).
+ *secret-access-key* is the corresponding IAM user's secret access key you noted in [Step 1: Create an IAM user for the on-premises instance](#register-on-premises-instance-iam-user-arn-1) or [Step 3: Get the IAM user credentials](#register-on-premises-instance-iam-user-arn-3).
+ *iam-user-arn* is the IAM user's ARN you noted earlier in [Step 1: Create an IAM user for the on-premises instance](#register-on-premises-instance-iam-user-arn-1).
+ *supported-region* is the identifier of a region supported by CodeDeploy where your CodeDeploy applications, deployment groups, and application revisions are located (for example, `us-west-2`). For a list of regions, see [Region and endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#codedeploy_region) in the *AWS General Reference*.
**Important**
If you chose **Delete** next to one of the access keys in [Step 3: Get the IAM user credentials](#register-on-premises-instance-iam-user-arn-3), and your on-premises instance is already using the associated access key ID and secret access key, you will need to follow the instructions in [Step 4: Add a configuration file to the on-premises instance](#register-on-premises-instance-iam-user-arn-4) to specify a different access key ID and secret access key associated with this IAM user. Otherwise, any deployments to your on-premises instance might be stuck in a perpetual pending state or fail altogether.
## Step 5: Install and configure the AWS CLI
Install and configure the AWS CLI on the on-premises instance. (The AWS CLI will be used in [Step 7: Install the CodeDeploy agent](#register-on-premises-instance-iam-user-arn-7) to download and install the CodeDeploy agent on the on-premises instance.)
1. To install the AWS CLI on the on-premises instance, follow the instructions in [Getting set up with the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-set-up.html) in the *AWS Command Line Interface User Guide*.
**Note**
CodeDeploy commands for working with on-premises instances became available in version 1.7.19 of the AWS CLI. If you have a version of the AWS CLI already installed, you can check its version by calling **aws --version**.
1. To configure the AWS CLI on the on-premises instance, follow the instructions in [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) in the *AWS Command Line Interface User Guide*.
**Important**
As you configure the AWS CLI (for example, by calling the **aws configure** command), be sure to specify the secret key ID and secret access key of an IAM user that has, at minimum, the following AWS access permissions in addition to the access permissions specified in the [Prerequisites for configuring an on-premises instance](instances-on-premises-prerequisites.md). This makes it possible for you to download and install the CodeDeploy agent on the on-premises instance:
****
```
{
"Version":"2012-10-17",
"Statement" : [
{
"Effect" : "Allow",
"Action" : [
"codedeploy:*"
],
"Resource" : "*"
},
{
"Effect" : "Allow",
"Action" : [
"s3:Get*",
"s3:List*"
],
"Resource" : [
"arn:aws:s3:::amzn-s3-demo-bucket/*",
"arn:aws:s3:::amzn-s3-demo-bucket1/*"
]
}
]
}
```
****
```
{
"Version":"2012-10-17",
"Statement" : [
{
"Effect" : "Allow",
"Action" : [
"codedeploy:*"
],
"Resource" : "*"
},
{
"Effect" : "Allow",
"Action" : [
"s3:Get*",
"s3:List*"
],
"Resource" : [
"*"
]
}
]
}
```
These access permissions can be assigned to either the IAM user you created in [Step 1: Create an IAM user for the on-premises instance](#register-on-premises-instance-iam-user-arn-1) or to a different IAM user. To assign these permissions to an IAM user, follow the instructions in [Step 1: Create an IAM user for the on-premises instance](#register-on-premises-instance-iam-user-arn-1), using these access permissions instead of the ones in that step.
## Step 6: Set the AWS\$1REGION environment variable (Ubuntu Server and RHEL only)
If you are not running Ubuntu Server or RHEL on your on-premises instance, skip this step and go directly to [Step 7: Install the CodeDeploy agent](#register-on-premises-instance-iam-user-arn-7).
Install the CodeDeploy agent on an Ubuntu Server or RHEL on-premises instance and enable the instance to update the CodeDeploy agent whenever a new version becomes available. You do this by setting the `AWS_REGION` environment variable on the instance to the identifier of one of the regions supported by CodeDeploy. We recommend that you set the value to the region where your CodeDeploy applications, deployment groups, and application revisions are located (for example, `us-west-2`). For a list of regions, see [Region and endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#codedeploy_region) in the *AWS General Reference*.
To set the environment variable, call the following from the terminal:
```
export AWS_REGION=supported-region
```
Where *supported-region* is the region identifier (for example, `us-west-2`).
## Step 7: Install the CodeDeploy agent
Install the CodeDeploy agent on the on-premises instance:
+ For an Ubuntu Server on-premises instance, follow the instructions in [Install the CodeDeploy agent for Ubuntu Server](codedeploy-agent-operations-install-ubuntu.md), and then return to this page.
+ For a RHEL on-premises instance, follow the instructions in [Install the CodeDeploy agent for Amazon Linux or RHEL](codedeploy-agent-operations-install-linux.md), and then return to this page.
+ For a Windows Server on-premises instance, follow the instructions in [Install the CodeDeploy agent for Windows Server](codedeploy-agent-operations-install-windows.md), and then return to this page.
## Step 8: Register the on-premises instance with CodeDeploy
The instructions in this step assume you are registering the on-premises instance from the on-premises instance itself. You can register an on-premises instance from a separate device or instance that has the AWS CLI installed and configured, as described in [Step 5: Install and configure the AWS CLI](#register-on-premises-instance-iam-user-arn-5).
Use the AWS CLI to register the on-premises instance with CodeDeploy so that it can be used in deployments.
1. Before you can use the AWS CLI, you will need the user ARN of the IAM user you created in [Step 1: Create an IAM user for the on-premises instance](#register-on-premises-instance-iam-user-arn-1). If you don't already have the user ARN, call the [get-user](https://docs.aws.amazon.com/cli/latest/reference/iam/get-user.html) command, specifying the name of the IAM user (with the `--user-name` option) and querying for just the user ARN (with the `--query` and `--output` options):
```
aws iam get-user --user-name CodeDeployUser-OnPrem --query "User.Arn" --output text
```
1. Call the [register-on-premises-instance](https://docs.aws.amazon.com/cli/latest/reference/deploy/register-on-premises-instance.html) command, specifying:
+ A name that uniquely identifies the on-premises instance (with the `--instance-name` option).
**Important**
To help identify the on-premises instance, especially for debugging purposes, we strongly recommend that you specify a name that maps to some unique characteristic of the on-premises instance (for example, the serial number or an internal asset identifier, if applicable). If you specify a MAC address as a name, be aware that MAC addresses contain characters that CodeDeploy does not allow, such as colon (`:`). For a list of allowed characters, see [CodeDeploy quotas](limits.md).
+ The user ARN of the IAM user you created in [Step 1: Create an IAM user for the on-premises instance](#register-on-premises-instance-iam-user-arn-1) (with the `--iam-user-arn` option).
For example:
```
aws deploy register-on-premises-instance --instance-name AssetTag12010298EX --iam-user-arn arn:aws:iam::444455556666:user/CodeDeployUser-OnPrem
```
## Step 9: Tag the on-premises instance
You can use either the AWS CLI or the CodeDeploy console to tag the on-premises instance. (CodeDeploy uses on-premises instance tags to identify the deployment targets during a deployment.)
**To tag the on-premises instance (CLI)**
+ Call the [add-tags-to-on-premises-instances](https://docs.aws.amazon.com/cli/latest/reference/deploy/add-tags-to-on-premises-instances.html) command, specifying:
+ The name that uniquely identifies the on-premises instance (with the `--instance-names` option).
+ The name of the on-premises instance tag key and tag value you want to use (with the `--tags` option). You must specify both a name and value. CodeDeploy does not allow on-premises instance tags that have values only.
For example:
```
aws deploy add-tags-to-on-premises-instances --instance-names AssetTag12010298EX --tags Key=Name,Value=CodeDeployDemo-OnPrem
```
**To tag the on-premises instance (console)**
1. Sign in to the AWS Management Console and open the CodeDeploy console at [https://console.aws.amazon.com/codedeploy](https://console.aws.amazon.com/codedeploy).
**Note**
Sign in with the same user that you set up in [Getting started with CodeDeploy](getting-started-codedeploy.md).
1. From the CodeDeploy menu, choose **On-premises instances**.
1. In the list of on-premises instances, choose the arrow next to the on-premises instance you want to tag.
1. In the list of tags, select or enter the desired tag key and tag value. After you enter the tag key and tag value, another row appears. You can repeat this for up to 10 tags. To remove a tag, choose the delete icon (![\[The delete icon.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/delete-triggers-x.png)).
1. After you have added tags, choose **Update Tags**.
## Step 10: Deploy application revisions to the on-premises instance
You are now ready to deploy application revisions to the registered and tagged on-premises instance.
You deploy application revisions to on-premises instances in a way that's similar to deploying application revisions to Amazon EC2 instances. For instructions, see [Create a deployment with CodeDeploy](deployments-create.md). These instructions include a link to prerequisites, including creating an application, creating a deployment group, and preparing an application revision. If you need a simple sample application revision to deploy, you can create the one described in [Step 2: Create a sample application revision](tutorials-on-premises-instance-2-create-sample-revision.md) in the [Tutorial: Deploy an application to an on-premises instance with CodeDeploy (Windows Server, Ubuntu Server, or Red Hat Enterprise Linux)](tutorials-on-premises-instance.md).
**Important**
If you reuse a CodeDeploy service role as part of creating a deployment group that targets on-premises instances, you must include `Tag:get*` to the `Action` portion of the service role's policy statement. For more information, see [Step 2: Create a service role for CodeDeploy](getting-started-create-service-role.md).
## Step 11: Track deployments to the on-premises instance
After you deploy an application revision to registered and tagged on-premises instances, you can track the deployment's progress.
You track deployments to on-premises instances in a way that's similar to tracking deployments to Amazon EC2 instances. For instructions, see [View CodeDeploy deployment details](deployments-view-details.md).
# Managing on-premises instances operations in CodeDeploy
Follow the instructions in this section to manage operations on your on-premises instances after you have registered them with CodeDeploy, such as getting more information about, removing tags from, and uninstalling and deregistering on-premises instances.
**Topics**
+ [Get information about a single on-premises instance](on-premises-instances-operations-view-details-single.md)
+ [Get information about multiple on-premises instances](on-premises-instances-operations-view-details-multiple.md)
+ [Manually remove on-premises instance tags from an on-premises instance](on-premises-instances-operations-remove-tags.md)
+ [Automatically uninstall the CodeDeploy agent and remove the configuration file from an on-premises instance](on-premises-instances-operations-uninstall-agent.md)
+ [Automatically deregister an on-premises instance](on-premises-instances-operations-deregister-automatically.md)
+ [Manually deregister an on-premises instance](on-premises-instances-operations-deregister-manually.md)
# Get information about a single on-premises instance
You can get information about a single on-premises instance by following the instructions in [View CodeDeploy deployment details](deployments-view-details.md). You can use the AWS CLI or the CodeDeploy console to get more information about a single on-premises instance.
**To get information about a single on-premises instance (CLI)**
+ Call the [get-on-premises-instance](https://docs.aws.amazon.com/cli/latest/reference/deploy/get-on-premises-instance.html) command, specifying the name that uniquely identifies the on-premises instance (with the `--instance-name` option):
```
aws deploy get-on-premises-instance --instance-name AssetTag12010298EX
```
**To get information about a single on-premises instance (console)**
1. Sign in to the AWS Management Console and open the CodeDeploy console at [https://console.aws.amazon.com/codedeploy](https://console.aws.amazon.com/codedeploy).
**Note**
Sign in with the same user that you set up in [Getting started with CodeDeploy](getting-started-codedeploy.md).
1. In the navigation pane, expand **Deploy**, and choose **On-premises instances**.
1. In the list of on-premises instances, choose the name of an on-premises instance to view its detail.
# Get information about multiple on-premises instances
You can get information about on-premises instances by following the instructions in [View CodeDeploy deployment details](deployments-view-details.md). You can use the AWS CLI or the CodeDeploy console to get more information about on-premises instances.
**To get information about multiple on-premises instances (CLI)**
1. For a list of on-premises instance names, call the [list-on-premises-instances](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-on-premises-instances.html) command, specifying:
+ Whether to get information about all registered or deregistered on-premises instances (with the `--registration-status` option and `Registered` or `Deregistered`, respectively). If you omit this, then both registered and deregistered on-premises instance names are returned.
+ Whether to get information only about on-premises instances tagged with specific on-premises instance tags (with the `--tag-filters` option). For each on-premises instance tag, specify the `Key`, `Value`, and `Type` (which should always be `KEY_AND_VALUE`). Separate multiple on-premises instance tags with spaces between each `Key`, `Value`, and `Type` triplet.
For example:
```
aws deploy list-on-premises-instances --registration-status Registered --tag-filters Key=Name,Value=CodeDeployDemo-OnPrem,Type=KEY_AND_VALUE Key=Name,Value=CodeDeployDemo-OnPrem-Beta,Type=KEY_AND_VALUE
```
1. For more detailed information, call the [batch-get-on-premises-instances](https://docs.aws.amazon.com/cli/latest/reference/deploy/batch-get-on-premises-instances.html) command, with the names of the on-premises instances (with the `--instance-names` option):
```
aws deploy batch-get-on-premises-instances --instance-names AssetTag12010298EX AssetTag09920444EX
```
**To get information about multiple on-premises instances (console)**
1. Sign in to the AWS Management Console and open the CodeDeploy console at [https://console.aws.amazon.com/codedeploy](https://console.aws.amazon.com/codedeploy).
**Note**
Sign in with the same user that you set up in [Getting started with CodeDeploy](getting-started-codedeploy.md).
1. In the navigation pane, expand **Deploy**, and choose **On-premises instances**.
Information about the on-premises instances is displayed.
# Manually remove on-premises instance tags from an on-premises instance
Typically, you remove an on-premises instance tag from an on-premises instance when that tag is no longer being used, or you want to remove the on-premises instance from any deployment groups that rely on that tag. You can use the AWS CLI or the AWS CodeDeploy console to remove on-premises instance tags from on-premises instances.
You do not need to remove the on-premises instance tags from an on-premises instance before you deregister it.
Manually removing on-premises instance tags from an on-premises instance does not deregister the instance. It does not uninstall the CodeDeploy agent from the instance. It does not remove the configuration file from the instance. It does not delete the IAM user associated with the instance.
To automatically deregister the on-premises instance, see [Automatically deregister an on-premises instance](on-premises-instances-operations-deregister-automatically.md).
To manually deregister the on-premises instance, see [Manually deregister an on-premises instance](on-premises-instances-operations-deregister-manually.md).
To automatically uninstall the CodeDeploy agent and remove the configuration file from the on-premises instance, see [Automatically uninstall the CodeDeploy agent and remove the configuration file from an on-premises instance](on-premises-instances-operations-uninstall-agent.md).
To manually uninstall just the CodeDeploy agent from the on-premises instance, see [Managing CodeDeploy agent operations](codedeploy-agent-operations.md).
To manually delete the associated IAM user, see [Deleting an IAM user from your AWS account](https://docs.aws.amazon.com/IAM/latest/UserGuide/Using_DeletingUserFromAccount.html).
**To remove on-premises instance tags from an on-premises instance (CLI)**
+ Call the [remove-tags-from-on-premises-instances](https://docs.aws.amazon.com/cli/latest/reference/deploy/remove-tags-from-on-premises-instances.html), specifying:
+ The names that uniquely identify the on-premises instance (with the `--instance-names` option).
+ The names and values of the tags you want to remove (with the `--tags` option).
For example:
```
aws deploy remove-tags-from-on-premises-instances --instance-names AssetTag12010298EX --tags Key=Name,Value=CodeDeployDemo-OnPrem
```
**To remove on-premises instance tags from an on-premises instance (console)**
1. Sign in to the AWS Management Console and open the CodeDeploy console at [https://console.aws.amazon.com/codedeploy](https://console.aws.amazon.com/codedeploy).
**Note**
Sign in with the same user that you set up in [Getting started with CodeDeploy](getting-started-codedeploy.md).
1. In the navigation pane, expand **Deploy**, and choose **On-premises instances**.
1. In the list of on-premises instances, choose the name of the on-premises instance from which you want to remove tags.
1. In **Tags**, choose **Remove** next to each tag you want to remove.
1. After you have deleted the tags, choose **Update tags**.
# Automatically uninstall the CodeDeploy agent and remove the configuration file from an on-premises instance
Typically, you uninstall the CodeDeploy agent and remove the configuration file from an on-premises instance after you're no longer planning to deploy to it.
**Note**
Automatically uninstalling the CodeDeploy agent and removing the configuration file from an on-premises instance does not deregister an on-premises instance. It does not disassociate any on-premises instance tags associated with the on-premises instance. It does not delete the IAM user associated with the on-premises instance.
To automatically deregister the on-premises instance, see [Automatically deregister an on-premises instance](on-premises-instances-operations-deregister-automatically.md).
To manually deregister the on-premises instance, see [Manually deregister an on-premises instance](on-premises-instances-operations-deregister-manually.md).
To manually disassociate any associated on-premises instance tags, see [Manually remove on-premises instance tags from an on-premises instance](on-premises-instances-operations-remove-tags.md).
To manually uninstall the CodeDeploy agent from the on-premises instance, see [Managing CodeDeploy agent operations](codedeploy-agent-operations.md).
To manually delete the associated IAM user, see [Deleting an IAM user from your AWS account](https://docs.aws.amazon.com/IAM/latest/UserGuide/Using_DeletingUserFromAccount.html).
From the on-premises instance, use the AWS CLI to call the [uninstall](https://docs.aws.amazon.com/cli/latest/reference/deploy/uninstall.html) command.
For example:
```
aws deploy uninstall
```
The **uninstall** command does the following:
1. Stops the running CodeDeploy agent on the on-premises instance.
1. Uninstalls the CodeDeploy agent from the on-premises instance.
1. Removes the configuration file from the on-premises instance. (For Ubuntu Server and RHEL, this is `/etc/codedeploy-agent/conf`/`codedeploy.onpremises.yml`. For Windows Server, this is `C:\ProgramData\Amazon\CodeDeploy`\$1`conf.onpremises.yml`.)
# Automatically deregister an on-premises instance
Typically, you deregister an on-premises instance after you're no longer planning to deploy to it. When you deregister an on-premises instance, even though the on-premises instance might be part of a deployment group's on-premises instance tags, the on-premises instance will not be included in any deployments. You can use the AWS CLI to deregister on-premises instances.
**Note**
You cannot use the CodeDeploy console to deregister an on-premises instance. Also, deregistering an on-premises instance removes any on-premises instance tags that are associated with the on-premises instance. It does not uninstall the CodeDeploy agent from the on-premises instance. It does not remove the on-premises instance configuration file from the on-premises instance.
To use the CodeDeploy console to perform some (but not all) of the activities in this section, see the CodeDeploy console section of [Manually deregister an on-premises instance](on-premises-instances-operations-deregister-manually.md).
To manually disassociate any associated on-premises instance tags, see [Manually remove on-premises instance tags from an on-premises instance](on-premises-instances-operations-remove-tags.md).
To automatically uninstall the CodeDeploy agent and remove the configuration file from the on-premises instance, see [Automatically uninstall the CodeDeploy agent and remove the configuration file from an on-premises instance](on-premises-instances-operations-uninstall-agent.md).
To manually uninstall only the CodeDeploy agent from the on-premises instance, see [Managing CodeDeploy agent operations](codedeploy-agent-operations.md).
Use the AWS CLI to call the [deregister](https://docs.aws.amazon.com/cli/latest/reference/deploy/deregister.html) command, specifying:
+ The name that uniquely identifies the on-premises instance to CodeDeploy (with the `--instance-name` option).
+ Optionally, whether to delete the IAM user associated with the on-premises instance. The default behaviour is to delete the IAM user. If you do not want to delete the IAM user associated with the on-premises instance, specify the `--no-delete-iam-user` option in the command.
+ Optionally, the AWS region where the on-premises instance was registered with CodeDeploy (with the `--region` option). This must be one of the supported regions listed in [Region and endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#codedeploy_region) in the *AWS General Reference* (for example, `us-west-2`). If this option is not specified, the default AWS region associated with the calling IAM user will be used.
An example that degisters an instance and deletes the user:
```
aws deploy deregister --instance-name AssetTag12010298EX --region us-west-2
```
An example that degisters an instance and does not delete the user:
```
aws deploy deregister --instance-name AssetTag12010298EX --no-delete-iam-user --region us-west-2
```
The **deregister** command does the following:
1. Deregisters the on-premises instance with CodeDeploy.
1. If specified, deletes the IAM user associated with the on-premises instance.
After you deregister an on-premises instance:
+ It stops appearing in the console immediately.
+ You can create another instance with the same name immediately.
If this command encounters any errors, an error message appears, describing how you can manually complete the remaining steps. Otherwise, a success message appears, describing how to call the **uninstall** command.
# Manually deregister an on-premises instance
Typically, you deregister an on-premises instance after you're no longer planning to deploy to it. You use the AWS CLI to manually deregister on-premises instances.
Manually deregistering an on-premises instance does not uninstall the CodeDeploy agent. It does not remove the configuration file from the instance. It does not delete the IAM user associated with the instance. It does not remove any tags associated with the instance.
To automatically uninstall the CodeDeploy agent and remove the configuration file from the on-premises instance, see [Automatically uninstall the CodeDeploy agent and remove the configuration file from an on-premises instance](on-premises-instances-operations-uninstall-agent.md).
To manually uninstall only the CodeDeploy agent, see [Managing CodeDeploy agent operations](codedeploy-agent-operations.md).
To manually delete the associated IAM user, see [Deleting an IAM user from your AWS account](https://docs.aws.amazon.com/IAM/latest/UserGuide/Using_DeletingUserFromAccount.html).
To manually remove only the associated on-premises instance tags, see [Manually remove on-premises instance tags from an on-premises instance](on-premises-instances-operations-remove-tags.md).
+ Call the [deregister-on-premises-instance](https://docs.aws.amazon.com/cli/latest/reference/deploy/deregister-on-premises-instance.html) command, specifying the name that uniquely identifies the on-premises instance (with the `--instance-name` option):
```
aws deploy deregister-on-premises-instance --instance-name AssetTag12010298EX
```
After you deregister an on-premises instance:
+ It stops appearing in the console immediately.
+ You can create another instance with the same name immediately.
# View instance details with CodeDeploy
You can use the CodeDeploy console, the AWS CLI, or the CodeDeploy APIs to view details about instances used in a deployment.
For information about using CodeDeploy API actions to view instances, see [GetDeploymentInstance](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_GetDeploymentInstance.html), [ListDeploymentInstances](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_ListDeploymentInstances.html), and [ListOnPremisesInstances](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_ListOnPremisesInstances.html).
**Topics**
+ [View instance details (console)](#instances-view-details-console)
+ [View instance details (CLI)](#instances-view-details-cli)
## View instance details (console)
To view instance details:
1. Sign in to the AWS Management Console and open the CodeDeploy console at [https://console.aws.amazon.com/codedeploy](https://console.aws.amazon.com/codedeploy).
**Note**
Sign in with the same user that you set up in [Getting started with CodeDeploy](getting-started-codedeploy.md).
1. In the navigation pane, expand **Deploy**, and then choose **Deployments**.
**Note**
If no entries are displayed, make sure the correct region is selected. On the navigation bar, in the region selector, choose one of the regions listed in [Region and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#codedeploy_region) in the *AWS General Reference*. CodeDeploy is supported in these regions only.
1. To display deployment details, choose the deployment ID for the instance.
1. You can view all instances in the **Instance activity** section of the deployment's page.
1. To see information about individual deployment lifecycle events for an instance, on the deployment details page, in the **Events** column, choose **View events**.
**Note**
If **Failed** is displayed for any of the lifecycle events, on the instance details page, choose **View logs**, **View in EC2**, or both. You can find troubleshooting tips in [Troubleshoot instance issues](troubleshooting-ec2-instances.md).
1. If you want to see more information about an Amazon EC2 instance, choose the ID of the instance in the **Instance ID** column.
## View instance details (CLI)
To use the AWS CLI to view instance details, call either the `get-deployment-instance` command or the `list-deployment-instances` command.
To view details about a single instance, call the [get-deployment-instance](https://docs.aws.amazon.com/cli/latest/reference/deploy/get-deployment-instance.html) command, specifying:
+ The unique deployment ID. To get the deployment ID, call the [list-deployments](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-deployments.html) command.
+ The unique instance ID. To get the instance ID, call the [list-deployment-instances](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-deployment-instances.html) command.
To view a list of IDs for instances used in a deployment, call the [list-deployment-instances](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-deployment-instances.html) command, specifying:
+ The unique deployment ID. To get the deployment ID, call the [list-deployments](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-deployments.html) command.
+ Optionally, whether to include only specific instance IDs by their deployment status. (If not specified, all matching instance IDs will be listed, regardless of their deployment status.)
# CodeDeploy instance health
CodeDeploy monitors the health status of the instances in a deployment group. It fails deployments if the number of healthy instances falls below the minimum number of healthy instances that have been specified for the deployment group during a deployment. For example, if 85% of instances must remain healthy during a deployment, and the deployment group contains 10 instances, the overall deployment will fail if deployment to even a single instance fails. This is because when an instance is taken offline so the latest application revision can be installed, the available healthy instance counts already drops to 90%. A failed instance plus another offline instance would mean that only 80% of instances are healthy and available. CodeDeploy will fail the overall deployment.
It is important to remember that for the overall deployment to succeed, the following must be true:
+ CodeDeploy is able to deploy to each instance in the deployment.
+ Deployment to at least one instance must succeed. This means that even if the minimum healthy hosts value is 0, deployment to at least one instance must succeed (that is, at least one instance must be healthy) for the overall deployment to succeed.
**Topics**
+ [Health status](#instances-health-status)
+ [About the minimum number of healthy instances](#minimum-healthy-hosts)
+ [About the minimum number of healthy instances per Availability Zone](#minimum-healthy-hosts-az)
## Health status
CodeDeploy assigns two health status values to each instance: *revision health* and *instance health*.
Revision health
Revision health is based on the application revision currently installed on the instance. It has the following status values:
+ Current: The revision installed on the instance matches the revision for the deployment group's last successful deployment.
+ Old: The revision installed on the instance matches an older version of the application.
+ Unknown: The application revision has not been installed successfully on the instance.
Instance health
Instance health is based on whether deployments to an instance have been successful. It has the following values:
+ Healthy: The last deployment to the instance was successful.
+ Unhealthy: The attempt to deploy a revision to the instance failed, or a revision has not yet been deployed to the instance.
CodeDeploy uses revision health and instance health to schedule the deployment to the deployment group's instances in the following order:
1. Unhealthy instance health.
1. Unknown revision health.
1. Old revision health.
1. Current revision health.
If the overall deployment succeeds, the revision is updated and the deployment group's health status values are updated to reflect the latest deployment.
+ All current instances that had a successful deployment remain current. Otherwise, they become unknown.
+ All old or unknown instances that had a successful deployment become current. Otherwise, they remain old or unknown.
+ All healthy instances that had a successful deployment remain healthy. Otherwise, they become unhealthy.
+ All unhealthy instances that had a successful deployment become healthy. Otherwise, they remain unhealthy.
If the overall deployment fails or is stopped:
+ Each instance to which CodeDeploy attempted to deploy the application revision has its instance health set to healthy or unhealthy, depending on whether the deployment attempt for that instance succeeded or failed.
+ Each instance to which CodeDeploy did not attempt to deploy the application revision retains its current instance health value.
+ The deployment group's revision remains the same.
## About the minimum number of healthy instances
The required minimum number of healthy instances is defined as part of a deployment configuration.
**Important**
During a blue/green deployment, the deployment configuration and minimum healthy hosts value apply to instances in the replacement environment, not those in the original environment. However, when instances in the original environment are deregistered from the load balancer, the overall deployment is marked as Failed if even a single original instance fails to be deregistered successfully.
CodeDeploy provides three default deployment configurations that have commonly used minimum healthy host values:
| Default deployment configuration name | Predefined minimum healthy hosts value |
| --- | --- |
| CodeDeployDefault.OneAtATime | 1 |
| CodeDeployDefault.HalfAtATime | 50% |
| CodeDeployDefault.AllAtOnce | 0 |
You'll find more information about default deployment configurations in [Working with deployment configurations in CodeDeploy](deployment-configurations.md).
You can create custom deployment configurations in CodeDeploy to define your own minimum healthy host values. You can define these values as whole numbers or percentages when using the following operations:
+ As `minimum-healthy-hosts` when you use the [create-deployment-config](https://docs.aws.amazon.com/cli/latest/reference/deploy/create-deployment-config.html) command in the AWS CLI.
+ As `Value` in the [MinimumHealthyHosts](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_MinimumHealthyHosts.html) data type in the CodeDeploy API.
+ As `MinimumHealthyHosts` when you use [AWS::CodeDeploy::DeploymentConfig](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codedeploy-deploymentconfig.html) in an CloudFormation template.
CodeDeploy allows you to specify a minimum number of healthy instances for the deployment for two main purposes:
+ To determine whether the overall deployment succeeds or fails. Deployment succeeds if the application revision was successfully deployed to at least the minimum number of healthy instances.
+ To determine the number of instances that must be healthy during a deployment to allow the deployment to proceed.
You can specify the minimum number of healthy instances for your deployment group as a number of instances or as a percentage of the total number of instances. If you specify a percentage, then at the start of the deployment, CodeDeploy converts the percentage to the equivalent number of instances, rounding up any fractional instances.
CodeDeploy tracks the health status of the deployment group's instances during the deployment process and uses the deployment's specified minimum number of healthy instances to determine whether to continue the deployment. The basic principle is that a deployment must never cause the number of healthy instances to fall below the minimum number you have specified. The one exception to this rule is when a deployment group initially has less than the specified minimum number of healthy instances. In that case, the deployment process does not reduce the number of healthy instances any further.
**Note**
CodeDeploy will attempt to deploy to all instances in a deployment group, even those that are currently in a Stopped state. In the minimum healthy host calculation, a stopped instance has the same impact as a failed instance. To resolve deployment failures due to too many stopped instances, either restart instances or change their tags to exclude them from the deployment group.
CodeDeploy starts the deployment process by attempting to deploy the application revision to the deployment group's unhealthy instances. For each successful deployment, CodeDeploy changes the instance's health status to healthy and adds it to the deployment group's healthy instances. CodeDeploy then compares the current number of healthy instances to the specified minimum number of healthy instances.
+ If the number of healthy instances is less than or equal to the specified minimum number of healthy instances, CodeDeploy cancels the deployment to ensure the number of healthy instances doesn't decrease with more deployments.
+ If the number of healthy instances is greater than the specified minimum number of healthy instances by at least one, CodeDeploy deploys the application revision to the original set of healthy instances.
If a deployment to a healthy instance fails, CodeDeploy changes that instance's health status to unhealthy. As the deployment progresses, CodeDeploy updates the current number of healthy instances and compares it to the specified minimum number of healthy instances. If the number of healthy instances falls to the specified minimum number at any point in the deployment process, CodeDeploy stops the deployment. This practice prevents the possibility the next deployment will fail, dropping the number of healthy instances below the specified minimum number.
**Note**
Make sure the minimum number of healthy instances you specify is less than the total number of instances in the deployment group. If you specify a percentage value, remember it will be rounded up. Otherwise, when the deployment starts, the number of healthy instances will already be less than or equal to the specified minimum number of healthy instances, and CodeDeploy will immediately fail the overall deployment.
CodeDeploy also uses the specified minimum number of healthy instances and the actual number of healthy instances to determine whether and how to deploy the application revision to multiple instances. By default, CodeDeploy deploys the application revision to as many instances as it can without any risk of having the number of healthy instances fall below the specified minimum number of healthy instances.
To determine the number of instances that should be deployed to at once, CodeDeploy uses the following calculation:
```
[total-hosts] - [minimum-healthy-hosts] =
[number-of-hosts-to-deploy-to-at-once]
```
For example:
+ If your deployment group has 10 instances and you set the minimum healthy instances number to 9, CodeDeploy deploys to 1 instance at a time.
+ If your deployment group has 10 instances and you set the minimum healthy instances number to 3, CodeDeploy deploys to 7 instances at the same time in the first batch, and then to the remaining 3 in the second batch.
+ If your deployment group has 10 instances and you set the minimum healthy instances number to 0, CodeDeploy deploys to 10 instances at the same time.
**Examples**
The following examples assume a deployment group with 10 instances.
Minimum healthy instances: 95%
CodeDeploy rounds the minimum healthy instances number up to 10 instances, which equals the number of healthy instances. The overall deployment immediately fails without deploying the revision to any instances.
Minimum healthy instances: 9
CodeDeploy deploys the revision to one instance at a time. If deployment to any of the instances fails, CodeDeploy immediately fails the overall deployment because the number of healthy instances equals the minimum healthy instances number. The exception to this rule is that if the last instance fails, the deployment still succeeds.
CodeDeploy continues the deployment, one instance at a time, until any deployment fails or the overall deployment is complete. If all 10 deployments succeed, the deployment group now has 10 healthy instances.
Minimum healthy instances: 8
CodeDeploy deploys the revision to two instances at a time. If two of these deployments fail, CodeDeploy immediately fails the overall deployment. The exception to this rule is that if the last instance is the second to fail, the deployment still succeeds.
Minimum healthy instances: 0
CodeDeploy deploys the revision to the entire deployment group at once. At least one deployment to an instance must succeed for the overall deployment to succeed. If 0 instances are healthy, then the deployment fails. This is because of the requirement that in order to mark an overall deployment as successful, at least one instance must be healthy when the overall deployment is completed, even if the minimum healthy instances value is 0.
## About the minimum number of healthy instances per Availability Zone
**Note**
This section uses the terms *instance* and *host* interchangeably to refer to Amazon EC2 instances.
If you're deploying to instances in several [Availability Zones](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-availability-zones), you can optionally enable the [zonal configuration](deployment-configurations-create.md#zonal-config) feature, which allows CodeDeploy to deploy to one Availability Zone at a time.
When this feature is enabled, CodeDeploy will make sure that the number of healthy hosts stays above the 'minimum healthy hosts per zone' *and* the 'minimum healthy hosts' values. If the number of healthy hosts falls below either value, CodeDeploy fails the deployment across all Availability Zones.
To calculate the number of hosts to deploy to at once, CodeDeploy uses both the 'minimum healthy hosts per zone' and the 'minimum healthy hosts' values. CodeDeploy will use the *lesser* of calculations `[A]` and `[B]`, where `[A]` and `[B]` are:
```
[A] = [total-hosts] - [min-healthy-hosts] =
[number-of-hosts-to-deploy-to-at-once]
```
```
[B] = [total-hosts-per-AZ] - [min-healthy-hosts-per-AZ] =
[number-of-hosts-to-deploy-to-at-once-per-AZ]
```
After determining the number of hosts to deploy to at once, CodeDeploy deploys to hosts in batches of that number, one Availability Zone at a time, with an optional pause (or 'bake time') in between zones.
**Example**
If your deployment is configured like this:
+ `[total-hosts]` is `200`
+ `[minimum-healthy-hosts]` is `160`
+ `[total-hosts-per-AZ]` is `100`
+ `[minimum-healthy-hosts-per-AZ]` is `50`
Then...
+ `[A]` = `200 - 160 = 40`
+ `[B]` = `100 - 50 = 50`
+ `40` is less than `50`
Therefore, CodeDeploy will deploy to `40` hosts at once.
In this scenario, the deployment unfolds as follows:
1. CodeDeploy deploys to the first Availability Zone:
1. CodeDeploy deploys to the first `40` hosts.
1. CodeDeploy deploys to the next `40` hosts.
1. CodeDeploy deploys to the remaining `20` hosts.
The deployment to the first Availability Zone is now complete.
1. (Optional) CodeDeploy waits while the deployment to the first zone 'bakes', as defined by the **Monitor duration** or **Add a monitor duration for the first zone** setting. If there are no problems, CodeDeploy continues.
1. CodeDeploy deploys to the second Availability Zone:
1. CodeDeploy deploys to the first `40` hosts.
1. CodeDeploy deploys to the next `40` hosts.
1. CodeDeploy deploys to the remaining `20` hosts.
The deployment to the second and final Availability Zone is now complete.
To learn about the zonal configuration feature, and how to specify the minimum number of healthy instances per Availability Zone, see [zonal configuration](deployment-configurations-create.md#zonal-config).