Working with the CodeDeploy agent
The Amazon 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.
Amazon 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 Amazon 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 Amazon 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
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
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
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 Amazon 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
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
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 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
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. ImportantDeprecation 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 |
ImportantCodeDeploy agent 1.3.2 addresses CVE-2018-1000201 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 Amazon PrivateLink and VPC endpoints for Windows instances. Added: AppSpec file improvements, as described below.
Upgraded: CodeDeploy now uses the Amazon 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 |
ImportantThis 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 Amazon 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 Amazon 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 |
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 Amazon Local Zone in Los Angeles (LA). Added: Extract AZ from instance metadata to provide compatibility for Amazon 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:
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 Amazon 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 |
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 Amazon 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 |
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 |
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 Amazon 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 |
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 |
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 Amazon 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 Amazon 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 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
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 Amazon CodeDeploy console
or the Amazon 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
andBeforeInstall
scripts to run. An example file name isacde1916-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 incodedeploy-agent.log
. Tomorrow, on January 4, 2018, the log file is renamedcodedeploy-agent.20180103.log
. -
codedeploy-agent-deployments.log compiles the contents of
scripts.log
files for each deployment. Thescripts.log
files are located in thelogs
subfolder under eachDeployment 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 ofd-ABCDEF123
. Whencodedeploy-agent-deployments.log
reaches its maximum size, the CodeDeploy agent continues to write to it while deleting old content.
-