Working with the CodeDeploy agent - AWS CodeDeploy
Operating systems supported by the CodeDeploy agentCommunication protocol and port for the CodeDeploy agentVersion history of the CodeDeploy agentManaging the CodeDeploy processApplication revision and log file cleanupFiles installed by the CodeDeploy agent

Working with the CodeDeploy agent

The AWS CodeDeploy agent is a software package that, when installed and configured on an instance, makes it possible for that instance to be used in CodeDeploy deployments.

AWS supports the latest minor version of the CodeDeploy agent. Currently the latest minor version is 1.7.x.

Note

The CodeDeploy agent is required only if you deploy to an EC2/On-Premises compute platform. The agent is not required for deployments that use the Amazon ECS or AWS Lambda compute platform.

A configuration file is placed on the instance when the agent is installed. This file is used to specify how the agent works. This configuration file specifies directory paths and other settings for AWS CodeDeploy to use as it interacts with the instance. You can change some of the configuration options in the file. For information about working with the CodeDeploy agent configuration file, see CodeDeploy agent configuration reference.

For more information about working with the CodeDeploy agent, such as steps for installing, updating, and verifying versions, see Managing CodeDeploy agent operations.

Topics

Operating systems supported by the CodeDeploy agent

Supported Amazon EC2 AMI operating systems

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

  • Amazon Linux 2023 (ARM, x86)

  • Amazon Linux 2 (ARM, x86)

  • Microsoft Windows Server 2022, 2019

  • Red Hat Enterprise Linux (RHEL) 9.x, 8.x, 7.x

  • Ubuntu Server 22.04 LTS, 20.04 LTS, 18.04 LTS, 16.04 LTS

The 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 CodeDeploy agent repository in GitHub.

Supported on-premises operating systems

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

  • Microsoft Windows Server 2022, 2019

  • Red Hat Enterprise Linux (RHEL) 9.x, 8.x, 7.x

  • Ubuntu Server 22.04 LTS, 20.04 LTS

The 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 CodeDeploy agent repository in GitHub.

Communication protocol and port for the CodeDeploy agent

The CodeDeploy agent communicates outbound using HTTPS over port 443.

When the CodeDeploy agent runs on an EC2 instance, it will use the EC2 metadata endpoint to retrieve instance related information. Find out more about limiting and granting instance metadata service access.

Version history of the CodeDeploy agent

Your instances must be running a supported version of the CodeDeploy agent. The current minimum supported version is 1.7.x.

Note

We recommend using the latest version of the CodeDeploy agent. If you’re having issues, update to the latest version before contacting AWS Support. For upgrade information, see Update the CodeDeploy agent.

The following table lists all releases of the CodeDeploy agent and the features and enhancements included with each version.

Version Release date Details

1.7.1

November 14, 2024

Changed: Updated dependencies for security patches.

1.7.0

March 6, 2024

Added: A :disable_imds_v1: configuration setting to the CodeDeploy agent configuration file. Use this setting to disable the fallback to IMDSv1 when IMDSv2 errors occur. Defaults to false (enable the fallback). For more information, see CodeDeploy agent configuration reference.

Added: Support for the Red Hat Enterprise Linux 9 (RHEL 9) operating system.

Added: Support for Ruby versions 3.1 and 3.2 on Ubuntu Server.

Fixed: The CodeDeploy agent now generates a user-friendly error if the CodeDeploy agent configuration file fails to load.

Changed: Upgraded Ruby to 2.7.8-1 in the CodeDeploy agent for Windows.

1.6.0

March 30, 2023

Added: Support for Ruby 3.1, 3.2.

Added: Support for Amazon Linux 2023.

Added: Support for Windows Server 2022.

Changed: The default setting of verbose is now false for Windows Server instances. To continue to print debug messages in log files on Windows, you must set verbose to true.

Removed: Support for Windows Server 2016 and Windows Server 2012 R2.

Removed: Support for Amazon Linux 2018.03.x.

1.5.0

March 3, 2023

Added: Support for Ruby 3.

Added: Support for Ubuntu 22.04.

Fixed: An issue where restarting the CodeDeploy agent soon after startup would lead to the agent hanging.

Changed: The CodeDeploy agent now fails a host deployment on agent startup if the agent service restarts unexpectedly while running a hook script. This fix lets you avoid waiting for the 70-minute timeout period before retrying a deployment.

Deprecation notice: CodeDeploy agent 1.5.0 is the last release to support Windows Server 2016 and Windows Server 2012 R2.

Removed: Support for the CodeDeploy agent on Ubuntu 14.04 LTS, Windows Server 2008 R2, and Windows Server 2008 R2 32-bit.

