Running the agent on AWS ECS

Deploy a self-hosted Airplane agent on AWS with ECS and Fargate

Airplane supports easy installation via Terraform or AWS CloudFormation. If you're using neither Terraform nor CloudFormation, you can also set up the agent manually using Docker:

Airplane recommends running agents using EC2 Auto Scaling groups instead of Fargate. Runs executed on EC2 will start faster than those executed on Fargate. To get started, follow our EC2 Auto Scaling Groups guide.

To follow the installation instructions below, you'll need the following values:

  • YOUR_API_TOKEN: generate a new token by running airplane apikeys create <token name> from the Airplane CLI.
  • YOUR_TEAM_ID: get your team ID via airplane auth info or visit the Team Settings page.

If your team already uses Terraform, we recommend using the Terraform module: Install with Terraform.

Otherwise, for a faster setup you can also use AWS CloudFormation: Install with AWS CloudFormation.

Install with Terraform

If you're already using Terraform, the fastest way to set up a cluster of agents is to use the airplane-agents Terraform module.

See the Terraform module page for the full module documentation.

To deploy into an existing VPC, simply specify the subnet_ids:

module "airplane_agent" {
source = "airplanedev/airplane-agents/aws"
api_token = "YOUR_API_TOKEN"
team_id = "YOUR_TEAM_ID"
# Set which VPC / subnets agents should live in
subnet_ids = ["subnet-000", "subnet-111"]
# Optional: attach labels to agents for constraints
agent_labels = {
vpc = "123"
env = "test"

For details on using labels, see Execute rules & constraints.

You should be able to terraform apply—that's it! Visit and confirm that an agent has now appeared:

Install with AWS CloudFormation

As an alternative to Terraform, you can use AWS CloudFormation as a simpler but less flexible method of installation.

The latest version the CloudFormation stack is available at—for your convenience, you can use the below link to launch the stack:

Upon opening the link above, you should see a screen with a pre-filled Amazon S3 template URL. Click Next.

On the Specify stack details screen, fill in the Parameters:

  • Airplane Team ID: retrieve this by running airplane auth info.
  • Airplane API Token/Airplane API Token Secret: generate this by running airplane apikeys create "Cloudformation" from the CLI.
    • Exactly one of Airplane API Token or Airplane API Token Secret should be used
    • Airplane API Token should be used if you just want to pass the token directly to the Airplane agent via environment variable.
    • Airplane API Token Secret should be used if you wish to use AWS secret manager to manage your Airplane API tokens instead.
  • KMS Key for API Token Secret: optional, if your API Token Secret requires a KMS Key, you can set this to be the required key.
  • Cluster ARN: optional. ARN for the ECS cluster to run the Airplane agents in. If left blank, creates a new cluster for the agents.
  • Subnet IDs: choose the VPC subnet(s) you want to deploy the agent into.
  • VPC ID: choose the VPC that matches the subnets you selected.
  • Service Name: fill in with the name to assign to the ECS service, it can be left as airplane-agent if it doesn't conflict with any other name.

Click Next once you've filled in the Parameters.

On the Configure stack options page, you can optionally set additional tags and settings, but you can also leave the defaults alone.

Click Next.

On the final Review page, check "I acknowledge that AWS CloudFormation might create IAM resources." towards the bottom and click Create stack.

Once the stack has been created, it'll take 2-3 minutes for the agents to boot up. Visit and confirm that an agent has now appeared.

Custom IAM roles

If you need tasks to run with custom IAM roles, you can replace the default IAM role that the AWS ECS agent will use for a specific task. To do this, add an environment variable on the task with name ECS_TASK_ROLE, and set its value to the ARN of the role you want the task to execute with.