Use the CodeDeploy agent to validate a deployment package on a local machine
Using the CodeDeploy agent, you can deploy content on an instance you are logged in to. This allows you to test the integrity of an application specification file (AppSpec file) that you intend to use in a deployment and the content you intend to deploy.
You do not need to create an application and deployment group. If you want to deploy content stored on the local instance, you do not even need an AWS account. For the simplest testing, you can run the codedeploy-local command, without specifying any options, in a directory that contains the AppSpec file and the content to be deployed. There are options for other test cases in the tool.
By validating a deployment package on a local machine you can:
-
Test the integrity of an application revision.
-
Test the contents of an AppSpec file.
-
Try out CodeDeploy for the first time with your existing application code.
-
Deploy content rapidly when you are already logged in to an instance.
You can use deploy content that is stored on the local instance or in a supported remote repository type (Amazon S3 buckets or public GitHub repositories).
Prerequisites
Before you start a local deployment, complete the following steps:
-
Create or use an instance type supported by the CodeDeploy agent. For information, see Operating systems supported by the CodeDeploy agent.
-
Install version 1.0.1.1352 or later of the CodeDeploy agent. For information, see Install the CodeDeploy agent.
-
If you are deploying your content from an Amazon S3 bucket or GitHub repository, provision a user to use with CodeDeploy. For information, see Step 1: Setting up.
-
If you are deploying your application revision from an Amazon S3 bucket, create an Amazon S3 bucket in the region you are working in and apply an Amazon S3 bucket policy to the bucket. This policy grants your instances the permissions required to download the application revision.
For example, the following Amazon S3 bucket policy allows any Amazon EC2 instance with an attached IAM instance profile containing the ARN
arn:aws:iam::444455556666:role/CodeDeployDemo
to download from anywhere in the Amazon S3 bucket namedamzn-s3-demo-bucket
:{ "Statement": [ { "Action": [ "s3:Get*", "s3:List*" ], "Effect": "Allow", "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*", "Principal": { "AWS": [ "arn:aws:iam::444455556666:role/CodeDeployDemo" ] } } ] }
The following Amazon S3 bucket policy allows any on-premises instance with an associated IAM user containing the ARN
arn:aws:iam::444455556666:user/CodeDeployUser
to download from anywhere in the Amazon S3 bucket namedamzn-s3-demo-bucket
:{ "Statement": [ { "Action": [ "s3:Get*", "s3:List*" ], "Effect": "Allow", "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*", "Principal": { "AWS": [ "arn:aws:iam::444455556666:user/CodeDeployUser" ] } } ] }
For information about how to generate and attach an Amazon S3 bucket policy, see Bucket policy examples.
-
If you are deploying your application revision from an Amazon S3 bucket or GitHub repository, set up an IAM instance profile and attach it to the instance. For information, see Step 4: Create an IAM instance profile for your Amazon EC2 instances, Create an Amazon EC2 instance for CodeDeploy (AWS CLI or Amazon EC2 console), and Create an Amazon EC2 instance for CodeDeploy (AWS CloudFormation template).
-
If you are deploying your content from GitHub, create a GitHub account and a public repository. To create a GitHub account, see Join GitHub
. To create a GitHub repository, see Create a repo . Note
Private repositories are not currently supported. If your content is stored in a private GitHub repository, you can download it to the instance and use the
--bundle-location
option to specify its local path. -
Prepare the content (including an AppSpec file) that you want to deploy to the instance and place it on the local instance, in your Amazon S3 bucket, or in your GitHub repository. For information, see Working with application revisions for CodeDeploy.
-
If you want to use values other than the defaults for other configuration options, create the configuration file and place it on the instance (
/etc/codedeploy-agent/conf/codedeployagent.yml
for Amazon Linux, RHEL, or Ubuntu Server instances orC:\ProgramData\Amazon\CodeDeploy\conf.yml
for Windows Server instances). For information, see CodeDeploy agent configuration reference.Note
If you use a configuration file on Amazon Linux, RHEL, or Ubuntu Server instances, you must either:
-
Use the
:root_dir:
and:log_dir:
variables to specify locations other than the defaults for the deployment root and log directory folders. -
Use
sudo
to run CodeDeploy agent commands.
-
Create a local deployment
On the instance where you want to create the local deployment, open a terminal session (Amazon Linux, RHEL, or Ubuntu Server instances) or a command prompt (Windows Server) to run the tool commands.
Note
The codedeploy-local command is installed in the following locations:
-
On Amazon Linux, RHEL, or Ubuntu Server:
/opt/codedeploy-agent/bin
. -
On Windows Server:
C:\ProgramData\Amazon\CodeDeploy\bin
.
Basic Command Syntax
codedeploy-local [options]
Synopsis
codedeploy-local [--bundle-location <value>] [--type <value>] [--file-exists-behavior <value>] [--deployment-group <value>] [--events <comma-separated values>] [--agent-configuration-file <value>] [--appspec-filename <value>]
Options
-l, --bundle-location
The location of the application revision bundle. If you do not specify a location, the
tool uses the directory you are currently working in by default. If you specify a value for
--bundle-location
, you must also specify a value for
--type
.
Bundle location format examples:
-
Local Amazon Linux, RHEL, or Ubuntu Server instance:
/path/to/local/bundle.tgz
-
Local Windows Server instance:
C:/path/to/local/bundle
-
Amazon S3 bucket:
s3://amzn-s3-demo-bucket/bundle.tar
-
GitHub repository:
https://github.com/
account-name
/repository-name
/
-t, --type
The format of the application revision bundle. Supported types include tgz
,
tar
, zip
, and directory
. If you do not specify a
type, the tool uses directory
by default. If you specify a value for
--type
, you must also specify a value for
--bundle-location
.
-b, --file-exists-behavior
Indicates how files are handled that already exist in a deployment target location but weren't part of a previous successful deployment. Options include DISALLOW, OVERWRITE, RETAIN. For more information, see fileExistsBehavior in AWS CodeDeploy API Reference.
-g, --deployment-group
The path to the folder that is the target location for the content to be deployed. If you do not specify a folder, the tool creates one named default-local-deployment-group inside your deployment root directory. For each local deployment you create, the tool creates a subdirectory inside this folder with names such as d-98761234-local.
-e, --events
A set of override lifecycle event hooks you want to run, in order, instead of the events you listed in the AppSpec file. Multiple hooks can be specified, separated by commas. You can use this option if:
-
You want to run a different set of events without having to update the AppSpec file.
-
You want to run a single event hook as an exception to what's in the AppSpec file, such as
ApplicationStop
.
If you don't specify DownloadBundle and Install events in the override list, they will run before all the
event hooks you do specify. If you include DownloadBundle
and Install in the list of --events
options,
they must be preceded only by events that normally run before them in CodeDeploy deployments. For
information, see AppSpec 'hooks' section.
-c, --agent-configuration-file
The location of a configuration file to use for the deployment, if you store it in a location other than the default. A configuration file specifies alternatives to other default values and behaviors for a deployment.
By default, configuration files are stored in
/etc/codedeploy-agent/conf/codedeployagent.yml
(Amazon Linux, RHEL, or
Ubuntu Server instances) or C:/ProgramData/Amazon/CodeDeploy/conf.yml
(Windows Server). For more information, see CodeDeploy agent configuration reference.
-A, --appspec-filename
The name of the AppSpec file. For local deployments, accepted values are
appspec.yml
and appspec.yaml
. By default, the
AppSpec file is called
appspec.yml
.
-h, --help
Displays a summary of help content.
-v, --version
Displays the tool's version number.
Examples
The following are examples of valid command formats.
codedeploy-local
codedeploy-local --bundle-location /path/to/local/bundle/directory
codedeploy-local --bundle-location C:/path/to/local/bundle.zip --type zip --deployment-group my-deployment-group
codedeploy-local --bundle-location /path/to/local/directory --type directory --deployment-group my-deployment-group
Deploy a bundle from Amazon S3:
codedeploy-local --bundle-location s3://amzn-s3-demo-bucket/bundle.tgz --type tgz
codedeploy-local --bundle-location s3://amzn-s3-demo-bucket/bundle.zip?versionId=1234&etag=47e8 --type zip --deployment-group my-deployment-group
Deploy a bundle from a public GitHub repository:
codedeploy-local --bundle-location https://github.com/awslabs/aws-codedeploy-sample-tomcat --type zip
codedeploy-local --bundle-location https://api.github.com/repos/awslabs/aws-codedeploy-sample-tomcat/zipball/master --type zip
codedeploy-local --bundle-location https://api.github.com/repos/awslabs/aws-codedeploy-sample-tomcat/zipball/HEAD --type zip
codedeploy-local --bundle-location https://api.github.com/repos/awslabs/aws-codedeploy-sample-tomcat/zipball/1a2b3c4d --type zip
Deploy a bundle specifying multiple lifecycle events:
codedeploy-local --bundle-location /path/to/local/bundle.tar --type tar --application-folder my-deployment --events DownloadBundle,Install,ApplicationStart,HealthCheck
Stop a previously deployed application using the ApplicationStop lifecycle event:
codedeploy-local --bundle-location /path/to/local/bundle.tgz --type tgz --deployment-group --events ApplicationStop
Deploy using a specific deployment group ID:
codedeploy-local --bundle-location C:/path/to/local/bundle/directory --deployment-group 1234abcd-5dd1-4774-89c6-30b107ac5dca
codedeploy-local --bundle-location C:/path/to/local/bundle.zip --type zip --deployment-group 1234abcd-5dd1-4774-89c6-30b107ac5dca