1.4.1

December 6, 2022

Fixed: Security vulnerability related to logging.

Enhancement: Improved logging when polling for the host command.

1.4.0

August 31, 2022

Added: Support for Red Hat Enterprise Linux 8.

Added: Support for long file paths on the CodeDeploy agent for Windows. To enable long file paths, you'll need to set the appropriate Windows registry key and then restart your agent. For more information, see Long file paths cause "No such file or directory" errors.

Fixed: An issue with the unzip operation when the disk was full. The CodeDeploy agent now detects the unzip's exit code 50 indicating a full disk, removes partially extracted files, and raises an exception to post a failure to the CodeDeploy server. The error message is visible as a lifecycle event error message, and the host-level deployment will stop without being stuck or timing-out.

Fixed: An issue that would cause the agent to fail.

Fixed: An issue where hooks would time out during an edge-case race condition. Hooks with no scripts will now continue and no longer cause failures or timeouts.

Changed: The update script from the CodeDeploy agent's bin directory was removed because it is no longer used.

Changed: The CodeDeploy agent for Windows Server now bundles Ruby 2.7.

Changed: New environment variables were added, to be used by hook scripts depending on the source of the deployment bundle (Amazon S3 or GitHub).

For more information, see Environment variable availability for hooks.

Important

Deprecation notice: CodeDeploy agent 1.4.0 is the last release that will include installers for 32-bit Windows Server.

Deprecation notice: CodeDeploy agent 1.4.0 is the last release that will support Windows Server 2008 R2.

Removed: Support for the CodeDeploy agent on the following Amazon EC2 AMIs: Amazon Linux 2014.09, 2016.03, 2016.09, and 2017.03.

1.3.2

May 6, 2021
Important

CodeDeploy agent 1.3.2 addresses CVE-2018-1000201 which affects Windows hosts running the agent. The CVE cites ruby-ffi, which is a dependency of the CodeDeploy agent. If your agent was installed with Amazon EC2 Systems Manager (SSM) and is set to update automatically, no action is required. Otherwise, action is required to manually update the agent. To upgrade the agent follow the instructions in Update the CodeDeploy agent on Windows Server.

Fixed: An issue when installing the CodeDeploy agent on Ubuntu 20.04 and later.

Fixed: An intermittent issue that occurred when extracting compressed files because relative paths weren't being handled correctly.

Added: Support for AWS PrivateLink and VPC endpoints for Windows instances.

Added: AppSpec file improvements, as described below.

Upgraded: CodeDeploy now uses the AWS SDK for Ruby 3.0.

1.3.1

December 22, 2020

Fixed: 1.3.0 issue that prevented on-premises instances from starting.

1.3.0

November 10, 2020
Important

This version is deprecated.

Fixed: Removed an expired certificate that was no longer used.

Fixed: Removed the prompt message from the agent uninstall script used by AWS Systems Manager, making it easier to downgrade a host or fleet to a previous version of the agent.

1.2.1

September 23, 2020

Changed: Upgraded AWS SDK for Ruby dependency from v2 to v3.

Added: Support for IMDSv2. Includes a silent fallback to IMDSv1 if IMDSv2 http requests fail.

Changed: Updated Rake and Rubyzip dependencies for security patches.

Fixed: Ensure that an empty PID file will return a status of No CodeDeploy Agent Running and clean up the PID file on agent start.

1.1.2

August 4, 2020

Added: Support for Ubuntu Server 19.10 and 20.04.

Note: : Version 19.10 reached its end-of-life date and is no longer supported by Ubuntu or CodeDeploy.

Added: Memory efficiency improvements for Linux and Ubuntu to release reserved memory more timely.

Added: Compatibility with Windows Server "silent-cleanup" which was causing the agent to be unresponsive in some cases.

Added: Ignore non-empty directories during cleanup to avoid failures on deployment.

Added: Support for AWS Local Zone in Los Angeles (LA).

Added: Extract AZ from instance metadata to provide compatibility for AWS Local Zones.

Added: Users can now provide their archive in subdirectories and aren't required to store it in the root directory.

Added: Detected an issue with Rubyzip that could result in memory leaks. Updated the unzip command to first attempt to use a system-installed unzip utility before using Rubyzip.

Added: :enable_auth_policy: as an agent configuration setting.

Changed: Unzip warnings are now ignored so deployments will continue.

1.1.0

June 30, 2020

Changed: Versioning of the CodeDeploy agent now follows the Ruby standard versioning convention.

Added: New parameter to the install and update command to allow installation of specific agent version from the command line.

