drift Docs
Pages
drift Docs
Start
What is Drift?
The tour, if you are new here.
Use cases
Whether Drift does your thing.
Getting started
Nothing to deployed, in one command.
Architecture
How a slice is put together.
What it costs
The free grant, four unit prices, two rules.
Moving off Azure
Estimate, snapshot and transform a resource group.
Build
Canvas
Static sites, same origin as your API.
Tools
Operate
Auth
Route gates, API keys and your account.
Teams
More than one person on one account.
Security
Boundaries, sandboxing and hardening.
Troubleshooting
Error codes
What went wrong, and what to do about it.
Legal
Acceptable use
What a slice may not be used for.
Data processing
The DPA, and every sub-processor.

Driftfile

A Driftfile declares one slice: what runs on it, and its shape. It names the Atomic Functions and Workers to deploy and the memory each one books, the Backbone databases, collections, buckets and queues and the size of each, the Canvas sites to publish, and through edge, what can reach the slice and what it can reach. Every booking sits beside what it books, and the slice-wide limits sit in one limits block inside slice, so the file is the whole of what the slice is and what it costs.

The file is written in HCL, the configuration language Terraform uses. A YAML Driftfile is refused: every command that reads one answers with

Driftfile is written in YAML, and the Driftfile is HCL now: this CLI reads no YAML Driftfile.
  Rewrite it in HCL. `drift file new` writes a starter, and `drift file explain` lists every block it can hold

You run drift plan to see what applying the file would change and what it would cost, and drift apply from the project root to make the slice exactly what the file says. Applying creates the slice when it does not exist, resizes it to the file's shape when it does, and then deploys what runs on it. What a file leaves out is the smallest shape that runs what it names; see Anatomy.

The file

The file is named Driftfile: capital D, no extension, just like a Makefile or Dockerfile. It lives at the project root, next to your atomic/, backbone/, and canvas/ folders. The CLI looks for ./Driftfile where you run it. There is no second config file and no lockfile; several environments live in this one file as environment blocks, not a forest of per-environment variants.

  • my-project/the project root
    • atomic/your functions
      • submit.go
      • validator.go
    • backbone/seeds and schemas
      • permit-types.jsonlupserted by _id
    • canvas/your sites
      • public/mounted at /
      • reviewer/mounted at /reviewer
    • Driftfilethe manifest, at the root

The shape of the file

Section by section

The smallest Driftfile

The minimum is the slice, how it is paid for, and one Function to run on it. drift file new writes exactly this, with comments that explain each part:

Driftfile
# new: a Drift project.
# `drift file explain` lists every block this file can hold, `drift file lint`
# checks it without deploying, and `drift plan` shows what applying it does and
# what that costs.

# The file does not say how the slice is paid for: a shape inside the free grant
# can be one of your free slices, and `drift plan` says which it is.
slice "new" {}

# The Atomic pillar: every backend the slice runs. A backend is one folder
# of one language's source: "default" is ./atomic itself, and any other name
# is ./atomic/<name>. Each function and worker is declared inside the backend its
# handler lives in; nothing in your source declares one.
atomic {
  backend "default" {
    # A function answers one call with one result. It is labelled with its method
    # and route, or with QUEUE and the queue it drains: "QUEUE orders".
    # Long-running processes are `worker` blocks beside it.
    function "GET /hello" {
      handler = "GetHello"
      # The memory it books: its own pool, and what it is billed at.
      # `drift size` rewrites it from what the slice measured.
      memory = "32MiB"
    }
  }
}

# An environment is a slice of its own, <slice>-<name> unless it names one:
#
#   environment "staging" {}
#
# `drift plan staging` and `drift apply staging` work on it.

The slice is named after DRIFT_SLICE when it is set, or after the folder; --name chooses another, --canvas <dir> adds a site, and --force overwrites an existing Driftfile.

drift plan

drift plan compares the file with the live slice and prints every difference, what it costs, and what it removes. It changes nothing: the only request it makes that is not a read is the platform's price quote, which writes nothing. It takes the name of an environment, drift plan staging, to plan that environment's slice.

Shell
$ drift plan

  slice ada/testnode                                 ~ change

  ~ function POST /rpc          memory 64MiB → 128MiB
  - function GET /bench         deployed code, triggers and history are deleted
    sql chain                unchanged
    worker sequencer          unchanged (digest 9f2c…)

  Price     €5.76 a month → €7.68 a month         (quoted by the platform)
  Restart   yes: the slice restarts once, because its total booked memory changes (192MiB → 256MiB),
            which means a few seconds of errors
  Removes   function GET /bench

  Apply with:  drift apply      (asks for each of the above)
         or:   drift apply --approve-price 768 --approve-remove "function GET /bench"

Each line starts with a mark:

mark means
+added
~changed
-removed
blankunchanged
!cannot be applied as it is, for example secret STRIPE_KEY $STRIPE_KEY is not set here: apply would refuse

