InfrapilotAlpha

Reference

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.

FieldMeaning
namelogical name; usable in objectives before it exists
kindwhat to build (below). A kind the cloud does not have is refused (workload_kinds in GET /api/types/<provider>)
descriptionplain words Pilot sizes from: purpose, expected load
specthe details for that kind

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

kindspecBecomes
http-serviceimage (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
workeras 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
databaseengine: 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
cacheengine: redis \| valkey (valkey on AWS only), memory_gb (1)a private Redis-compatible cache: ElastiCache Serverless, Memorystore, Azure Managed Redis
schedulecron (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 commanda job on a schedule: EventBridge Scheduler and an ECS task, Cloud Scheduler and a Cloud Run job, a Container Apps job
queue, bucketoptional detailsa queue; a private, encrypted bucket
table, topicAWS onlya 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.

FieldMeaning
resourcelogical name
metrica metric or live signal for that type (GET /api/types/<provider>), or any provider metric
belowthe threshold
statoptional: p99, p95, Average, Sum, Maximum... (default depends on the metric)
namespace, dimensionsonly for metrics Pilot doesn't already know
act_atfraction of below where Pilot starts acting (default 0.7)
calm_atfraction 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.

LevelPilot may
observeread, review, explain, estimate cost, find risks. It changes nothing.
proposeprepare 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

FieldValuesMeaning
manageprofiled (default) or allprofiled: change only types Pilot has a profile for; observe the rest. all: any type, still schema-checked.
create_typestype names (* allowed), or omitWhat Pilot may create beyond declared workloads. Omitted: profiled types. []: nothing.
protectedlogical 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.

    Type to search every page.