Running the agent on AWS
Deploy a self-hosted Airplane agent on AWS with ECS and Fargate
Airplane supports easy installation via Terraform or
AWS CloudFormation.
To follow the installation instructions below, you'll need the following values:
YOUR_API_TOKEN
: generate a new token by runningairplane apikeys create <token name>
from the Airplane CLI.YOUR_TEAM_ID
: get your team ID viaairplane 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
:hclCopied1module "airplane_agent" {2source = "airplanedev/airplane-agents/aws"34api_token = "YOUR_API_TOKEN"5team_id = "YOUR_TEAM_ID"6# Set which VPC / subnets agents should live in7subnet_ids = ["subnet-000", "subnet-111"]89# Optional: attach labels to agents for constraints10agent_labels = {11vpc = "123"12env = "test"13}1415# Optional: if set, only allows agents to execute runs from environment16# with the provided slug17env_slug = ""18}
For details on using labels, see
Execute rules & constraints.
For details on using environments, see Environments.
You should be able to
terraform apply
—that's it! Visit
app.airplane.dev/settings/team 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 of the CloudFormation stack is available at
https://airplane-aws-stack.s3.amazonaws.com/agentv2-stack-fargate.yaml—for
your convenience, you can use the below link to launch the stack:
- Create CloudFormation stack
- To change regions, use the region switcher after opening the above link.
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
https://app.airplane.dev/agents 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.
Fargate capacity
By default, AWS only allows a total of 6 Fargate vCPU across all running workloads per account
region
(source).
If you're running more than a handful of Airplane tasks simultaneously, you'll want to request a
quota increase via the AWS console.
If you hit this limit, tasks will take a long time to start, and the agent logs will show errors
like
capacity is unavailable at this time. Please try again later or in a different availability zone
.ECR cache
This feature is currently in beta. If you have any feedback on it, please send a message to
support@airplane.dev!
The Airplane Terraform and CloudFormation configs now support using a private ECR repository in your
account as a pull-through cache for Airplane-hosted images. This can help improve task start
performance and also reduce your organization's network ingress costs.
To enable this feature, either set
ecr_cache = true
(if using the Terraform module) or ECRCache
to true
(if using the CloudFormation template). You'll then see a new ECR repository in the agent
account and region that's opportunistically populated with upstream Airplane images. The agent will
periodically clean the images in this repository to minimize storage costs.