Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Deploy to AWS

today3 min read
Cloud
Server v4.x
Server v3.x
On This Page

In this how-to guide, you will learn how to configure CircleCI to deploy to Amazon Web Services.

Introduction

This page covers deployment to S3, ECR/ECS (Elastic Container Registry/Elastic Container Service), as well as application deployment using AWS Code Deploy.

For more detailed information about the AWS S3, ECS, ECR, and CodeDeploy orbs, refer to the following orb registry pages:

In addition to the orb described below, CircleCI has created an AWS convenience image focusing deployment: cimg/aws.

Deploy to S3 using the AWS S3 orb

For detailed information about the AWS S3 orb, refer to the CircleCI AWS S3 Orb Reference page. This section details the use of the AWS S3 orb and version: 2.1 configuration for simple deployment, below we will look at the same example without orbs and using version: 2 configuration.

1. Create IAM user

2. Add AWS access keys

Add your AWS access keys to CircleCI – store your Access Key ID in a variable called AWS_ACCESS_KEY_ID and your Secret Access Key in a variable called AWS_SECRET_ACCESS_KEY.

3. Deploy using orb

Use the orb’s sync command to deploy. Note the use of workflows to deploy only if the build job passes and the current branch is main.

Make sure to replace any placeholder versions in the example.

version: 2.1

orbs:
  aws-s3: circleci/aws-s3@3.1.1 # use the AWS S3 orb in your configuration

workflows: # Define a Workflow running the build job, then the deploy job
  build-deploy: # Make a workflow to build and deploy your project
    jobs:
      - build
      - deploy:
          requires:
            - build # Only run deploy job once the build job has completed
          filters:
            branches:
              only: main # Only deploy when the commit is on the Main branch

jobs: # Define the build and deploy jobs
  build:
    docker: # Use the Docker executor for the build job
      - image: <image-name-and-tag> # Specify the Docker image to use for the build job
    steps:
      - checkout # build job steps omitted for brevity
  deploy:
    docker: # Use the Docker executor for the deploy job
      - image: <image-name-and-tag>  # Specify the Docker image to use for the deploy job
    steps:
      - checkout
      - aws-s3/sync:
          from: bucket
          to: 's3://my-s3-bucket-name/prefix'
          arguments: | # Optional arguments
            --acl public-read \
            --cache-control "max-age=86400"

Deploy to S3 without orbs

1. Create IAM user

For security best practice, create a new IAM user specifically for CircleCI.

2. Add AWS access keys

Add your AWS access keys to CircleCI – store your Access Key ID in a variable called AWS_ACCESS_KEY_ID and your Secret Access Key in a variable called AWS_SECRET_ACCESS_KEY.

3. Create deploy job

In your .circleci/config.yml file, create a new deploy job. In the deploy job, add a step to install awscli in your primary container.

4. Install the AWS CLI

Install awscli in your primary container by following the AWS CLI documentation.

5. Deploy with the AWS CLI

Use the AWS CLI to deploy your application to S3 or perform other AWS operations. Note the use of workflows to deploy only if the build job passes and the current branch is main.

Make sure to replace any placeholder versions in the example.

version: 2.1

workflows: # Define a Workflow running the build job, then the deploy job
    build-deploy:
    jobs:
        - build
        - deploy:
            requires:
            - build
            filters:
            branches:
                only: main # Only deploys when the commit is on the Main branch

jobs:
    build:
    docker: # Specify executor for running build job - this example uses a Docker container
        - image: <docker-image-name-tag> # Specify docker image to use
    ... # build job steps omitted for brevity
    deploy:
    docker: # Specify executor for running deploy job
        - image: <docker-image-name-tag> # Specify docker image to use
    steps:
        - run: # Install the AWS CLI if it is not already included in the docker image
            name: Install awscli
            command: sudo pip install awscli
        - run: # Deploy to S3 using the sync command
            name: Deploy to S3
            command: aws s3 sync <path/to/bucket> <s3://location/in/S3-to-deploy-to>

For a complete list of AWS CLI commands and options, see the AWS CLI Command Reference.

Deploy Docker image to AWS ECR

The AWS ECR orb enables you to log into AWS, build, and then push a Docker image to AWS Elastic Container Registry with minimal config. See the orb registry page for a full list of parameters, jobs, commands and options.

Using the build-and-push-image job (shown below) requires the following environment variables to be set: AWS_ECR_ACCOUNT_URL, ACCESS_KEY_ID, SECRET_ACCESS_KEY, AWS_DEFAULT_REGION.

Make sure to replace any placeholder versions in the example.

version: 2.1

orbs:
  aws-ecr: circleci/aws-ecr@x.y.z # Use the AWS ECR orb in your configuration

workflows:
  build_and_push_image:
    jobs:
      - aws-ecr/build-and-push-image: # Use the pre-defined `build-and-push-image` job
          dockerfile: <my-Docker-file>
          path: <path-to-my-Docker-file>
          profile-name: <my-profile-name>
          repo: <my-ECR-repo>
          tag: <my-ECR-repo-tag> # default - latest

Update an AWS ECS instance

Use the AWS ECR and ECS orbs to easily update an existing AWS ECS instance.

Using the build-and-push-image job (shown below) requires the following environment variables to be set: AWS_ECR_ACCOUNT_URL, ACCESS_KEY_ID, SECRET_ACCESS_KEY, AWS_DEFAULT_REGION.

Make sure to replace any placeholder versions in the example.

version: 2.1

orbs:
  aws-ecr: circleci/aws-ecr@x.y.z # Use the AWS ECR orb in your configuration
  aws-ecs: circleci/aws-ecs@x.y.z # Use the AWS ECS orb in your configuration

workflows:
  build-and-deploy:
    jobs:
      - aws-ecr/build-and-push-image:
          dockerfile: <my-Docker-file>
          path: <path-to-my-Docker-file>
          profile-name: <my-profile-name>
          repo: ${MY_APP_PREFIX}
          tag: '${CIRCLE_SHA1}'
      - aws-ecs/deploy-service-update:
          requires:
            - aws-ecr/build-and-push-image # only run the deployment job once the build and push image job has completed
          family: '${MY_APP_PREFIX}-service'
          cluster: '${MY_APP_PREFIX}-cluster'
          container-image-name-updates: 'container=${MY_APP_PREFIX}-service,tag=${CIRCLE_SHA1}'

AWS CodeDeploy

The AWS CodeDeploy orb enables you to run deployments through AWS CodeDeploy.

Make sure to replace any placeholder versions in the example.

version: 2.1 # use 2.1 to make use of orbs and pipelines

orbs:
  aws-code-deploy: circleci/aws-code-deploy@x.y.z # Use the AWS CodeDeploy orb in your configuration

workflows:
  deploy_application:
    jobs:
      - aws-code-deploy/deploy:
          application-name: <my-application> # The name of an AWS CodeDeploy application associated with the applicable IAM user or AWS account.
          deployment-group: <my-deployment-group> # The name of a new deployment group for the specified application.
          service-role-arn: <my-deployment-group-role-ARN> # The service role for a deployment group.
          bundle-bucket: <my-application-S3-bucket> # The s3 bucket where an application revision will be stored.
          bundle-key: <my-S3-bucket-key> # A key under the s3 bucket where an application revision will be stored.

Suggest an edit to this page

Make a contribution
Learn how to contribute