Removed: Removed the CodeDeploy agent Auto Updater for Linux and Ubuntu. To configure automatic updates of the CodeDeploy agent, see Install the CodeDeploy agent using AWS Systems Manager.

1.0.1.1597

November 15, 2018

Enhancement: CodeDeploy supports Ubuntu 18.04.

Enhancement: CodeDeploy supports Ruby 2.5.

Enhancement: CodeDeploy supports FIPS endpoints. For more information about FIPS endpoints, see FIPS 140-2 overview. For endpoints that can be used with CodeBuild, see CodeDeploy regions and endpoints.

1.0.1.1518

June 12, 2018

Enhancement: Fixed an issue that caused an error when the CodeDeploy agent is closed while it is accepting poll requests.

Enhancement: Added a deployment tracking feature that prevents the CodeDeploy agent from being closed when a deployment is in progress.

Enhancement: Improved performance when deleting files.

1.0.1.1458

March 6, 2018

Note: This version is no longer supported. If you use this version, your deployments might fail.

Enhancement: Improved certificate validations to support more trusted authorities.

Enhancement: Fixed an issue that caused the local CLI to fail during a deployment that includes a BeforeInstall lifecycle event.

Enhancement: Fixed an issue that might cause an active deployment to fail when the CodeDeploy agent is updated.

1.0.1.1352

November 16, 2017

Note: This version is no longer supported. If you use this version, your deployments might fail.

Feature: Introduced a new feature for testing and debugging an EC2/On-Premises deployment on a local machine or instance where the CodeDeploy agent is installed.

1.0.1.1106

May 16, 2017

Note: This version is no longer supported. If you use this version, your deployments might fail.

Feature: Introduced new support for handling content in a target location that wasn't part of the application revision from the most recent successful deployment. Deployments options for existing content now include retaining the content, overwriting the content, or failing the deployment.

Enhancement: Made the CodeDeploy agent compatible with version 2.9.2 of the AWS SDK for Ruby (aws-sdk-core 2.9.2).

1.0.1.1095

March 29, 2017

Note: This version is no longer supported. If you use this version, your deployments might fail.

Enhancement: Introduced support for the CodeDeploy agent in the China (Beijing) Region.

Enhancement: Enabled Puppet to run on Windows Server instances when invoked by a lifecycle event hook.

Enhancement: Improved the handling of untar operations.
1.0.1.1067 January 6, 2017

Note: This version is no longer supported. If you use this version, your deployments might fail.

Enhancement: Revised many error messages to include more specific causes for deployment failures.

Enhancement: Fixed an issue that prevented the CodeDeploy agent from identifying the correct application revision to deploy during some deployments.

Enhancement: Reverted the usage of pushd and popd before and after the untar operation.
1.0.1.1045 November 21, 2016

Note: This version is no longer supported. If you use this version, your deployments might fail.

Enhancement: Made the CodeDeploy agent compatible with version 2.6.11 of the AWS SDK for Ruby (aws-sdk-core 2.6.11).

1.0.1.1037 October 19, 2016

Note: This version is no longer supported. If you use this version, your deployments might fail.

The CodeDeploy agent for Amazon Linux, RHEL, and Ubuntu Server instances has been updated with the following change. For Windows Server instances, the latest version remains 1.0.1.998.

Enhancement: The agent can now determine which version of Ruby is installed on an instance so it can invoke the codedeploy-agent script using that version.
1.0.1.1011.1 August 17, 2016

Note: This version is no longer supported. If you use this version, your deployments might fail.

Enhancement: Removed the changes introduced by version 1.0.1.1011 due to issues with shell support. This version of the agent is functionally equivalent to version 1.0.1.998 released on July 11, 2016.
1.0.1.1011 August 15, 2016

Note: This version is no longer supported. If you use this version, your deployments might fail.

The CodeDeploy agent for Amazon Linux, RHEL, and Ubuntu Server instances has been updated with the following changes. For Windows Server instances, the latest version remains 1.0.1.998.

Feature: Added support for invoking the CodeDeploy agent using the bash shell on operating systems where the systemd init system is in use.

Enhancement: Enabled support for all versions of Ruby 2.x in the CodeDeploy agent and the CodeDeploy agent updater. Updated CodeDeploy agents are no longer dependent on Ruby 2.0 only. (Ruby 2.0 is still required for deb and rpm versions of the CodeDeploy agent installer.)
1.0.1.998 July 11, 2016

Note: This version is no longer supported. If you use this version, your deployments might fail.

Enhancement: Fixed support for running the CodeDeploy agent with user profiles other than root. The variable named USER is replaced by CODEDEPLOY_USER to avoid conflicts with environmental variables.
1.0.1.966 June 16, 2016

