Deploy to AWS

Cloud

Server v4.x

Server v3.x

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

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. 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@9.3.6 # Use the AWS ECR orb in your configuration
  aws-cli: circleci/aws-cli@5.1.1 # Use the AWS CLI 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
          auth:
            - aws-cli/setup:
                role_arn: arn:aws:iam::123456789012
          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 update an existing AWS ECS instance.

Using the build-and-push-image job (shown below) requires the following environment variables to be set: OIDC-USER, AWS__DEFAULT_REGION, MY_APP_PREFIX.

Make sure to replace any placeholder versions in the example.

version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.1.0
  aws-ecr: circleci/aws-ecr@9.3.4
  aws-ecs: circleci/aws-ecs@6.0.0
workflows:
  build-and-deploy:
    jobs:
      - aws-ecr/build_and_push_image:
          auth:
            - aws-cli/setup:
                profile_name: OIDC-USER
                role_arn: arn:aws:iam::123456789012:role/VALID_OIDC_ECR_ROLE
          profile_name: OIDC-USER
          repo: MY_APP_PREFIX
          tag: CIRCLE_SHA1 # This is a built-in environment variable
      - aws-ecs/deploy_service_update:
          auth:
            - aws-cli/setup:
                profile_name: OIDC-USER
                role_arn: arn:aws:iam::123456789012:role/VALID_OIDC_ECS_ROLE
          cluster: MY_APP_PREFIX-cluster
          container_image_name_updates: container=${MY_APP_PREFIX}-service,tag=${CIRCLE_SHA1}
          family: MY_APP_PREFIX-service
          profile_name: OIDC-USER
          requires:
            - aws-ecr/build_and_push_image