# The fleet spec

`infrapilot.yaml` is the whole configuration: what Pilot runs, what must stay true, and where its authority ends. It replaces infrastructure code. Pilot works out the changes; an engine checks each one against this file.

Only people change the spec. Pilot can ask for a change (`https://infrapilot.fly/docs/requests.md`). YAML or JSON.

## Shape

```yaml
version: 1
fleet: shop                     # required: lowercase letters, digits, dashes; at most 31 characters
provider: aws                   # aws | azure | gcp (defaults to the workspace's)
region: us-east-1               # region or location (defaults to the connection's)
scope: {}                       # azure: {subscription_id, resource_group}; gcp: {project_id, zone, billing_table} (defaults to the connection's)

adopt:                          # what already exists
  - tag: {"infrapilot:fleet": "shop"}
  - resource: {type: "AWS::SQS::Queue", identifier: "https://sqs.us-east-1.amazonaws.com/123456789012/orders", name: orders}

workloads:                      # what should exist; Pilot builds what is missing
  - name: uploads
    kind: bucket
    description: private bucket for customer uploads, about 50 GB
    spec: {}

intents:                        # what must stay true
  - name: orders processed promptly
    description: Orders are processed within about two minutes.
    objectives:
      - {resource: orders, metric: backlog, below: 300}
      - {resource: orders, metric: ApproximateAgeOfOldestMessage, below: 180}
    max_monthly_cost_usd: 60
    level: autonomous           # autonomous (default) | propose | observe
    bounds:
      worker-trigger.ScalingConfig.MaximumConcurrency: [2, 5]
    calm_seconds: 150

boundaries:                     # where Pilot's authority ends
  manage: profiled
  create_types: []
  protected: [orders-db]

infrastructure_code:            # optional: resources Terraform, CloudFormation, CDK or Pulumi manages
  level: propose                # what Pilot may do to them (default propose)
  tags:                         # your own convention, beside the ones Pilot recognises
    - {tag: {managed-by: platform}, tool: terraform}

smoke:                          # optional health-check requests
  worker: {Records: []}

contacts:                       # optional: who Pilot asks
  email: [team@example.com]
```

A spec needs at least one intent or workload.

## adopt

Brings existing resources under management. Reads only; changes nothing.

- `tag`: every resource with all these tags. On Google Cloud use labels with dashes (`infrapilot-fleet`).
- `resource`: one resource by `type` and `identifier`, optional `name`.

Each resource gets a **logical name** used across the spec: its `infrapilot:name` tag (`infrapilot-name` label), or one derived from its own name. `POST /api/v1/setup/discover` shows them. Attached provider autoscalers are adopted automatically as *controllers*.

## workloads

Things that should exist. If nothing implements a workload, Pilot builds it from the provider's blueprint, small and inside the cost ceiling, and then runs it like anything else in the fleet. A workload is implemented by the resource that carries its name, or by resources Pilot built for it.

| Field | Meaning |
| --- | --- |
| `name` | logical name; usable in objectives before it exists |
| `kind` | what to build (below). A kind the cloud does not have is refused (`workload_kinds` in `GET /api/types/<provider>`) |
| `description` | plain words Pilot sizes from: purpose, expected load |
| `spec` | the details for that kind |

The kinds and their `spec` are the same on every cloud; what each becomes is in the provider guide.