Note: This version is no longer supported. If you use this version, your deployments might fail.

Feature: Introduced support for running the CodeDeploy agent with user profiles other than root.

Enhancement: Fixed support for specifying the number of application revisions you want the CodeDeploy agent to archive for a deployment group.

Enhancement: Made the CodeDeploy agent compatible with version 2.3 of the AWS SDK for Ruby (aws-sdk-core 2.3).

Enhancement: Fixed issues with UTF-8 encoding during deployments.

Enhancement: Improved accuracy when identifying process names.
1.0.1.950 March 24, 2016

Note: This version is no longer supported. If you use this version, your deployments might fail.

Feature: Added installation proxy support.

Enhancement: Updated the installation script to not download the CodeDeploy agent if the latest version is already installed.
1.0.1.934 February 11, 2016

Note: This version is no longer supported. If you use this version, your deployments might fail.

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

1.0.1.880 January 11, 2016

Note: This version is no longer supported and might cause deployments to fail.

Enhancement: Made the 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.854 November 17, 2015

Note: This version is no longer supported. If you use this version, your deployments might fail.

Feature: Introduced support for the SHA-256 hash algorithm.

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 CodeDeploy agent logs using Amazon CloudWatch Logs.

For related information, see the following:

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

Managing the CodeDeploy process

All Linux distributions of the CodeDeploy agent (rpm and deb) use systemd by default to manage the agent process.

However, both the rpm and deb distributions ship with startup scripts that reside at /etc/init.d/codedeploy-agent. Depending on which distribution you are using, when using a command such as sudo service codedeploy-agent restart, the scripts at /etc/init.d may be run to launch the agent process instead of allowing systemd to manage the process. Running scripts at /etc/init.d is undesirable.

To prevent this issue, for systems that support systemd we recommend using the systemctl utility for any agent operations instead of using the service command.

For example, to restart the CodeDeploy agent use sudo systemctl restart codedeploy-agent instead of the equivalent command with the service utility.

Application revision and log file cleanup

The CodeDeploy agent archives revisions and log files on instances. The CodeDeploy agent cleans up these artifacts to conserve disk space.

Application revision deployment logs: You can use the :max_revisions: option in the agent configuration file to specify the number of application revisions to archive by entering any positive integer. CodeDeploy also archives the log files for those revisions. All others are deleted, with the exception of the log file of the last successful deployment. That log file is always retained, even if the number of failed deployments exceeds the number of retained revisions. If no value is specified, CodeDeploy retains the five most recent revisions in addition to the currently deployed revision.

CodeDeploy logs: For Amazon Linux, Ubuntu Server, and RHEL instances, the CodeDeploy agent rotates the log files under the /var/log/aws/codedeploy-agent folder. The log file is rotated at 00:00:00 (instance time) daily. Log files are deleted after seven days. The naming pattern for rotated log files is codedeploy-agent.YYYYMMDD.log.

Files installed by the CodeDeploy agent

The CodeDeploy agent stores revisions, deployment history, and deployment scripts in its root directory on an instance. The default name and location of this directory is:

'/opt/codedeploy-agent/deployment-root' for Amazon Linux, Ubuntu Server, and RHEL instances.

'C:\ProgramData\Amazon\CodeDeploy' for Windows Server instances.

You can use the root_dir setting in the CodeDeploy agent configuration file to configure the directory's name and location. For more information, see CodeDeploy agent configuration reference.

The following is an example of the file and directory structure under the root directory. The structure assumes there are N number of deployment groups, and each deployment group contains N number of deployments. 

