Machine Runner in AWS ECS

Users of CircleCI’s self-hosted runner may want to implement a scalable containerized solution to replicate Docker environment executions. While Container Runner is suitable for those wanting to use their Kubernetes cluster for containerized runner execution, not everyone has access to a Kubernetes cluster.

This guide outlines the use of the CircleCI Machine Runner agent within a containerized environment in AWS ECS.

• Scalability:

  • AWS ECS allows for easy scaling of resources to accommodate varying workloads, enabling dynamic resource adjustments based on demand.

• Cost Efficiency:

  • AWS ECS provides cost-effective pricing models for resource utilization, allowing users to pay only for the compute resources they use, leading to cost savings.

• Security:

  • AWS ECS offers robust security features like role-based access control, encryption, and secure networking.

• Integration with AWS Services:

  • ECS seamlessly integrates with AWS services such as Amazon S3, IAM, and CloudWatch, enhancing CI/CD pipelines and creating a cohesive development ecosystem.

This solution is ideal for customers looking to use a self-hosted runner in a private and secure environment within their infrastructure without the overhead of managing individual VMs.

• Terraform
• An AWS network, such as a VPC and subnets. Refer to this guide for networking requirements.

Visit the Github repo for a template on creating an ECS cluster, along with its associated features including logging to Cloudwatch.

1. Firstly, a CircleCI Resource Class token will be required. Check out this guide for further information on generating the resource class and associated token. Take note of the generated token
2. Store the resource class token in an AWS Parameter Store. The generated ARN will be required in the variables.tf
3. Populate the rest of the variables with the relevant values e.g. VPC ARN, subnets. Specify which AWS profile to use from the AWS credentials file.
4. Execute a terraform init command to initialise the installation
5. terraform plan allows you to preview the changes that Terraform plans to make. Any issues with permissions or variables will most likely happen at this stage.
6. Once output from the terraform plan command is correct and as expected, execute terraform apply to install the cluster.

Once terraform apply has been executed successfully, the cluster, service, and task should be running successfully. If there are any issues with any of these services, check out the logs in Cloudwatch for further information.

To execute a task on CircleCI using the newly created ECS task, use this config to get started (replacing <my-namespace>/<my-resource-class> with the relevant values created in step 1 above):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

version: 2.1

jobs:
  test_ecs:
    machine: true
    resource_class: my-namespace/my-resource-class
    steps:
      - run: echo "I'm using an ECS Runner"

workflows:
  my-workflow:
    jobs:
      - test_ecs

• Customize Runner Image:

  • Extend the default runner image to include any additional custom tooling.

• Cluster Expansion:

  • Increase the cluster’s resource capacity by incorporating different resource class sizes (e.g., small/medium/large), with adjustments in CPU & RAM settings as needed.

• Auto-Scaling Solution:

  • Implement a solution to automatically scale the number of desired_tasks in the ECS service during periods of high workload.