Upgrading to CircleCI 2.0

Gruntwork Customers
1

CircleCI released version 2.0 at the end of last year. This is a major new release that adds:

  • Support for the latest version of Docker.
  • Support for Docker layer caching (faster builds).
  • The ability to run the build in a custom Docker image that has all your dependencies already installed (even faster builds).
  • More powerful caching options (even more faster builds).
  • Workflows, such as triggering builds on a schedule (e.g., nightly) or with manual approvals.

The sample apps in the Gruntwork Reference Architecture were still using 1.0, and a number of customers asked us for help on upgrading. Here’s how you can update to CircleCI 2.0:

  1. First, read the 1.0 to 2.0 migration guide so you understand how 2.0 is different. You may also want to familiarize yourself with the 2.0 tutorials, as the new syntax is not very intuitive.

  2. Create a .circleci folder in your app repos and put a config.yml file inside of it. You’ll need to migrate the logic you currently have in circle.yml to this new format. If you bought the Reference Architecture, you can copy this config.yml example from the Acme samples. Note that CircleCI 2.0’s ability to run builds for specific tags is a bit crippled, so pay special attention to how the example explicitly runs builds on all branches and tags and the deploy.sh script is what does the filtering.

  3. Optional: Instead of installing dependencies every time a build runs, you can speed up the build significantly by creating a custom Docker image in which to run the build. If you bought the Reference Architecture, you can copy this Dockerfile example from the Acme samples, which installs Terraform, Terragrunt, Git, the AWS CLI, and Gruntwork’s module-ci build helpers. Pay special attention to the use of a multi-stage build, which allows us to access private GitHub repos without leaking your GitHub access token! You’ll need to build a Docker image from your Dockerfile, push it to your Docker registry (e.g., ECR), and update .circleci/config.yml to use it.

  4. Optional: To enable Docker layer caching, which can significantly speed up your Docker builds, you’ll need to have a paid CircleCI plan and file a support ticket with CircleCI as documented here.

  5. Delete circle.yml and any old _ci folder you may have.

Check out this commit to see all the changes in one place.

Any commit to your app repos should now run your tests. Commits to master should automatically deploy to staging. Tags of the form release-xxx should automatically deploy to production.