|--deployment-root/
|-- deployment group 1 ID 
|    |-- deployment 1 ID 
|    |    |-- Contents and logs of the deployment's revision
|    |-- deployment 2 ID
|    |    |-- Contents and logs of the deployment's revision
|    |-- deployment N ID
|    |    |-- Contents and logs of the deployment's revision
|-- deployment group 2 ID
|    |-- deployment 1 ID
|    |    |-- bundle.tar
|    |    |-- deployment-archive
|    |    |    | -- contents of the deployment's revision
|    |    |-- logs
|    |    |    | -- scripts.log     
|    |-- deployment 2 ID
|    |    |-- bundle.tar
|    |    |-- deployment-archive
|    |    |    | -- contents of the deployment's revision
|    |    |-- logs
|    |    |    | -- scripts.log     
|    |-- deployment N ID
|    |    |-- bundle.tar
|    |    |-- deployment-archive
|    |    |    | -- contents of the deployment's revision
|    |    |-- logs
|    |    |    | -- scripts.log     
|-- deployment group N ID
|    |-- deployment 1 ID
|    |    |-- Contents and logs of the deployment's revision
|    |-- deployment 2 ID
|    |    |-- Contents and logs of the deployment's revision
|    |-- deployment N ID
|    |    |-- Contents and logs of the deployment's revision
|-- deployment-instructions
|    |-- [deployment group 1 ID]_cleanup
|    |-- [deployment group 2 ID]_cleanup
|    |-- [deployment group N ID]_cleanup
|    |-- [deployment group 1 ID]_install.json
|    |-- [deployment group 2 ID]_install.json
|    |-- [deployment group N ID]_install.json
|    |-- [deployment group 1 ID]_last_successful_install
|    |-- [deployment group 2 ID]_last_successful_install
|    |-- [deployment group N ID]_last_successful_install
|    |-- [deployment group 1 ID]_most_recent_install
|    |-- [deployment group 2 ID]_most_recent_install
|    |-- [deployment group N ID]_most_recent_install
|-- deployment-logs
|    |-- codedeploy-agent-deployments.log

  • Deployment Group ID folders represent each of your deployment groups. A deployment group directory's name is its ID (for example, acde1916-9099-7caf-fd21-012345abcdef). Each deployment group directory contains one subdirectory for each attempted deployment in that deployment group.

    You can use the batch-get-deployments command to find a deployment group ID.

  • Deployment ID folders represent each deployment in a deployment group. Each deployment directory's name is its ID. Each folder contains:

    • bundle.tar, a compressed file with the contents of the deployment's revision. Use a zip decompression utility if you want to view the revision.

    • deployment-archive, a directory that contains the contents of the deployment's revision.

    • logs, a directory that contains a scripts.log file. This file lists the output of all scripts specified in the deployment's AppSpec file.

    If you want to find the folder for a deployment but don't know its deployment ID or deployment group ID, you can use the AWS CodeDeploy console or the AWS CLI to find them. For more information, see View CodeDeploy deployment details .

    The default maximum number of deployments that can be archived in a deployment group is five. When that number is reached, future deployments are archived and the oldest archive is deleted. You can use the max_revisions setting in the CodeDeploy agent configuration file to change the default. For more information, see CodeDeploy agent configuration reference.

    Note

    If you want to recover hard disk space used by archived deployments, update the max_revisions setting to a low number, such as 1 or 2. The next deployment deletes archived deployments so that the number is equal to the you specified.

  • deployment-instructions contains four text files for each deployment group:

    • [Deployment Group ID]-cleanup, a text file with an undo verison of each command that is run during a deployment. An example file name is acde1916-9099-7caf-fd21-012345abcdef-cleanup.

    • [Deployment Group ID]-install.json, a JSON file created during the most recent deployment. It contains the commands run during the deployment. An example file name is acde1916-9099-7caf-fd21-012345abcdef-install.json.

    • [Deployment Group ID]_last_successfull_install, a text file that lists the archive directory of the last successful deployment. This file is created when the CodeDeploy agent has copied all files in the deployment application to the instance. It is used by the CodeDeploy agent during the next deployment to determine which ApplicationStop and BeforeInstall scripts to run. An example file name is acde1916-9099-7caf-fd21-012345abcdef_last_successfull_install.

    • [Deployment Group ID]_most_recent_install, a text file that lists the name of the archive directory of the most recent deployment. This file is created when the files in the deployment are successfully downloaded. The [deployment group ID]_last_successfull_install file is created after this file, when the downloaded files are copied to their final destination. An example file name is acde1916-9099-7caf-fd21-012345abcdef_most_recent_install.

  • deployment-logs contains the following log files:

    • codedeploy-agent.yyyymmdd.log files are created for each day there is a deployment. Each log file contains information about the day's deployments. These log files might be useful for debugging problems like a permissions issue. The log file is initially named codedeploy-agent.log. The next day, the date of its deployments is inserted into the file name. For example, if today is January 3, 2018, you can see information about all of today's deployments in codedeploy-agent.log. Tomorrow, on January 4, 2018, the log file is renamed codedeploy-agent.20180103.log.

    • codedeploy-agent-deployments.log compiles the contents of scripts.log files for each deployment. The scripts.log files are located in the logs subfolder under each Deployment ID folder. The entries in this file are preceded by a deployment ID. For example, "[d-ABCDEF123]LifecycleEvent - BeforeInstall" might be written during a deployment with an ID of d-ABCDEF123. When codedeploy-agent-deployments.log reaches its maximum size, the CodeDeploy agent continues to write to it while deleting old content.