Deploy to AWS with CodeDeploy

These options provide you with a simplified way of deploying to AWS Cloud. This approach requires less maintenance since the pipeline is maintained on your behalf. 

Before you begin

To deploy your application with AWS CodeDeploy pipe you’ll need to have:

  • An IAM user is configured with sufficient permissions to allow the pipe to perform a deployment to your application and upload artifacts to the S3 bucket.

  • An EC2 instance configured for CodeDeploy : Working with Amazon EC2 Instances for CodeDeploy.

  • You have configured a CodeDeploy Application and Deployment Group. Here is a simple tutorial from AWS: Create an Application and Deployment Group.

  • Set up an AWS S3 bucket where deployment artifacts will be copied. The default follows the convention <application_name>-codedeploy-deployment. Note: Bucket name must be DNS-compliant (must not contain uppercase characters. Bucket name must start with a lowercase letter or number).

Steps

  1. Clone the AWS CodeDeploy pipe example repository.

  2. Add your AWS credentials to Bitbucket Pipelines. In your Bitbucket Repository go to Settings, under Pipelines, select Repository variables and add the following variables.

Common Variables

  • AWS_ACCESS_KEY_ID (*): Your AWS access key.

  • AWS_SECRET_ACCESS_KEY (*): Your AWS secret access key. Make sure that you save it as a secured variable.

  • AWS_DEFAULT_REGION (*):  The AWS region code (us-east-1, us-west-2, etc.) of the region containing the AWS resources. For more information, see Regions and Endpoints in the Amazon Web Services General Reference.

  • APPLICATION_NAME (*): Application name.

  • COMMAND (*): Mode of operation: upload or deploy. See the Details section to understand how each mode works.

  • DEBUG: Turn on extra debug information. Default: false.

(*) = required variable

Upload Command Variables

If COMMAND is set to upload:

  • ZIP_FILE (*): The application artifact to upload to S3. Required for 'update'

  • S3_BUCKET: Override the S3 bucket that the application zip is uploaded to and deployed from. The default follows the convention <application_name>-codedeploy-deployment

  • VERSION_LABEL: Override the name of the application revision in S3. The default follows the convention <application_name>-<build_number>-<commit>

(*) = required variable

Deploy Command Variables

If COMMAND is set to deploy:

  • DEPLOYMENT_GROUP (*): Name of the Deployment Group.

  • S3_BUCKET: Override the S3 bucket that the application zip is uploaded to and deployed from. The default follows the convention <application_name>-codedeploy-deployment.

  • VERSION_LABEL: Override the name of the application revision in S3. The default follows the convention <application_name>-<build_number>-<commit>.

  • WAIT: Wait for the deployment to complete. Default: true.

  • FILE_EXISTS_BEHAVIOR: Action to take if files already exist in the deployment target location (defined in the AppSpec file). Allowed values: OVERWRITE, DISALLOW, RETAIN, default: DISALLOW.

  • IGNORE_APPLICATION_STOP_FAILURES: Ignore any errors thrown when trying to stop the previous version of the deployed application. Default: false.

  • EXTRA_ARGS: Additional args to pass to aws deploy create-deployment.

(*) = required variable

Details

The pipe provides 2 modes of operation: Upload and Deploy

Upload

Upload the application (as a zip file) to an S3 bucket, and register a new application revision with CodeDeploy. By default, the zip file is uploaded to an S3 bucket following the naming convention <application_name>-codedeploy-deployment, which can be overridden with the S3_BUCKET parameter.

The uploaded zip artifact will be named <application_name>-<build_number>-<commit>, which can be overridden with the VERSION_LABEL parameter.

Deploy

Deploy a previously uploaded application revision to a deployment group. By default, the revision S3 bucket containing the revision follows the naming convention <application_name>-codedeploy-deployment, which can be overridden with the S3_BUCKET parameter.

The pipe will attempt to deploy the application revision matching <application_name>-<build_number>-<commit>, which can be overridden with the VERSION_LABEL parameter, and wait until deployment has succeeded.

Caveats

  • When you use the deploy mode with the default VERSION_LABEL, the pipe will generate a new version label based on the build number and commit hash, so you need to make sure to also run the pipe with the upload mode within the same pipeline so the corresponding version is preset in S3. If you don't run the upload part of the pipe in the same pipeline, you should use explicit VERSION_LABEL, for example, use semantic or another versioning scheme that is decoupled from the build number.

Examples

Upload

Upload the application myapp.zip to S3 bucket called my-application-codedeploy-deployment, with the application uploaded to S3 as my-application-<build-number>-<commit>.

1 2 3 4 5 6 7 8 9 script: - pipe: atlassian/aws-code-deploy:0.2.10 variables: AWS_DEFAULT_REGION: 'ap-southeast-2' AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY COMMAND: 'upload' APPLICATION_NAME: 'my-application' ZIP_FILE: 'myapp.zip'


Upload the application myapp.zip to custom S3 bucket called my-bucket, with the application uploaded to S3 as my-app-1.0.0.

1 2 3 4 5 6 7 8 9 10 11 script: - pipe: atlassian/aws-code-deploy:0.2.10 variables: AWS_DEFAULT_REGION: 'ap-southeast-2' AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY COMMAND: 'upload' APPLICATION_NAME: 'my-application' ZIP_FILE: 'myapp.zip' S3_BUCKET: 'my-bucket' VERSION_LABEL: 'my-app-1.0.0'


Deploy

Start a deployment and wait for it to finish. The application revision my-application-<build-number>-<commit> from the S3 bucket my-application-codedeploy-deployment will be deployed.

1 2 3 4 5 6 7 8 9 10 script: - pipe: atlassian/aws-code-deploy:0.2.10 variables: AWS_DEFAULT_REGION: 'ap-southeast-2' AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY COMMAND: 'deploy' APPLICATION_NAME: 'my-application' DEPLOYMENT_GROUP: 'my-deployment-group' WAIT: 'true'

Start a deployment, referencing an application revision uploaded to a custom location in S3. The application revision my-app-1.0.0 from the S3 bucket my-bucket will be deployed.

1 2 3 4 5 6 7 8 9 10 11 12 13 script: - pipe: atlassian/aws-code-deploy:0.2.10 variables: AWS_DEFAULT_REGION: 'ap-southeast-2' AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY COMMAND: 'deploy' APPLICATION_NAME: 'my-application' DEPLOYMENT_GROUP: 'my-deployment-group' WAIT: 'true' S3_BUCKET: 'my-bucket' VERSION_LABEL: 'my-app-1.0.0'

Start a deployment, and ignore any application stop failures, and force overwrite previous deployment files.

1 2 3 4 5 6 7 8 9 10 11 12 script: - pipe: atlassian/aws-code-deploy:0.2.10 variables: AWS_DEFAULT_REGION: 'ap-southeast-2' AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY COMMAND: 'deploy' APPLICATION_NAME: 'my-application' DEPLOYMENT_GROUP: 'my-deployment-group' WAIT: 'true' IGNORE_APPLICATION_STOP_FAILURES: 'true' FILE_EXISTS_BEHAVIOR: 'OVERWRITE'

 

When you use the deploy mode with the default VERSION_LABEL, the pipe generates a new version label based on the build number and commit hash. You need to make sure to also run the pipe with the upload mode within the same pipeline so the corresponding version is preset in S3. If you don't run the upload part of the pipe in the same pipeline, you should use explicit VERSION_LABEL, for instance, use a versioning scheme that is decoupled from the build number.

Additional Help