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 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:
hcl
Copied
1
module "airplane_agent" {
2
  source  = "airplanedev/airplane-agents/aws"
3


4
  api_token              = "YOUR_API_TOKEN"
5
  team_id                = "YOUR_TEAM_ID"
6
  # Set which VPC / subnets agents should live in
7
  subnet_ids         = ["subnet-000", "subnet-111"]
8


9
  # Optional: attach labels to agents for constraints
10
  agent_labels = {
11
    vpc = "123"
12
    env = "test"
13
  }
14


15
  # Optional: if set, only allows agents to execute runs from environment
16
  # with the provided slug
17
  env_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:
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.
PrivacyTermsSupport