Step 1 of https://infrapilot.fly/docs/onboard.md. You create one IAM role that Infrapilot assumes, and submit its ARN. No long-lived keys: Infrapilot assumes the role an hour at a time, only inside the workspace's sandbox.
Before you start
aws sts get-caller-identity # which account the CLI uses
aws configure get region # the project's regionConfirm the account and region with the person. You need iam:CreateRole, iam:PutRolePolicy, and permission to tag resources.
1. Get the role documents
curl -s -H "Authorization: Bearer $INFRAPILOT_TOKEN" $INFRAPILOT_URL/api/v1/setup/aws-role > /tmp/infrapilot-role.json
jq '.trust_policy' /tmp/infrapilot-role.json > /tmp/infrapilot-trust.json
jq '.policies.tune' /tmp/infrapilot-role.json > /tmp/infrapilot-tune.json
jq '.policies.build' /tmp/infrapilot-role.json > /tmp/infrapilot-build.jsontrust_policy: only Infrapilot, with this workspace's external id, can assume the role.policies.observe: for level observe only. Reads configuration, tags, CloudWatch metrics, CloudTrail and the bill (Cost Explorer), and nothing else: every action in it is aDescribe,GetorList, it cannot invoke a function, and it reads bucket settings, not objects. Attach it instead oftuneand submit the connection with"access": "observe"(step 3). AWS's managedReadOnlyAccessalso works, but it can read data (objects, table items); this policy cannot.policies.tune: read the account's configuration (tags, schemas, CloudWatch, CloudTrail, resource settings) and change settings of managed services through Cloud Control. It reads bucket settings but not objects. It does read Lambda configuration and can invoke functions (Pilot's check after changing one), on every function in the account: narrow those statements'Resourceif that is too wide for you. It includesiam:PassRoleto Lambda only, because changing a Lambda through Cloud Control re-submits its execution role. To narrow it, set that statement'sResourceto those execution role ARNs. The same holds for ECS: a new task size is a new revision of the service's task definition, registered as a copy that names the same task and execution roles, sotuneincludesiam:PassRoleto ECS tasks only (KeepTaskRoles). It also reads the bill through Cost Explorer (ce:GetCostAndUsage,ce:ListCostAllocationTags): AWS charges $0.01 per request, and Pilot makes two every six hours.policies.build: create and delete what blueprints use. Attach it only if the spec declares workloads. It can create a database or a cache and never delete one. Its IAM permissions cover only roles namedinfrapilot-*: Pilot can attach policies from one fixed list (AWS's own execution policies for Lambda and ECS, and the three workload policies below), never write a policy of its own, and hand a role to Lambda, ECS tasks or EventBridge Scheduler only. It can add rules to, or delete, only security groups it created.workload_policies: three managed policies you create once when the spec declares a service, a worker or a schedule (step 2). They are for the roles of what Pilot builds, not for Pilot's role. None names a resource: each allows its actions only on what carries the sameinfrapilot:fleettag as the role.InfrapilotWorkloadSecretsreads secrets and parameters,InfrapilotWorkloadQueuesuses SQS queues,InfrapilotWorkloadSchedulesstarts the fleet's ECS tasks.
Show the person these documents and what they allow. They may narrow them; Pilot can't do what the role doesn't allow and will ask for what it lacks.
2. Create the role
aws iam create-role --role-name InfrapilotAgent \
--assume-role-policy-document file:///tmp/infrapilot-trust.json \
--description "Infrapilot's agent: runs this account's infrastructure within the limits in infrapilot.yaml"
aws iam put-role-policy --role-name InfrapilotAgent --policy-name infrapilot-tune \
--policy-document file:///tmp/infrapilot-tune.json
# only when the spec declares workloads for Pilot to build:
aws iam put-role-policy --role-name InfrapilotAgent --policy-name infrapilot-build \
--policy-document file:///tmp/infrapilot-build.json
aws iam get-role --role-name InfrapilotAgent --query Role.Arn --output textWhen the spec declares an http-service, a worker or a schedule, also create the workload policies, and the service-linked roles AWS needs in an account that has never used these services (an "already exists" answer is fine; Pilot is not given the permission to create them):
for name in InfrapilotWorkloadSecrets InfrapilotWorkloadQueues InfrapilotWorkloadSchedules; do
jq ".workload_policies.$name" /tmp/infrapilot-role.json > /tmp/$name.json
aws iam create-policy --policy-name $name --policy-document file:///tmp/$name.json
done
for service in ecs elasticloadbalancing rds elasticache; do
aws iam create-service-linked-role --aws-service-name $service.amazonaws.com
doneFor level observe, attach only the read-only policy:
jq '.policies.observe' /tmp/infrapilot-role.json > /tmp/infrapilot-observe.json
aws iam put-role-policy --role-name InfrapilotAgent --policy-name infrapilot-observe \
--policy-document file:///tmp/infrapilot-observe.jsonIf InfrapilotAgent already exists for another workspace, pick another name (for example InfrapilotAgent-staging).
3. Submit the connection
curl -s -X POST $INFRAPILOT_URL/api/v1/setup/cloud \
-H "Authorization: Bearer $INFRAPILOT_TOKEN" -H "Content-Type: application/json" \
-d '{"kind": "aws_role", "role_arn": "arn:aws:iam::<account>:role/InfrapilotAgent", "region": "<region>"}'For a read-only role add "access": "observe" to the body. Pilot then reviews the account and the engine refuses every change before it is attempted, whatever the spec says.
Infrapilot assumes the role and checks:
| Check | Needs |
|---|---|
credentials | the trust policy exactly as issued |
cloudformation:DescribeType | resource schemas |
cloudformation:ListResources (Cloud Control) | the Cloud Control API (authorized under cloudformation:) |
tag:GetResources | finding tagged resources |
application-autoscaling:DescribeScalableTargets | seeing which values an autoscaler owns |
cloudwatch:GetMetricData | metrics |
cloudtrail:LookupEvents | attributing outside changes |
lambda:GetAccountSettings | account limits |
If credentials fails right after creating the role, wait 15 seconds and resubmit.
If connection.kinds lacks aws_role, use the first kind listed. aws_keys takes {"kind": "aws_keys", "access_key_id", "secret_access_key", "account_id", "region"} for an IAM user with the same policies. Prefer the role when offered.
4. Tag what Pilot should adopt
aws resourcegroupstaggingapi tag-resources \
--resource-arn-list arn:aws:lambda:us-east-1:123456789012:function:checkout-prod \
--tags infrapilot:fleet=shop,infrapilot:name=api- Up to 20 ARNs per call.
infrapilot:fleetmust equalfleetin the spec;infrapilot:nameis the logical name. - A Lambda's event source mappings come with it, named
<function name>-from-<source>unless tagged. - Autoscaling targets and policies on an adopted table or ECS service are adopted automatically. Don't tag them. The same goes for the scaling policies of an EC2 Auto Scaling group.
- Tag an Aurora cluster and its instances come with it, named
<cluster name>-<instance identifier>unless tagged. - For ElastiCache, tag the serverless cache or the replication group, not its nodes.
- New tags show up after a minute or two.
POST /api/v1/setup/discovershows what is seen.
5. Activate the cost allocation tag
Pilot shows what the fleet really costs beside its own estimate. AWS reports cost by tag only for tags activated for cost allocation, and only from the day they are activated:
- Open the Billing and Cost Management console in the organization's management account (or in this account, if it is not part of an organization), and choose Cost allocation tags.
- Under User-defined cost allocation tags, select
infrapilot:fleet(the adopt tag's key, if the spec uses another) and choose Activate. A tag appears in that list up to 24 hours after it was first put on a resource. - If Cost Explorer has never been opened in the account, open it once: AWS enables it on first use.
aws ce update-cost-allocation-tags-status --cost-allocation-tags-status TagKey=infrapilot:fleet,Status=ActiveFigures appear within 24 hours and cover the days since activation. Until then the overview says what is missing and Pilot works from its estimate, which is also what the cost ceiling is held to. The account's whole bill is shown beside the fleet's, so what no tag explains (NAT gateways, data transfer, untagged resources) is visible as "account, not attributed". Cost is by service and day; per-resource figures stay estimates.
What Pilot understands on AWS
Full list: curl -s $INFRAPILOT_URL/api/types/aws.
| Service | Type | Common objectives |
|---|---|---|
| Lambda | AWS::Lambda::Function | Duration (p99, ms), Throttles, Errors |
| Lambda triggers | AWS::Lambda::EventSourceMapping | (tuned: BatchSize, ScalingConfig.MaximumConcurrency) |
| SQS | AWS::SQS::Queue | backlog (live), ApproximateAgeOfOldestMessage |
| DynamoDB | AWS::DynamoDB::Table | WriteThrottleEvents, ReadThrottleEvents |
| Application Auto Scaling | ...::ScalableTarget, ...::ScalingPolicy | (tuned instead of the capacity they own) |
| ECS | AWS::ECS::Service | CPUUtilization, MemoryUtilization (tuned: task count, and task size as TaskCpu, TaskMemory) |
| Kinesis | AWS::Kinesis::Stream | WriteProvisionedThroughputExceeded |
| Aurora | AWS::RDS::DBCluster | ACUUtilization, CPUUtilization, DatabaseConnections (tuned: the Serverless v2 capacity range) |
| RDS | AWS::RDS::DBInstance | CPUUtilization, DatabaseConnections, ReadLatency, WriteLatency (tuned: storage and storage autoscaling) |
| ElastiCache Serverless | AWS::ElastiCache::ServerlessCache | Evictions, ThrottledCmds, BytesUsedForCache (tuned: CacheUsageLimits) |
| ElastiCache nodes | AWS::ElastiCache::ReplicationGroup | DatabaseMemoryUsagePercentage, EngineCPUUtilization, Evictions (observed only) |
| EC2 Auto Scaling | AWS::AutoScaling::AutoScalingGroup, ...::ScalingPolicy | CPUUtilization (tuned: MinSize, MaxSize, the policy's target) |
| Load balancers (ALB, NLB) | AWS::ElasticLoadBalancingV2::LoadBalancer, ...::TargetGroup | TargetResponseTime (p99, ms), HTTPCode_ELB_5XX_Count, HealthyHostCount |
| API Gateway | AWS::ApiGateway::RestApi, AWS::ApiGatewayV2::Api, AWS::ApiGateway::Stage | Latency (p99, ms), 5XXError |
| CloudFront | AWS::CloudFront::Distribution | 5xxErrorRate, CacheHitRate (observed only) |
| Built with a workload | AWS::ECS::Cluster, AWS::ECS::TaskDefinition, AWS::IAM::Role, AWS::EC2::SecurityGroup, AWS::ElasticLoadBalancingV2::Listener, AWS::CertificateManager::Certificate, AWS::Scheduler::Schedule | (observed; a certificate's status) |
Tag a load balancer and its target groups come with it, linked to the ECS service or Lambda behind them, so Pilot meets a latency goal at the load balancer by scaling what is behind it. Pilot changes only their settings (timeouts, health checks, stage throttling and cache), never listeners, certificates, targets or routes, and reads CloudFront only for fleets in us-east-1.
Changes that restart or fail over something always go to a person for approval, whatever the level: a database's instance class or Multi-AZ setting, an Aurora cluster's storage type, a cache's node type, an Auto Scaling group's launch template. Pilot never deletes a database or a cache.
An ECS service's task size is not a CloudFormation property of the service: Pilot shows the task-level cpu and memory of the task definition it runs as TaskCpu and TaskMemory (bound them like any property: checkout.TaskMemory: [1024, 4096]). Changing them registers a new revision of the task definition, a copy with only the size changed, and deploys it; if the deployment fails or the load balancer's targets turn unhealthy, the service goes back to the revision it ran before. Deploys of your own are not treated as drift.
Other Cloud Control types are adopted and watched, and changed only when boundaries.manage is all. Any CloudWatch metric works with namespace and dimensions.
What Pilot builds on AWS
Declare workloads in the spec (https://infrapilot.fly/docs/manifest.md) and Pilot builds what is missing, one checked transaction per step, each resource tagged infrapilot:fleet, infrapilot:name and infrapilot:created-by=pilot.
| Kind | Becomes | Sizes and defaults |
|---|---|---|
http-service | An ECS service on Fargate behind an Application Load Balancer: the fleet's ECS cluster, a task definition, a log group, an execution role (and a task role when it has a queue), a load balancer with its target group and listeners, Application Auto Scaling between min_instances and max_instances on 60% CPU, and a certificate when it has domains | cpu and memory_mb rounded up to a Fargate size (0.5 vCPU and 1024 MiB by default); 1 to 4 tasks |
worker | The same without the load balancer; with a queue, scaled on the queue's backlog (100 visible messages) | as above |
database | size: small (the default): one RDS PostgreSQL instance, db.t4g.small, gp3 storage of storage_gb (20). medium, large: Aurora Serverless v2 PostgreSQL, 0.5 to 4 and 1 to 16 ACUs, whose range Pilot tunes afterwards. serverless: true or false (AWS only) overrides that choice: serverless small is 0.5 to 2 ACUs; instances are db.t4g.large for medium and db.m7g.xlarge for large. high_availability: Multi-AZ, or a second Aurora instance | about $26 a month for small; Aurora from about $44 (its minimum) |
cache | An ElastiCache serverless cache, Valkey unless engine: redis, limited to memory_gb of data and 5,000 ECPUs a second | 1 GB |
schedule | An EventBridge Scheduler schedule that starts a Fargate task: its own task definition from image, or the task definition of the workload named by target with command | cron in five fields, converted to EventBridge's form; timezone UTC |
queue, table, bucket, topic | SQS, DynamoDB (on demand), S3 (private, encrypted), SNS |
runtime: lambda on an http-service, a worker or a schedule builds a Lambda function instead (a function URL, an event source mapping): cheaper for a small API that is often idle. An http-service may also name a queue it sends to.
What the blueprints assume about the account. The region's default VPC and its subnets: Pilot never builds a VPC or a NAT gateway. If the account has none, Pilot asks you to create one (aws ec2 create-default-vpc) or to name vpc and subnets in the workload's spec, and builds nothing that needs a network until then. It creates three security groups per fleet: one for load balancers (ports 80 and 443 from anywhere), one for services (from the load balancers only) and one for databases and caches (ports 5432 and 6379 from the services only). Tasks run in the default VPC's public subnets with a public address, because without a NAT gateway that is how a task pulls its image; nothing reaches them but the load balancer.
Databases and caches have no public endpoint, are encrypted at rest, and are never deleted by Pilot (its access cannot delete one). A database keeps seven days of backups and has deletion protection on. Its password is made and held by AWS (ManageMasterUserPassword): it never passes through Infrapilot, and Pilot's role cannot read it. The review shows where the database answers and the ARN of that secret.
Secrets are references. Under secrets: give each one as the ARN of a Secrets Manager secret (append :json-key:: for one key of a JSON secret) or of an SSM parameter; ECS injects it into the container when a task starts. A workload can read a secret only if you tagged it for the fleet, and a queue it did not build likewise:
aws secretsmanager tag-resource --secret-id shop/database-url --tags Key=infrapilot:fleet,Value=shopEvery workload of the fleet could read a secret so tagged; each receives only those its spec declares. Values under env: are written into the task definition in plain text (and hidden in Infrapilot's graph): nothing secret belongs there. A secret encrypted with your own KMS key also needs kms:Decrypt for the workload's -exec role, which is yours to grant.
Domains. With domains:, Pilot requests a certificate from AWS Certificate Manager and the review shows the DNS records to add: first the validation record, and, once AWS has issued the certificate and Pilot has created the HTTPS listener, the name to point each domain at. A certificate waiting for its record is shown as pending, not as a failure. Without domains the service answers over HTTP on the load balancer's own name: AWS issues no certificate for that name. Port 80 keeps forwarding to the service after HTTPS works; ask if you want it to redirect.
Deploys. infrapilot deploy <workload> <image> on an ECS service registers a revision of its task definition that differs only in the image and rolls it out; if the tasks do not start or the load balancer's targets turn unhealthy, the service goes back to the revision it ran before. A schedule is deployed the same way (also one that shares a target's task definition: deploy to it after the target); its image is proven only at its next run. Pilot's access cannot deregister a task definition, so revisions accumulate (they cost nothing).
Logs. Each service, worker and job writes to the CloudWatch log group /infrapilot/<fleet>/<workload> (30 days); the review links to it.
Building takes a while. Pilot's change budget lets it create about ten resources at once and one more every half minute, and a database takes 5 to 20 minutes to come up: a typical app (about 28 resources) is built over several of Pilot's turns.
Revoking access
Delete the role (aws iam delete-role-policy for each policy, then aws iam delete-role --role-name InfrapilotAgent). Access ends within the hour; everything keeps running as left.