Running the agent on AWS EC2

Deploy a self-hosted Airplane agent on AWS with EC2 Auto Scaling groups

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:

This method of running the agent on AWS will use EC2 Auto Scaling groups. It is also possible to use ECS to set up the Airplane agent:

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-cluster Terraform module.

See the Terraform module page for the full module documentation.

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

hcl
Copied
1
module "airplane_agent" {
2
source = "airplanedev/airplane-cluster/aws"
3
4
api_token = "YOUR_API_TOKEN"
5
team_id = "YOUR_TEAM_ID"
6
# Set which VPC / subnets agents should live in
7
vpc_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
}

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

You should be able to terraform apply—that's it! Visit app.airplane.dev/settings/team and confirm that an agent has now appeared:

IAM policies

You can attach IAM policies to your agents. This allows agents to use the policy to access AWS resources. For example, you might want to provide ECR read access in order to run tasks or runbooks with private ECR images.

hcl
Copied
1
module "airplane_agent" {
2
source = "airplanedev/airplane-cluster/aws"
3
4
# ... omitted
5
# Attach necessary IAM policies to e.g. allow agent to pull images from ECR
6
managed_policy_arns = [
7
# You can attach your own policy (see resource below)
8
aws_iam_policy.agent.arn,
9
# You can attach an AWS-managed policy
10
"arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly",
11
]
12
}
13
14
resource "aws_iam_policy" "agent" {
15
name_prefix = "airplane-agent-"
16
path = "/"
17
description = "Policy for agents"
18
19
policy = <<EOF
20
{
21
"Version": "2012-10-17",
22
"Statement": [
23
{
24
"Effect": "Allow",
25
"Action": [
26
"ecr:GetAuthorizationToken",
27
"ecr:GetDownloadUrlForLayer",
28
"ecr:BatchGetImage"
29
],
30
"Resource": "*"
31
}
32
]
33
}
34
EOF
35
}

Security groups

You can add additional security groups and optionally disable the default security group.

hcl
Copied
1
# Additional security groups
2
vpc_security_group_ids = ["sg-222"]
3
4
# Disable the default group—if disabled, you must ensure one of the attached security groups
5
# allows HTTPS egress to Airplane APIs.
6
create_egress_security_group = false

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 https://airplane-aws-stack.s3.amazonaws.com/stack.yaml—for your convenience, you can use one of the below links to launch the stack in the appropriate region:

(Contact us if you need a region that isn't listed above—we're happy to add more regions upon request.)

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 API Token: generate this by running airplane apikeys create "Cloudformation" from the CLI.
  • Airplane Team ID: retrieve this by running airplane auth info.
  • VPC ID: choose the VPC you want to deploy the agent into.
  • Subnet IDs: choose the VPC subnet(s) you want to deploy the agent into. These subnets must be in the VPC you chose above!
  • Instance Count, Instance Type: you can leave the default or change to your liking.
  • IAM Policy ARNs: You can leave this blank to start, although you'll likely want to attach additional permissions to the agent for any tasks that use the AWS API.
    • If there are IAM permissions you'd like to assign to the agent (such as being able to pull ECR images), create a new IAM policy and enter the policy ARN here.
    • You can also attach existing IAM policies, such asarn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly (allow reading from all ECR repositories) and arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess (allow reading from all S3 buckets).

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.