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.
Allowing access to AWS API or private network
Both the Terraform and CloudFormation configs will create a default run IAM role and a tasks
security group. Task runners created by the ECS agent will be ECS tasks with this IAM role and
belonging to this security group.
If a task needs to access an AWS resource via the AWS API, you should make sure that the run IAM
role
has the correct policy attached.
If a task needs to access internal resouces via the network (e.g. an internal API endpoint or a RDS
database), you should make sure that the VPC is selected correctly, and that the security group for
the internal resource has an ingress rule that
references the tasks security group
to allow Airplane tasks to access that resource.
Custom tasks security group
If you need to use custom security groups for your tasks, you can set the
VpcSecurityGroupIDs
parameter in the CloudFormation stack, or the vpc_security_group_ids
variable in the Terraform
module. Task runners will be created with the provided security groups instead of the default tasks
security group.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.
Configuring task CPU and memory
By default, each task runner is allocated 1 vCPU and 1GB of memory. To change this for all task
runners, you can set the
DefaultTaskCPU
and DefaultTaskMemory
(Cloud Formation) or
default_task_cpu
and default_task_memory
(Terraform) agent config parameters.Alternatively, to adjust this on a task-by-task basis, you can set the
AIRPLANE_TASK_CPU
and
AIRPLANE_TASK_MEMORY
environment variables in the associated tasks.Whether overriding these values in the agent configs or in the environment, keep in mind that
Fargate only allows certain combinations of CPU and memory; see the
AWS documentation
for more details.
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
.Image cache
The Airplane Terraform and CloudFormation configs will create a private ECR repository in your
account as a pull-through cache for Airplane-hosted images. This helps improve task start
performance and can also reduce your organization's network ingress costs.
The image caching feature is enabled by default, but if you want to turn it off you can either set
ecr_cache = false
(if using the Terraform module) or ECRCache
to false
(if using the
CloudFormation template).