loomplane.yaml

This is the complete field reference. For how to think about a manifest, read The manifest first. The JSON schema at pkg/manifest/schema.json ($id https://loomplane.dev/schemas/loomplane.json) is the machine-readable version, and it's also the MCP resource loomplane://schema/loomplane.yaml. Loomplane rejects unknown fields and unsupported versions. A manifest can be up to 256 KiB.

Top levelCopy Anchor Link

Names (of services, resources, gateways, links and environments in overrides) match ^[a-z][a-z0-9-]{0,39}$: lower case letters, digits and hyphens, starting with a letter, 40 characters at most.

defaultsCopy Anchor Link

servicesCopy Anchor Link

provider, cloud_target and cloud_tags can't be mixed at the same level. An effective direct provider or target also conflicts with Cloud placement, including one inherited from defaults.

buildCopy Anchor Link

Loomplane passes the Dockerfile to the build by its path from the context, so it can sit anywhere. A service without a Dockerfile is built from its source, and build on it is ignored with a warning.

endpointCopy Anchor Link

Settings for a service on your own server or cluster.

need_optionsCopy Anchor Link

Options a service hands to something it needs, by need name and then option name:

services:
  api:
    source: services/api
    needs: [fabriq]
    need_options:
      fabriq:
        tenant: acme

The need has to be in needs. Option names are lower case letters, digits and underscores, start with a letter and run to 32 characters. A value is up to 200 characters with no newline or other control character. Which options a kind accepts is checked when you plan.

The dashboard and POST /projects/:id/manifest/edits can change these in place without touching your comments. link adds a need to a service (with options if you give them, replacing old ones as a whole; with none, they stay). unlink removes the need and its options, and fails if the service doesn't need it. set_use sets one dependency on a catalog resource and leaves the rest of its uses alone. Send one of the three per edit.

resourcesCopy Anchor Link

usesCopy Anchor Link

A catalog resource can depend on other things, such as a Postgres for its data or a Redis for its cache. By default Loomplane provisions a new one of each and wires it in. uses chooses something else, one dependency at a time, keyed by the dependency's name as the catalog lists it.

Set resource or external, not both. Set nothing and you get a new one.

resources:
  db:
    kind: postgres
  gateway:
    kind: sample
    target: conn_your_server
    uses:
      postgres:
        resource: db
      redis:
        external: endpoint_01jbz7q5mx8vh3k2r9t4w6y0ae
      falkordb:
        enabled: true

sample stands in for a catalog kind with those three dependencies, and conn_your_server for one of your checked connections. The manifest checks what it can see on its own: that db is in it and isn't gateway itself, and that the endpoint ID has the right form. The rest waits until you plan, when Loomplane finds out whether the kind has a dependency called postgres, whether db is a kind it accepts, and whether the endpoint answers from the target.

gatewaysCopy Anchor Link

A route is {path, to, strip_prefix}. path is a prefix such as /api that matches /api and anything under /api/. to is the service name. strip_prefix removes the prefix first, so /api/users arrives as /users. The longest matching path wins.

linksCopy Anchor Link

A link needs more than a connection check asks for. The Google Cloud key needs Compute Network Admin (roles/compute.networkAdmin). The AWS key needs ec2:CreateVpnGateway, ec2:AttachVpnGateway, ec2:DetachVpnGateway, ec2:DeleteVpnGateway, ec2:DescribeVpnGateways, ec2:CreateCustomerGateway, ec2:DeleteCustomerGateway, ec2:CreateVpnConnection, ec2:DeleteVpnConnection, ec2:DescribeVpnConnections, ec2:DescribeRouteTables, ec2:EnableVgwRoutePropagation and ec2:CreateTags. See Gateways and networking for what a link builds and bills.

ignoreCopy Anchor Link

ignore.resources lists resource kinds analysis found that the application doesn't use, so plans stop asking about them.

heldCopy Anchor Link

held.same_address decides what a scoped plan does when a held service uses a service that was deleted outside Loomplane and that the plan creates again. The held service isn't redeployed, so it keeps the old address.

With block (the default) that's a problem until you add the held repository to the scope. With warn it's a warning, but only when the planner can tell the address won't change: a Cloud Run service created again with the name, region and connection it had, which gets the same URL. Anything else, including a replacement, is still a problem.

held:
  same_address: warn

Variables Loomplane addsCopy Anchor Link

Provider namesCopy Anchor Link

vercel, cloud-run, cloud-sql, memorystore, cloud-storage, ecs-fargate, rds, elasticache, s3, cross-cloud-vpn, render, digitalocean, azure-container-apps, azure-database, azure-managed-redis, server, kubernetes, plus any provider plugin. The Clouds overview says what each runs and provisions.

Federation (version 2)Copy Anchor Link

To convert a file, review its destinations and public exposure, change version explicitly, add the federation section and review the resulting blocked plan. Keep the original for rollback. The editor never upgrades it for you.

Each map allows 100 entries. A grant allows 16 HTTP methods, 32 paths of up to 1024 bytes, or 32 gRPC methods of up to 256 bytes (gRPC selectors look like /package.Service/Method). expires_at is RFC 3339, and an expired grant is rejected at execution even if the manifest still parses. Exports need public: false and an explicit service port that matches. Every export and source grant needs a matching placement. needs still controls configuration and startup order and grants no access.

Connections supply credentials through Vault, so manifests contain no tokens, kubeconfigs or certificate keys. Management is off by default and turned on with federation.enabled. See Configuration.