# Connect AWS

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

```bash
aws sts get-caller-identity          # which account the CLI uses
aws configure get region             # the project's region
```

Confirm the account and region with the person. You need `iam:CreateRole`, `iam:PutRolePolicy`, and permission to tag resources.

## 1. Get the role documents

```bash
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.json
```

- **`trust_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 a `Describe`, `Get` or `List`, it cannot invoke a function, and it reads bucket settings, not objects. Attach it **instead of** `tune` and submit the connection with `"access": "observe"` (step 3). AWS's managed `ReadOnlyAccess` also 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' `Resource` if that is too wide for you. It includes `iam:PassRole` to Lambda only, because changing a Lambda through Cloud Control re-submits its execution role. To narrow it, set that statement's `Resource` to 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, so `tune` includes `iam:PassRole` to 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 named `infrapilot-*`: 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 same `infrapilot:fleet` tag as the role. `InfrapilotWorkloadSecrets` reads secrets and parameters, `InfrapilotWorkloadQueues` uses SQS queues, `InfrapilotWorkloadSchedules` starts 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

```bash
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 text
```

When 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):

```bash
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
done
```

For level observe, attach only the read-only policy:

```bash
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.json
```

If `InfrapilotAgent` already exists for another workspace, pick another name (for example `InfrapilotAgent-staging`).

## 3. Submit the connection

```bash
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

```bash
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:fleet` must equal `fleet` in the spec; `infrapilot:name` is 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/discover` shows 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:

1. 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**.
2. 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.
3. If Cost Explorer has never been opened in the account, open it once: AWS enables it on first use.

```bash
aws ce update-cost-allocation-tags-status --cost-allocation-tags-status TagKey=infrapilot:fleet,Status=Active
```

Figures 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:

```bash
aws secretsmanager tag-resource --secret-id shop/database-url --tags Key=infrapilot:fleet,Value=shop
```

Every 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.