A slice that does not exist yet is planned as + create, and its price line reads €x.xx a month (quoted by the platform), or free. With nothing to do, the plan prints Nothing to change. A plan says that only for a slice it read in full: if some fact it compares could not be read, the slice's header reads unchanged (not fully read) instead, and the plan ends on Nothing differs in what could be read. followed by one line for each fact it could not read, naming what it was read for and why, for example site /: sites could not be read (Couldn't list canvas sites: the platform is having trouble. ...). A line carrying a mark still wins: a plan that finds a difference reports it, and lists beside it whatever else it could not read.

A line's address is how a resource is named everywhere, in the plan and in the flags that answer it: function POST /rpc, function QUEUE orders, field sequencer, sql chain, nosql items, blobs uploads, queue txs, secret STRIPE_KEY, site /, site_auth alice, link billing, allow 203.0.113.0/24, host app.example.com, domain app.example.com, egress, limits.timeout, slots, databases, tier and label team. When a store is removed or shrunk, or limits.backup_retention shortens, the plan adds a Data line saying could be lost and naming what.

Some things are compared in their own way:

  • A secret is write-only. One already on the slice is set again from its variable on apply, never compared.
  • An API key is compared by the slice's fingerprint of it, its last four characters. An unchanged key is not rotated; a different one is planned as rotates to the key in $NAME.
  • A booking that shrinks is a removal that apply asks about, and a store that shrinks is a possible data loss.
  • A site the file does not name stays served: the plan prints still served: no drift command removes a site yet.
  • A domain the file does not name stays attached. Apply adds what the file declares and reports the rest.

Plan files, for CI

drift plan --out plan.json also writes the plan down, for drift apply plan.json to apply exactly. See For CI below.

drift plan --exit-code reports the same verdict as an exit status, for a script that cannot read the plan's text: 0 for a match, 2 for create or a difference, 3 when a fact could not be read, 1 when the plan fails. Without the flag, a difference exits 0. Combined with --out, the file is written either way.

drift apply

drift apply prints the same plan, then asks before three things, each on its own:

asked whenanswered without a terminal by
  • The price
    asked when
    the monthly figure moves, or a monthly slice is created
    answered without a terminal by
    --approve-price <cents>, which must be the figure the plan quoted
  • A removal
    asked when
    code, a slot, a booking or a limit goes away
    answered without a terminal by
    --approve-remove "<address>", once per resource
  • A data loss
    asked when
    a database, collection, bucket or queue holding data is removed or shrunk, or backups are kept for less time
    answered without a terminal by
    --allow-data-loss "<address>", once per resource

Agreeing to a removal is not agreeing to lose what it holds; each is asked. At a terminal a price and a removal are y/N questions, and a data loss is agreed to by typing the resource's address. Without a terminal, an unanswered question stops the apply before anything is sent, and the message lists the flags that answer it.

Then, in order:

  1. A pre_deploy hook runs first, so it can build what the file names.
  2. Checks run before any route is called: the files and folders the Driftfile names exist, and every secret, API key and site password has its variable set.
  3. No slice yet: it is created with the file's shape. If the shape fits the free slice, apply asks You have 1 of 3 free slices — make this the 2nd? (--use-free-slice answers it in a script) and creates it from the free preset; if you hold all your free slices it refuses and names them. A shape that does not fit is a priced slice, and --approve-price agrees to the figure drift plan quotes.
  4. The shape changed: the slice is resized. The figure you agreed to goes with the request, so if the price moved between the plan and the apply, the platform refuses and nothing changes; run drift plan again.
  5. What runs on it is deployed: Backbone, then Atomic and Canvas, then edge. A Function or Worker whose source and declaration are unchanged is skipped; --force redeploys every one.
  6. API keys are set, but only where the slice holds none or a different one.
  7. A post_deploy hook runs once the slice is live. A failed one leaves the slice live and exits non-zero.

A file that would move an existing free slice to a priced shape is refused for now; drift slice resize makes that move.

Besides the three answers, drift apply takes --var KEY=value (repeatable) to set a variable env() reads, --secret as the same thing, and --no-env-file to skip the .env files. drift plan takes the same three.

For CI

Plan and apply in two steps. drift apply plan.json applies exactly the plan that was written, with the answers it recorded, and refuses if the Driftfile, the slice, or what the plan asks changed in between:

Shell
drift plan --out plan.json
drift apply plan.json

drift size

drift file benchmark reports what each Function and Worker measured: the peak memory of an invocation, the high-water mark of a slot, and the size it should book. drift size writes those recommendations into the Driftfile's memory lines, keeping comments and layout, and shows the change as a diff. drift size --dry-run shows the diff without writing it. A Function nobody has called yet is left alone, because there is nothing to size it from.

The file is changed and nothing else. Run drift plan to see what the new bookings cost, and apply them like any other edit.