| `kind` | `spec` | Becomes |
| --- | --- | --- |
| `http-service` | `image` (required), `command` (the image's own), `port` (8080), `public` (true), `cpu` (0.5 vCPU), `memory_mb` (1024), `min_instances` (1), `max_instances` (4), `env`, `secrets`, `domains`, `health_path` (`/`) | a container behind HTTPS, load balanced and autoscaled: ECS Fargate behind a load balancer, Cloud Run, Container Apps |
| `worker` | as `http-service` without the HTTP fields, plus `queue` (the name of a queue in the fleet) | a container with no inbound traffic, scaled on its queue when it has one |
| `database` | `engine: postgres`, `version`, `size: small \| medium \| large`, `storage_gb` (20), `high_availability` (false) | a private PostgreSQL database with backups, protected from deletion: RDS (small) or Aurora Serverless v2 (medium, large), Cloud SQL, Azure Database for PostgreSQL |
| `cache` | `engine: redis \| valkey` (valkey on AWS only), `memory_gb` (1) | a private Redis-compatible cache: ElastiCache Serverless, Memorystore, Azure Managed Redis |
| `schedule` | `cron` (required, five fields), `timezone` (UTC; Azure runs schedules in UTC only), and `image` with optional `command`, or `target` (an `http-service` or `worker` in the fleet) with `command` | a job on a schedule: EventBridge Scheduler and an ECS task, Cloud Scheduler and a Cloud Run job, a Container Apps job |
| `queue`, `bucket` | optional details | a queue; a private, encrypted bucket |
| `table`, `topic` | AWS only | a DynamoDB table; an SNS topic |

A few optional `spec` keys exist on one cloud only, each described in its provider guide: on AWS `runtime: lambda` (a small API as a Lambda function) and `serverless` on a database; on Google Cloud `service_account` on a container workload; on Azure `identity` on a container workload and `clients` on a database or cache. A spec without them builds everywhere.

```yaml
workloads:
  - name: api
    kind: http-service
    description: the public API, about 20 requests a second at peak
    spec:
      image: ghcr.io/acme/api:1.4.2
      port: 8080
      domains: [api.acme.dev]
      env: {LOG_LEVEL: info}
      secrets: {STRIPE_KEY: "arn:aws:secretsmanager:us-east-1:123456789012:secret:stripe-key"}
  - name: db
    kind: database
    spec: {engine: postgres, size: small}
  - name: cache
    kind: cache
  - name: nightly-report
    kind: schedule
    spec: {cron: "0 3 * * *", target: api, command: ["python", "manage.py", "report"]}
```

**Secrets are references, never values.** `secrets` maps an environment variable to a secret that already exists in your cloud's secret store, in its native form: a Secrets Manager or SSM parameter ARN, `projects/<project>/secrets/<name>`, a Key Vault secret URL. The workload's own identity reads them; how it is given that access differs by cloud and is in the provider guide (on AWS you tag the secret for the fleet; on Google Cloud you grant the workload's service account; on Azure Pilot assigns the Key Vault Secrets User role on that one secret, if you let it). A secret's value never appears in the spec, the ledger or anything Pilot reads; a spec that carries one is refused.

**Pilot does not wire a database into a service.** A database's password is the provider's to make and keep, or yours: Pilot never sets or reads one. After it builds a database or a cache, the review shows its address and where its password is kept; you write the connection string into a secret and reference it here. `https://infrapilot.fly/docs/migrate.md` walks through it.

**`env` is for configuration that is not secret.** Its values are still hidden from Pilot and the ledger once on a resource, because people put secrets there anyway.

**A database and a cache are private.** No public endpoint; only the fleet's services reach them. Pilot never deletes one: removing it from the spec leaves it running, and deleting it is an operation a named person approves.

**`domains`**: Pilot creates the certificate and the mapping, then shows the DNS records to add (in the review and on the workload). The domain serves once the records exist; nothing else waits for it.

**Deploying a new image** is not a spec change: `infrapilot deploy api <image>` (`https://infrapilot.fly/docs/deploy.md`).

A workload lets Pilot create only the types its blueprint lists.

## intents

Something that must stay true, and the limits for keeping it true.

**`objectives`**: a metric that must stay **below** a number.

| Field | Meaning |
| --- | --- |
| `resource` | logical name |
| `metric` | a metric or live signal for that type (`GET /api/types/<provider>`), or any provider metric |
| `below` | the threshold |
| `stat` | optional: `p99`, `p95`, `Average`, `Sum`, `Maximum`... (default depends on the metric) |
| `namespace`, `dimensions` | only for metrics Pilot doesn't already know |
| `act_at` | fraction of `below` where Pilot starts acting (default `0.7`) |
| `calm_at` | fraction under which it counts as comfortably met (default `0.3`) |

Pilot acts before a breach, and gives capacity back after `calm_seconds` (default 120) of comfort.

**`max_monthly_cost_usd`**: the ceiling for the intent's resources (and things tied to them, like an autoscaler, or the compute behind a load balancer). No change of Pilot's may pass it, and under a ceiling Pilot does not create or enlarge a resource Infrapilot has no price for (a person can approve it). For autoscaled resources, it is checked against the autoscaler's maximum.

**`bounds`**: limits on values Pilot sets, as `"resource.Property.Path": [min, max]`, using the provider's property names. Nested fields use dots; pick list items with `[Key=value]`:

```yaml
bounds:
  api.MemorySize: [128, 2048]
  worker-trigger.ScalingConfig.MaximumConcurrency: [2, 5]
  events.GlobalSecondaryIndexes[IndexName=by-user].ProvisionedThroughput.ReadCapacityUnits: [5, 100]
```

Use bounds for limits Pilot can't see: a downstream API's concurrency, a licence, a connection limit.

**`level`**: how much Pilot may do for this intent.

| Level | Pilot may |
| --- | --- |
| `observe` | read, review, explain, estimate cost, find risks. It changes nothing. |
| `propose` | prepare each change; the change waits for one click from a person (dashboard, Slack or email) and runs in that person's name. An approval is refused if the resources changed after Pilot proposed it. |
| `autonomous` (default) | act within the bounds and the cost ceiling, and ask at the limits. |

The engine enforces the level like every other limit: at `observe` a change is refused whoever submits it. A resource under several intents takes the most cautious level. A resource no intent names is held to the most cautious intent of the fleet, so `observe` on your only intent means nothing in the fleet is changed. A cloud account connected with a read-only role (`access: observe`, see the provider guide) caps every intent at `observe`.

Some changes wait for approval at any level, because they restart or fail over the resource (a database's instance class, a cache's node type). `GET /api/types/<provider>` lists them per type.

## Infrastructure code

If Terraform, CloudFormation, CDK or Pulumi manages a resource, it has two owners the moment Pilot changes it: the next `terraform apply` puts the old value back. Pilot finds those resources from their tags and, by default, proposes changes to them instead of making them. The graph and the review show which tool manages each one.

Recognised without configuration: `aws:cloudformation:stack-name` (CloudFormation, CDK, SAM), `goog-terraform-provisioned` (Google's Terraform provider), `pulumi:project` / `pulumi:stack`, `azd-env-name`, and the usual conventions (`managed-by: terraform`, `ManagedBy: Pulumi`, `terraform: true`, `tf-workspace`). A Terraform resource that carries none of these looks like any other: name your own tag under `infrastructure_code.tags` (values may be globs), or add a default tag in your provider block:

```hcl
provider "aws" {
  default_tags { tags = { managed-by = "terraform" } }
}
```

`infrastructure_code.level` is `propose` by default. To let Pilot change these resources itself, tell your tool to leave alone the properties Pilot tunes, then set the level to `autonomous`:

```hcl
resource "aws_ecs_service" "api" {
  # ...
  lifecycle { ignore_changes = [desired_count] }      # Pilot (or its autoscaler) sets the task count
}
resource "aws_appautoscaling_target" "api" {
  lifecycle { ignore_changes = [min_capacity, max_capacity] }
}
resource "google_cloud_run_v2_service" "api" {
  lifecycle { ignore_changes = [template[0].scaling] }
}
resource "azurerm_container_app" "api" {
  lifecycle { ignore_changes = [template[0].min_replicas, template[0].max_replicas] }
}
```

Pulumi: `ignoreChanges: ["desiredCount"]` in the resource options. CloudFormation and CDK have no per-property ignore: keep those at `propose`, and make the approved change in the template too. The properties Pilot tunes per type are in `GET /api/types/<provider>` (`tunable_properties`).

An autoscaler or trigger tied to a managed resource is treated as managed with it.

## Boundaries

| Field | Values | Meaning |
| --- | --- | --- |
| `manage` | `profiled` (default) or `all` | `profiled`: change only types Pilot has a profile for; observe the rest. `all`: any type, still schema-checked. |
| `create_types` | type names (`*` allowed), or omit | What Pilot may create beyond declared workloads. Omitted: profiled types. `[]`: nothing. |
| `protected` | logical names (`*` allowed) | Never changed. |

## Rules that always apply

Enforced on every change; not configurable:

- Valid against the provider's schema; read-only and replace-on-change properties are refused.
- Values a provider autoscaler owns are never written; Pilot tunes the autoscaler.
- At most half of any capacity removed per change.
- Pilot deletes only what it created. Deleting data needs a named person.
- A change budget limits pace and refills only while objectives are met.
- A health check follows each change; failures are undone automatically.

## Changing the spec

Edit and resubmit: `PUT /api/v1/setup/manifest` (setup token) or `PUT /api/workspaces/<id>/manifest` (API token or dashboard). The diff is recorded under your name and Pilot re-plans. A running workspace's fleet name and provider can't change.
