Menu
AWS CodeDeploy
User Guide (API Version 2014-10-06)

Create an Amazon EC2 Instance for AWS 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 AWS CodeDeploy deployments. As part of this process, you will create an IAM instance profile.

You can use our AWS CloudFormation template to launch an Amazon EC2 instance running Amazon Linux or Windows Server that is already configured for use in AWS CodeDeploy deployments. We do not provide an AWS 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.

You can use the Amazon EC2 console, AWS CLI, or Amazon EC2 APIs to launch an Amazon EC2 instance.

Launch an Amazon EC2 Instance (CLI )

Follow the instructions in Getting Started to set up and configure the AWS CLI and create an IAM instance profile named CodeDeployDemo-EC2-Instance-Profile.

  1. 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:

    Copy
    aws ec2 create-security-group --group-name CodeDeployDemo-Windows-Security-Group --description "For launching Windows Server images for use with AWS 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. AWS CodeDeploy does not require unrestricted port access and does not require HTTP access. For more information, see Tips for Securing Your Amazon EC2 Instance.

  2. On your development machine, create a file named instance-setup.sh (for Amazon EC2 instances running Amazon Linux, Ubuntu Server, or RHEL) or instance-setup.txt (for Amazon EC2 instances running Windows Server) that contains the following contents.

    As the Amazon EC2 instance is launched, this script will download the AWS CodeDeploy agent from the specified Amazon S3 location and then install it on the instance.

    Here are the contents of the instance-setup.sh file (Amazon Linux and RHEL):

    Copy
    #!/bin/bash yum -y update yum install -y ruby cd /home/ec2-user curl -O https://bucket-name.s3.amazonaws.com/latest/install chmod +x ./install ./install auto

    bucket-name represents one of the following:

    • aws-codedeploy-us-east-1 for instances in the US East (N. Virginia) region

    • aws-codedeploy-us-east-2 for instances in the US East (Ohio) region

    • aws-codedeploy-us-west-1 for instances in the US West (N. California) region

    • aws-codedeploy-us-west-2 for instances in the US West (Oregon) region

    • aws-codedeploy-ca-central-1 for instances in the Canada (Central) region

    • aws-codedeploy-eu-west-1 for instances in the EU (Ireland) region

    • aws-codedeploy-eu-west-2 for instances in the EU (London) region

    • aws-codedeploy-eu-central-1 for instances in the EU (Frankfurt) region

    • aws-codedeploy-ap-northeast-1 for instances in the Asia Pacific (Tokyo) region

    • aws-codedeploy-ap-northeast-2 for instances in the Asia Pacific (Seoul) region

    • aws-codedeploy-ap-southeast-1 for instances in the Asia Pacific (Singapore) region

    • aws-codedeploy-ap-southeast-2 for instances in the Asia Pacific (Sydney) region

    • aws-codedeploy-ap-south-1 for instances in the Asia Pacific (Mumbai) region

    • aws-codedeploy-sa-east-1 for instances in the South America (São Paulo) region

    Here are the contents of the instance-setup.sh (Ubuntu Server):

    Copy
    #!/bin/bash apt-get -y update apt-get -y install awscli apt-get -y install ruby cd /home/ubuntu aws s3 cp s3://bucket-name/latest/install . --region region-name chmod +x ./install ./install auto

    bucket-name represents one of the following:

    • aws-codedeploy-us-east-1 for instances in the US East (N. Virginia) region

    • aws-codedeploy-us-east-2 for instances in the US East (Ohio) region

    • aws-codedeploy-us-west-1 for instances in the US West (N. California) region

    • aws-codedeploy-us-west-2 for instances in the US West (Oregon) region

    • aws-codedeploy-ca-central-1 for instances in the Canada (Central) region

    • aws-codedeploy-eu-west-1 for instances in the EU (Ireland) region

    • aws-codedeploy-eu-west-2 for instances in the EU (London) region

    • aws-codedeploy-eu-central-1 for instances in the EU (Frankfurt) region

    • aws-codedeploy-ap-northeast-1 for instances in the Asia Pacific (Tokyo) region

    • aws-codedeploy-ap-northeast-2 for instances in the Asia Pacific (Seoul) region

    • aws-codedeploy-ap-southeast-1 for instances in the Asia Pacific (Singapore) region

    • aws-codedeploy-ap-southeast-2 for instances in the Asia Pacific (Sydney) region

    • aws-codedeploy-ap-south-1 for instances in the Asia Pacific (Mumbai) region

    • aws-codedeploy-sa-east-1 for instances in the South America (São Paulo) region

    region-name represents one of the following:

    • us-east-1 for instances in the US East (N. Virginia) region

    • us-east-2 for instances in the US East (Ohio) region

    • us-west-1 for instances in the US West (N. California) region

    • us-west-2 for instances in the US West (Oregon) region

    • ca-central-1 for instances in the Canada (Central) region

    • eu-west-1 for instances in the EU (Ireland) region

    • eu-west-2 for instances in the EU (London) region

    • eu-central-1 for instances in the EU (Frankfurt) region

    • ap-northeast-1 for instances in the Asia Pacific (Tokyo) region

    • ap-northeast-2 for instances in the Asia Pacific (Seoul) region

    • ap-southeast-1 for instances in the Asia Pacific (Singapore) region

    • ap-southeast-2 for instances in the Asia Pacific (Sydney) region

    • ap-south-1 for instances in the Asia Pacific (Mumbai) region

    • sa-east-1 for instances in the South America (São Paulo) region

    Here are the contents of the instance-setup.txt (Windows Server):

    Copy
    <powershell> New-Item -Path c:\temp -ItemType "directory" -Force powershell.exe -Command Read-S3Object -BucketName bucket-name/latest -Key codedeploy-agent.msi -File c:\temp\codedeploy-agent.msi Start-Process -Wait -FilePath c:\temp\codedeploy-agent.msi -WindowStyle Hidden </powershell>

    bucket-name represents one of the following:

    • aws-codedeploy-us-east-1 for instances in the US East (N. Virginia) region

    • aws-codedeploy-us-east-2 for instances in the US East (Ohio) region

    • aws-codedeploy-us-west-1 for instances in the US West (N. California) region

    • aws-codedeploy-us-west-2 for instances in the US West (Oregon) region

    • aws-codedeploy-ca-central-1 for instances in the Canada (Central) region

    • aws-codedeploy-eu-west-1 for instances in the EU (Ireland) region

    • aws-codedeploy-eu-west-2 for instances in the EU (London) region

    • aws-codedeploy-eu-central-1 for instances in the EU (Frankfurt) region

    • aws-codedeploy-ap-northeast-1 for instances in the Asia Pacific (Tokyo) region

    • aws-codedeploy-ap-northeast-2 for instances in the Asia Pacific (Seoul) region

    • aws-codedeploy-ap-southeast-1 for instances in the Asia Pacific (Singapore) region

    • aws-codedeploy-ap-southeast-2 for instances in the Asia Pacific (Sydney) region

    • aws-codedeploy-ap-south-1 for instances in the Asia Pacific (Mumbai) region

    • aws-codedeploy-sa-east-1 for instances in the South America (São Paulo) region

  3. From the same directory where you created the instance-setup.sh or instance-setup.txt file, you will call the run-instances command to create and launch the Amazon EC2 instance.

    Before you call this command, you will need to collect the following:

    • The ID of an Amazon Machine Image (AMI) (ami-id) you will use for the instance. To get the ID, see Finding a Suitable AMI.

    • The name of the type of Amazon EC2 instance (instance-type) you will create, such as t1.micro. For a list, see Amazon EC2 Instance Types.

    • 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.

      To find a key pair name, open the Amazon EC2 console at 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. Be sure you create the key pair in one of the regions listed in Region and Endpoints in AWS General Reference. Otherwise, you won't be able to use the Amazon EC2 instance key pair with AWS CodeDeploy.

    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:

    Important

    Be sure to include file:// before the file name. It is required in this command.

    Copy
    aws ec2 run-instances \ --image-id ami-id \ --key-name key-name \ --user-data file://instance-setup.sh \ --count 1 \ --instance-type instance-type \ --iam-instance-profile Name=CodeDeployDemo-EC2-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. AWS 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.

    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:

    Important

    Be sure to include file:// before the file name. It is required in this command.

    Copy
    aws ec2 run-instances --image-id ami-id --key-name key-name --user-data file://instance-setup.txt --count 1 --instance-type instance-type --iam-instance-profile Name=CodeDeployDemo-EC2-Instance-Profile --security-groups CodeDeployDemo-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.

  4. 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.

    Copy
    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 AWS 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.

    Copy
    aws ec2 create-tags --resources instance-id --tags Key=Name,Value=CodeDeployDemo

    To verify the Amazon EC2 instance has been launched and passed all checks, use the instance ID to call the describe-instance-status command.

    Copy
    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 will appear in the output:

To verify the AWS CodeDeploy agent is running on the instance, see Managing AWS CodeDeploy Agent Operations, and then return to this page. After you do this, the Amazon EC2 instance will be ready for use in AWS CodeDeploy deployments. The next step is to proceed to Create an Application.

Launch an Amazon EC2 Instance (Console)

We assume you have already followed the instructions in Getting Started and created an IAM instance profile named CodeDeployDemo-EC2-Instance-Profile.

  1. Sign in to the AWS Management Console and open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, choose Instances, and then choose Launch Instance.

  3. On the Step 1: Choose an Amazon Machine Image (AMI) page, from the Quick Start tab, locate operating system amd versopm you want to use, and then choose Select.

  4. On the Step 2: Choose an Instance Type page, choose any available Amazon EC2 instance type, and then choose Next: Configure Instance Details.

  5. On the Step 3: Configure Instance Details page, in the IAM role list, choose the IAM instance profile you created in Step 4: Create an IAM Instance Profile.

    Note

    If neither Launch into EC2-Classic nor a default virtual private cloud (VPC) is displayed in the Network list, and you are not able to select a different Amazon EC2 instance type that supports launching into EC2-Classic, you must choose an Amazon VPC and subnet, or choose Create new VPC or Create new subnet or both. For more information, see Your VPC and Subnets.

  6. Expand Advanced Details.

  7. Next to User data, with the As text option selected, type the following to install the AWS CodeDeploy agent as the Amazon EC2 instance is launched.

    For Amazon Linux or RHEL:

    Copy
    #!/bin/bash yum -y update yum install -y ruby cd /home/ec2-user curl -O https://bucket-name.s3.amazonaws.com/latest/install chmod +x ./install ./install auto

    bucket-name represents one of the following:

    • aws-codedeploy-us-east-1 for instances in the US East (N. Virginia) region

    • aws-codedeploy-us-east-2 for instances in the US East (Ohio) region

    • aws-codedeploy-us-west-1 for instances in the US West (N. California) region

    • aws-codedeploy-us-west-2 for instances in the US West (Oregon) region

    • aws-codedeploy-ca-central-1 for instances in the Canada (Central) region

    • aws-codedeploy-eu-west-1 for instances in the EU (Ireland) region

    • aws-codedeploy-eu-west-2 for instances in the EU (London) region

    • aws-codedeploy-eu-central-1 for instances in the EU (Frankfurt) region

    • aws-codedeploy-ap-northeast-1 for instances in the Asia Pacific (Tokyo) region

    • aws-codedeploy-ap-northeast-2 for instances in the Asia Pacific (Seoul) region

    • aws-codedeploy-ap-southeast-1 for instances in the Asia Pacific (Singapore) region

    • aws-codedeploy-ap-southeast-2 for instances in the Asia Pacific (Sydney) region

    • aws-codedeploy-ap-south-1 for instances in the Asia Pacific (Mumbai) region

    • aws-codedeploy-sa-east-1 for instances in the South America (São Paulo) region

    For Ubuntu Server:

    Copy
    #!/bin/bash apt-get -y update apt-get -y install awscli apt-get -y install ruby cd /home/ubuntu aws s3 cp s3://bucket-name/latest/install . --region region-name chmod +x ./install ./install auto

    bucket-name represents one of the following:

    • aws-codedeploy-us-east-1 for instances in the US East (N. Virginia) region

    • aws-codedeploy-us-east-2 for instances in the US East (Ohio) region

    • aws-codedeploy-us-west-1 for instances in the US West (N. California) region

    • aws-codedeploy-us-west-2 for instances in the US West (Oregon) region

    • aws-codedeploy-ca-central-1 for instances in the Canada (Central) region

    • aws-codedeploy-eu-west-1 for instances in the EU (Ireland) region

    • aws-codedeploy-eu-west-2 for instances in the EU (London) region

    • aws-codedeploy-eu-central-1 for instances in the EU (Frankfurt) region

    • aws-codedeploy-ap-northeast-1 for instances in the Asia Pacific (Tokyo) region

    • aws-codedeploy-ap-northeast-2 for instances in the Asia Pacific (Seoul) region

    • aws-codedeploy-ap-southeast-1 for instances in the Asia Pacific (Singapore) region

    • aws-codedeploy-ap-southeast-2 for instances in the Asia Pacific (Sydney) region

    • aws-codedeploy-ap-south-1 for instances in the Asia Pacific (Mumbai) region

    • aws-codedeploy-sa-east-1 for instances in the South America (São Paulo) region

    region-name represents one of the following:

    • us-east-1 for instances in the US East (N. Virginia) region

    • us-east-2 for instances in the US East (Ohio) region

    • us-west-1 for instances in the US West (N. California) region

    • us-west-2 for instances in the US West (Oregon) region

    • ca-central-1 for instances in the Canada (Central) region

    • eu-west-1 for instances in the EU (Ireland) region

    • eu-west-2 for instances in the EU (London) region

    • eu-central-1 for instances in the EU (Frankfurt) region

    • ap-northeast-1 for instances in the Asia Pacific (Tokyo) region

    • ap-northeast-2 for instances in the Asia Pacific (Seoul) region

    • ap-southeast-1 for instances in the Asia Pacific (Singapore) region

    • ap-southeast-2 for instances in the Asia Pacific (Sydney) region

    • ap-south-1 for instances in the Asia Pacific (Mumbai) region

    • sa-east-1 for instances in the South America (São Paulo) region

    For Windows Server:

    Copy
    <powershell> New-Item -Path c:\temp -ItemType "directory" -Force powershell.exe -Command Read-S3Object -BucketName bucket-name/latest -Key codedeploy-agent.msi -File c:\temp\codedeploy-agent.msi Start-Process -Wait -FilePath c:\temp\codedeploy-agent.msi -WindowStyle Hidden </powershell>

    bucket-name represents one of the following:

    • aws-codedeploy-us-east-1 for instances in the US East (N. Virginia) region

    • aws-codedeploy-us-east-2 for instances in the US East (Ohio) region

    • aws-codedeploy-us-west-1 for instances in the US West (N. California) region

    • aws-codedeploy-us-west-2 for instances in the US West (Oregon) region

    • aws-codedeploy-ca-central-1 for instances in the Canada (Central) region

    • aws-codedeploy-eu-west-1 for instances in the EU (Ireland) region

    • aws-codedeploy-eu-west-2 for instances in the EU (London) region

    • aws-codedeploy-eu-central-1 for instances in the EU (Frankfurt) region

    • aws-codedeploy-ap-northeast-1 for instances in the Asia Pacific (Tokyo) region

    • aws-codedeploy-ap-northeast-2 for instances in the Asia Pacific (Seoul) region

    • aws-codedeploy-ap-southeast-1 for instances in the Asia Pacific (Singapore) region

    • aws-codedeploy-ap-southeast-2 for instances in the Asia Pacific (Sydney) region

    • aws-codedeploy-ap-south-1 for instances in the Asia Pacific (Mumbai) region

    • aws-codedeploy-sa-east-1 for instances in the South America (São Paulo) region

  8. Leave the rest of the items on this page unchanged, and choose Next: Add Storage.

  9. Leave the Step 4: Add Storage page unchanged, and choose Next: Add Tags.

  10. On the Step 5: Add Tags page, with Name displayed in the Key box, type CodeDeployDemo in the Value box, and then choose Next: Configure Security Group.

    Important

    The contents of the Key and Value boxes are case-sensitive.

  11. On the Step 6: Configure Security Group page, leave the Create a new security group option selected.

    A default SSH role will be configured for Amazon EC2 instances running Amazon Linux, Ubuntu Server, or RHEL. A default RDP role will be configured for Amazon EC2 instances running Windows Server.

  12. 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 Anywhere 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. AWS CodeDeploy does not require unrestricted port access and does not require HTTP access. For more information, see Tips for Securing Your Amazon EC2 Instance.

    If a Boot from General Purpose (SSD) dialog box appears, follow the instructions, and then choose Next.

  13. Leave the Step 7: Review Instance Launch page unchanged, and choose Launch.

  14. 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 name, such as codedeploydemo. 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.

  15. Choose Launch Instances.

  16. Choose the ID for your Amazon EC2 instance. Do not continue until the instance has been launched and passed all checks.

To verify the AWS CodeDeploy agent is running on the instance, see Managing AWS CodeDeploy Agent Operations, and then return to this page. After you do this, the Amazon EC2 instance will be ready for use in AWS CodeDeploy deployments. The next step is to proceed to Create an Application.