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

Managing AWS CodeDeploy Agent Operations

These instructions show you how to install, uninstall, reinstall, or update the AWS CodeDeploy agent and how to verify the AWS CodeDeploy agent is running.

Operating Systems Supported by the AWS CodeDeploy Agent

Supported Amazon EC2 AMI Operating Systems

The AWS CodeDeploy agent has been tested on the following Amazon EC2 AMI operating systems:

  • Amazon Linux 2014.09.1, 2015.03, 2016.03.0, 2016.03.1

  • Ubuntu Server 14.04 LTS

  • Windows Server 2008 R2 and Windows Server 2012 R2

  • Red Hat Enterprise Linux (RHEL) 7.x

The AWS CodeDeploy agent is available as open source for you to adapt to your needs. It can be used with other Amazon EC2 AMI operating systems. For more information, go to the AWS CodeDeploy Agent repository in GitHub.

Supported On-Premises Operating Systems

The AWS CodeDeploy agent has been tested on the following on-premises operating systems:

  • Ubuntu Server 14.04 LTS

  • Windows Server 2008 R2 and Windows Server 2012 R2

  • Red Hat Enterprise Linux (RHEL) 7.x

The AWS CodeDeploy agent is available as open source for you to adapt to your needs. It can be used with other on-premises instance operating systems. For more information, go to the AWS CodeDeploy Agent repository in GitHub.

Communication Protocol and Port for the AWS CodeDeploy Agent

The AWS CodeDeploy agent communicates outbound using HTTPS over port 443.

Required Version of AWS SDK for Ruby (aws-sdk-core) on Amazon EC2 Instances

Versions of the AWS CodeDeploy agent earlier than 1.0.1.880 are compatible only with version 2.1.2 and earlier versions of the AWS SDK for Ruby (aws-sdk-core 2.1.2). If you are using a version of the AWS CodeDeploy agent earlier than 1.0.1.880, we recommend that you update to version 1.0.1.880. For information, see the following:

Supported Versions of the AWS CodeDeploy Agent

Your instances must be running a supported version of the AWS CodeDeploy agent. The current minimum supported version is 1.0.1.854. If you are running an earlier version, deployments to your instances may fail.

The following table lists the currently supported versions of the AWS CodeDeploy agent and the features and enhancements included with each release.

VersionRelease dateDetails
1.0.1.950March 24, 2016

Feature: Added installation proxy support.

Enhancement: Updated the installation script to not download the AWS CodeDeploy agent if the latest version is already installed.

1.0.1.934February 11, 2016

Feature: Introduced support for specifying the number of application revisions you want the AWS CodeDeploy agent to archive for a deployment group.

1.0.1.880January 11, 2016Enhancement: Made the AWS CodeDeploy agent compatible with version 2.2 of the AWS SDK for Ruby (aws-sdk-core 2.2). Version 2.1.2 is still supported.
1.0.1.854November 17, 2015

Feature: Introduced support for the SHA-256 hash algorithm. After March 31, 2016, all installations of the AWS CodeDeploy agent must be updated, at minimum, to version 1.0.1.854 or deployments will fail.

Feature: Introduced version tracking support in .version files.

Feature: Made the deployment group ID available through the use of an environment variable.

Enhancement: Added support for monitoring AWS CodeDeploy agent logs using Amazon CloudWatch Logs.

For related information, see the following:

For a history of AWS CodeDeploy agent versions, see the Release Repository on GitHub.

Verify the AWS CodeDeploy Agent Is Running

This section describes commands to run if you suspect the AWS CodeDeploy agent has stopped running on an instance.

To verify the AWS CodeDeploy agent for Amazon Linux or RHEL is running

To see if the AWS CodeDeploy agent is installed and running, sign in to the instance, and run the following command:

sudo service codedeploy-agent status

If the command returns an error, the AWS CodeDeploy agent is not installed. Install it as described in To install or reinstall the AWS CodeDeploy agent for Amazon Linux or RHEL .

If the AWS CodeDeploy agent is installed and running, you should see a message like The AWS CodeDeploy agent is running.

If you see a message like error: No AWS CodeDeploy agent running, start the service and run the following two commands, one at a time:

sudo service codedeploy-agent start
sudo service codedeploy-agent status

To verify the AWS CodeDeploy agent for Ubuntu Server is running

To see if the AWS CodeDeploy agent is installed and running, sign in to the instance, and run the following command:

sudo service codedeploy-agent status

If the command returns an error, the AWS CodeDeploy agent is not installed. Install it as described in To install or reinstall the AWS CodeDeploy agent for Ubuntu Server.

If the AWS CodeDeploy agent is installed and running, you should see a message like The AWS CodeDeploy agent is running.

If you see a message like error: No AWS CodeDeploy agent running, start the service and run the following two commands, one at a time:

sudo service codedeploy-agent start
sudo service codedeploy-agent status

To verify the AWS CodeDeploy agent for Windows Server is running

To see if the AWS CodeDeploy agent is installed and running, sign in to the instance, and run the following command:

powershell.exe -Command Get-Service -Name codedeployagent

You should see output similar to the following:


Status   Name               DisplayName
------   ----               -----------
Running codedeployagent    CodeDeploy Host Agent Service

If the command returns an error, the AWS CodeDeploy agent is not installed. Install it as described in To install or reinstall the AWS CodeDeploy agent for Windows Server.

If Status shows anything other than Running, start the service with the following command:

powershell.exe -Command Start-Service -Name codedeployagent

You can restart the service with the following command:

powershell.exe -Command Restart-Service -Name codedeployagent

You can stop the service with the following command:

powershell.exe -Command Stop-Service -Name codedeployagent

Determine the Version of the AWS CodeDeploy Agent

You can determine the version of the AWS CodeDeploy agent running on your instance in two ways.

First, starting with version 1.0.1.854 of the AWS CodeDeploy agent, you can view the version number in a .version file on the instance. The following table shows the location and sample version string for each of the supported operating systems.

Operating systemFile locationSample agent_version string
Amazon Linux and Red Hat Enterprise Linux (RHEL)/opt/codedeploy-agent/.versionOFFICIAL_1.0.1.854_rpm
Ubuntu Server/opt/codedeploy-agent/.versionOFFICIAL_1.0.1.854_deb
Windows ServerC:\ProgramData\Amazon\CodeDeploy\.versionOFFICIAL_1.0.1.854_msi

Second, you can run a command on an instance to determine the version of the AWS CodeDeploy agent.

To determine the version on Amazon Linux or RHEL

Sign in to the instance and run the following command:

sudo yum info codedeploy-agent

To determine the version on Ubuntu Server

Sign in to the instance and run the following command:

sudo dpkg -s codedeploy-agent

To determine the version on Windows Server

Sign in to the instance and run the following command:

sc qdescription codedeployagent

Install or Reinstall the AWS CodeDeploy Agent

If you suspect the AWS CodeDeploy agent is missing or not working, you can run commands on an instance to install or reinstall it.

To install or reinstall the AWS CodeDeploy agent for Amazon Linux or RHEL

Sign in to the instance, and run the following commands, one at a time.

Note

In the fourth command, /home/ec2-user represents the default user name for an Amazon Linux or RHEL Amazon EC2 instance. If your instance was created using a custom AMI, the AMI owner might have specified a different default user name.

  1. sudo yum update
    sudo yum install ruby
    sudo yum install wget
    cd /home/ec2-user
    wget https://bucket-name.s3.amazonaws.com/latest/install
    chmod +x ./install
    sudo ./install auto

    Type y if prompted.

    bucket-name represents one of the following:

    • aws-codedeploy-us-east-1 for instances in the US East (N. Virginia) 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-eu-west-1 for instances in the EU (Ireland) 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-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-sa-east-1 for instances in the South America (São Paulo) region

  2. sudo service codedeploy-agent status

    If the AWS CodeDeploy agent is installed and running, you should see a message like The AWS CodeDeploy agent is running.

    If you see a message like error: No AWS CodeDeploy agent running, start the service and run the following two commands, one at a time:

    sudo service codedeploy-agent start
    sudo service codedeploy-agent status

To uninstall the AWS CodeDeploy agent, sign in to the instance and run the following command:

sudo yum erase codedeploy-agent

To install or reinstall the AWS CodeDeploy agent for Ubuntu Server

Sign in to the instance, and run the following commands, one at a time.

Note

In the fifth command, /home/ubuntu represents the default user name for an Ubuntu Server instance. If your instance was created using a custom AMI, the AMI owner might have specified a different default user name.

  1. sudo apt-get update
    sudo apt-get install python-pip
    sudo apt-get install ruby2.0
    sudo apt-get install wget
    cd /home/ubuntu
    wget https://bucket-name.s3.amazonaws.com/latest/install
    chmod +x ./install
    sudo ./install auto

    Type y if prompted.

    bucket-name represents one of the following:

    • aws-codedeploy-us-east-1 for instances in the US East (N. Virginia) 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-eu-west-1 for instances in the EU (Ireland) 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-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-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-west-1 for instances in the US West (N. California) region

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

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

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

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

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

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

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

  2. sudo service codedeploy-agent status

    If the AWS CodeDeploy agent is installed and running, you should see a message like The AWS CodeDeploy agent is running.

    If you see a message like error: No AWS CodeDeploy agent running, start the service and run the following two commands, one at a time:

    sudo service codedeploy-agent start
    sudo service codedeploy-agent status

To uninstall the AWS CodeDeploy agent, sign in to the instance and run the following command:

sudo dpkg -r codedeploy-agent

To install or reinstall the AWS CodeDeploy agent for Windows Server

Sign in to the instance, and run the following commands, one at a time:

if not exist "c:\temp" mkdir c:\temp
powershell.exe -Command Read-S3Object -BucketName bucket-name -Key latest/codedeploy-agent.msi -File c:\temp\codedeploy-agent.msi
c:\temp\codedeploy-agent.msi /quiet /l c:\temp\host-agent-install-log.txt
powershell.exe -Command Get-Service -Name codedeployagent

bucket-name represents one of the following:

  • aws-codedeploy-us-east-1 for instances in the US East (N. Virginia) 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-eu-west-1 for instances in the EU (Ireland) 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-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-sa-east-1 for instances in the South America (São Paulo) region

If the AWS CodeDeploy agent is installed and running, after the Get-Service command call, you should see output similar to the following:


Status   Name                DisplayName
------   ----                -----------
Running  codedeployagent    CodeDeploy Host Agent Service

To uninstall the AWS CodeDeploy agent, sign in to the instance and run the following three commands, one at a time:

wmic
product where name="CodeDeploy Host Agent" call uninstall /nointeractive
exit

Alternatively, sign in to the instance, and in Control Panel, open Programs and Features, choose CodeDeploy Host Agent, and then choose Uninstall.

Update the AWS CodeDeploy Agent

For all supported operating systems except Windows Server, the AWS CodeDeploy agent is updated automatically when a new version is released. You can also force updates on all supported operating systems by running a command on an instance.

To update on Amazon Linux or RHEL

After the AWS CodeDeploy agent (codedeploy-agent.noarch.rpm) is installed on an instance, it will be updated automatically within 24 hours of the release of a new version. The update time cannot be easily cancelled or rescheduled. If a deployment is in progress during the update, the current deployment lifecycle event will finish first. After the update is complete, the deployment will resume with the next deployment lifecycle event.

If you want to force an update of the AWS CodeDeploy agent, sign in to the instance, and run the following command:

sudo /opt/codedeploy-agent/bin/install auto

To update on Ubuntu Server

After the AWS CodeDeploy agent (codedeploy-agent_all.deb) is installed on an instance, it will be updated automatically within 24 hours of the release of a new version. The update time cannot be easily cancelled or rescheduled. If a deployment is in progress during the update, the current deployment lifecycle event will finish first. After the update is complete, the deployment will resume with the next deployment lifecycle event.

If you want to force an update of the AWS CodeDeploy agent, sign in to the instance, and run the following command:

sudo /opt/codedeploy-agent/bin/install auto

To update on Windows Server

The AWS CodeDeploy agent (codedeploy-agent.msi) is not updated automatically upon release of a new version. To update the AWS CodeDeploy agent after it has been installed on an instance, follow the instructions in To install or reinstall the AWS CodeDeploy agent for Windows Server.