Fjall Docs — deploy AWS infrastructure into your own account

The destruction gate

Every application deploy computes a resource-level change plan before it mutates anything. If that plan would destroy, rename or replace a stateful resource, the deploy stops at an unconditional gate and nothing is applied. There is no blanket override:

No blanket flag exists. --auto-approve, --skip-confirmation, --force and approval tokens never satisfy this gate.

Consent is per resource and by exact name. You tell Fjall what to do with each affected resource, and the deploy proceeds only when every one is covered. Stateless changes never stop here. A plain replacement of a stateless resource, or a delete that loses no data, flows through the normal plan and confirmation surfaces.

Findings

A finding classifies why a resource stopped the deploy. Each finding has its own verb vocabulary.

Finding	Meaning	Verbs offered
`replacement-required`	A property change forces CloudFormation to replace the resource, and the replacement loses data	`abort`, `pin`, `recreate`
`pinned-name-replacement`	A replacement of a resource with a custom physical name. CloudFormation refuses in-stack replacement of custom-named resources	`abort`, `pin`, `recreate`
`data-loss-delete`	The resource was removed from your config, and deleting it destroys data	`abort`, `recreate`
`rename-detected`	A delete plus a create that are really one resource whose logical identity changed	`abort`, `pin`
`rename-ambiguous`	The same shape, but no evidence proved which delete pairs with which create	`abort`, `recreate`

Two further findings exist in the shared vocabulary but are never minted by a deploy:

Finding	Where it comes from	Verbs offered
`resource-deleted`	`fjall drift repair`. A resource deleted outside CloudFormation	`abort`, `forget`
`stack-deleted`	Reserved. No remediation arm ships in this release, so only a decline is offered	`abort`

The verbs offered column is what menus, tickets and re-run hints actually advertise: the finding’s legal vocabulary filtered to what this release can execute, plus abort. A consent you are offered is a consent that runs.

Resources deleted outside CloudFormation are a different problem with a different tool. The deploy pre-flight blocks with a confirmed finding and points you at fjall drift.

The ticket

When the gate stops a deploy, it prints a ticket naming every affected resource: the finding, the resource type, its stack and logical id, the exact physical name you must consent with, the property change that caused it, and the verbs you may choose.

! replacement-required  AWS::RDS::DBInstance  ApiDatabase/Database (data loss)
    physical name: api-production-db
    cause: StorageEncrypted forces replacement
    legal verbs: abort | recreate
ticket digest: 5f3c…

Every text surface renders these same lines: a withheld fjall deploy, a --plan run, fjall drift repair, the fjall domain commands and fjall org deploy. The text block always closes with ticket digest:, the value --destruction-consent-digest takes. In --agent output the same value arrives as the block’s ticketDigest field. The Ink deploy screen and the web app hold the digest for you and never ask you to pass it, because both consent flows bind the consents themselves. An empty ticket renders nothing at all, digest included.

The verbs

Verb	Meaning
`abort`	Stop here. Nothing is changed
`pin`	Record the live value or deployed identity in your fjall config so the change disappears. Non-destructive
`recreate`	Accept a new physical resource under this name. Data survives only via snapshot or backup (none if the resource is already deleted and no backup exists)
`forget`	Stop managing the resource. The physical resource is never touched
`repair`	Report-only: forensics plus a manual runbook, nothing is mutated
`refactor`	Move the resource to its new logical ID via CloudFormation stack refactoring. The physical resource is never replaced

The --remediate help text lists the whole verb vocabulary. Only the verbs printed on your ticket row are accepted for that row. Anything else fails the gate closed with a verdict table.

Offered when the change is safe to accept in place instead of replacing the resource. pin has two arms. Property pin. Probes the live value of the offending property from AWS and writes it back into your application’s infrastructure.ts, so the diff disappears. In this release the live-value probe covers RDS instance and cluster port changes. pin is offered only where the live value can be captured. Identity pin. On a rename-detected row, freezes the deployed capacity identity into capacityIdentity in fjall-config.json so re-synths reproduce the deployed logical ids byte for byte. Either way the deploy then stops (exit code 4) for you to review and commit the config change:

Pin remediation stopped the deploy for api — nothing was applied.
  Updated fjall/api/infrastructure.ts with the live value(s). Review and commit the change, then re-run: fjall deploy api

Re-run the deploy without re-supplying the consent. The config edit already satisfied it. Where the automatic edit cannot land, the CLI prints the exact config line to apply by hand instead. Consents you gave for other resources on the same ticket do not run on a pin stop. They re-consent against the recomputed plan on the next deploy, and the CLI says how many were deferred.

recreate

Consents to a new physical resource under the same name.

On a plain replacement or a consented delete, CloudFormation performs its native action. Nothing extra is orchestrated.
On a custom-named resource, CloudFormation refuses to replace in place, so Fjall runs a surgical removal and the same deploy re-creates the resource under its pinned name. For types that support DeletionPolicy: Snapshot, the removal takes a final snapshot first: DocumentDB clusters, EBS volumes, ElastiCache cache clusters and replication groups, Neptune clusters, RDS clusters and instances, and Redshift clusters. For every other type the data loss is exactly what you consented to.

forget

Stops CloudFormation tracking a resource that no longer exists, without touching anything physical. On a deploy ticket this verb applies to out-of-band deletions, which are remediated through fjall drift repair rather than the deploy itself.

abort and repair

abort declines. The deploy is withheld and nothing is applied. repair is the report-only arm for findings that cannot be safely remediated automatically, so it never appears on a deploy ticket.

Renames

Fjall pairs a delete and a create that are really one resource whose logical identity changed. Deploying such a plan unremediated orphans or deletes the live resource and boots the application against a fresh empty twin. Rename verdicts outrank every other classification, including a resource carrying a Retain policy, because CloudFormation would orphan a retained volume invisibly. rename-detected means the pairing was proved, by the synthesised manifest’s own identity aliases, by the live physical id appearing in the new resource’s properties, by a property digest match, or by being the only candidate pairing in the stack. Consent with pin to weld the deployed identity onto the new slot. pin is offered only when the ticket row carries a slot hint. Without one, only abort is offered, and the cure is to hand-author the capacityIdentity entry in fjall-config.json and validate it with fjall migrate identity. You can also pin a rename before the deploy, outside the consent ceremony:

fjall migrate identity --app api

A deliberate delete-slot-A / create-slot-B swap looks structurally identical to a rename. pin freezes the deployed capacity identity (and its data volume) onto the new slot. If you meant to replace the capacity with a fresh slot, choose abort.

rename-ambiguous means candidate pairings contested each other and no evidence disambiguated them. Classification fails closed. There is nothing safe to pin, so the only executable verb is recreate, which accepts exactly the delete and create the plan already shows.

Consenting interactively

Run interactively, the deploy walks you through the ticket one resource at a time. For each resource you pick a verb from a menu, with each verb’s meaning shown inline, and then, for any verb with consequences, you must type the resource’s exact physical name:

Destructive changes require named consent

Destructive change 1 of 1
  AWS::RDS::DBInstance Database (ApiDatabase)
  physical name: api-production-db
  finding: replacement-required — StorageEncrypted forces replacement
  offending properties: StorageEncrypted
  ⚠ data on this resource may be lost

How should api-production-db be handled?

    abort     stop here — nothing is changed
>   recreate  accept a new physical resource under this name — data survives only via snapshot or backup (none if the resource is already deleted and no backup exists)

Type the exact physical name to consent to recreate (attempt 1 of 3):

The comparison is exact and case-sensitive. Three mismatches decline the ceremony, as does pressing Esc. The deploy is withheld and nothing is applied. The typed name is re-checked by the deploy engine itself, so the screen can never widen what you consented to.

The ceremony runs only when no consent flags were passed. Once any --remediate, --allow-replace or --destruction-consent-digest is supplied, an unsatisfied ticket exits 4 with the verdict table instead of falling back to a prompt. A flag consent that fails keeps failing loudly.

Consenting with flags

Non-interactive runs (and CI) cannot hold a ceremony. The deploy exits with code 4 and prints the ticket plus the consent shape:

Deployment withheld — destructive changes require named consent; nothing was applied (target: api).
Consent to each destructive change by exact physical name, then re-run:
  fjall deploy api --remediate api-production-db=<abort|recreate>
  (--allow-replace <physicalName> is shorthand for <physicalName>=recreate)

Flag	Description
`--remediate <name=verb>`	Named consent for a pending destructive change (repeatable, exact, case-sensitive physical name)
`--allow-replace <name>`	Shorthand consent: allow the named resource to be replaced (repeatable, equivalent to `--remediate <name>=recreate`)
`--destruction-consent-digest <digest>`	Bind consents to the ticket digest printed under the ticket, either by a `--plan` run or by the withheld run that asked for consent. If the pending destructive changes have changed since, the deploy withholds instead of silently carrying the consents over

All three flags work on fjall ci run deploy and on fjall org deploy. fjall drift repair takes --remediate and --destruction-consent-digest but not --allow-replace, whose verb belongs to the deploy.

Consents fail closed

Every supplied consent gets a verdict. A misspelt or surplus name, or a verb that is not legal for the finding, fails the gate closed with a per-name verdict table rather than being ignored:

consent verdicts:
  api-prodction-db=recreate  unmatched — no pending destructive resource has this exact name
awaiting consent:
  api-production-db

A consent to a verb the release cannot yet execute withholds truthfully. The output says the consent was given, names what is executable today, and does not ask you to consent again. fjall deploy <app> --plan prints the pending destructive changes alongside the change plan. The ticket rows and the closing ticket digest: line go to stdout, because the plan is the run’s result:

stdout

ticket digest: 5f3c…

The instruction naming the consent flags is conversation, so it goes to stderr:

stderr

Applying will withhold these until consented: mint consents with --remediate <physicalName>=<verb> --destruction-consent-digest 5f3c… (a changed plan then withholds instead of silently carrying consents over).

Applying later with --destruction-consent-digest guarantees the consent covers exactly the changes that were reviewed. If the plan changed in between, the deploy withholds and asks for a fresh review.

Other ticket surfaces

Four more commands mint tickets through the same engine.

Command	Ticket rows
`fjall domain deploy`	Record takeover on an adopted live zone. Each colliding record as `<name>/<TYPE>`, or `<name>/<TYPE>@<setIdentifier>` when the live record set carries a SetIdentifier (weighted, latency and failover variants are classified and consented per variant)
`fjall domain sync --fix`	Residue records (provably orphaned) as `<name>/<TYPE>`, with `@<setIdentifier>` appended for variant record sets
`fjall domain destroy`	The apex zone as `<zoneName>`, or a delegated child’s parent NS record as `<childZone>/NS`
`fjall org deploy`	Record takeover raised by the cascade’s domains phase, spelled exactly as on `fjall domain deploy`

The same rules apply on all four: named per-row consent, digest binding, fail-closed verdicts, and exit 4 on withheld. Three differences from an application deploy:

The verbs are recreate, forget (delegated-child NS only, when the parent cannot delete it), and abort. There is no pin.
--allow-replace is not available on the three fjall domain surfaces and is rejected rather than silently dropped. fjall org deploy carries the full consent family, including --allow-replace.
Records classified unknown by the zone classifier are never offered on a ticket. Classification fails closed, and only provable residue is remediable.

fjall org deploy has no --plan surface, so its digest comes from a prior withheld run rather than from a plan. The withheld run prints it: the human ticket closes with a ticket digest: line, and --agent carries the same value as the block’s ticketDigest field. The human hint asks for --remediate on every row and treats the digest as optional:

Consent with --remediate '<name>/<TYPE>[@<setIdentifier>]'=recreate for EVERY row on
the ticket (e.g. --remediate 'www.example.com/A'=recreate) (exact, case-sensitive).

Exit codes

The deploy exit-code contract:

Code	Meaning
`0`	Applied, or nothing to change
`1`	A real error
`2`	Stopped without a failure: plan pending approval, plan rejected at the approval gate, or the run was cancelled remotely
`4`	The destruction ceremony stopped the deploy: consent withheld, declined, invalid, not yet executable, or a consented `pin` stopped for its config write-back. Nothing was applied
`64`	A prerequisite is missing (Docker buildx)
`129`, `130`, `143`	The process was signalled (SIGHUP, SIGINT, SIGTERM). The run was interrupted, not a verdict on the plan

Exit code 4 in CI

Exit 4 is not a failure. It means a human decision is required and nothing was applied. A pipeline that hits it should:

Surface the printed ticket to a human, in the job log, a PR comment, or a chat notification.
Stop. Let the failed-by-default step be the stop, and do not retry.
After a human has reviewed, re-run the deploy with the named consents, ideally minted from a --plan run and bound with --destruction-consent-digest.

Never auto-inject --remediate or --allow-replace in a pipeline. Baking a consent flag into CI defeats the gate: the next unrelated change that replaces a resource of the same name is silently consented. Consents belong to a human review of a specific ticket.

Deploys started from the Fjall web app pass through the same gate and present a consent dialog there. A withheld run that was approval-gated re-mints its approval token, still bound to the same plan digest but with a 25-hour window, so a consent decision can take as long as the review needs. The web app abandons an unanswered destructive-pending deploy after 24 hours.

Next Steps

fjall drift

Detect and repair resources deleted outside CloudFormation.

fjall deploy

Every deploy flag, target, and option.

CI/CD Integration

Wire deploys, plans, and consent handling into your pipeline.

fjall destroy

Explicit teardown of a whole application or organisation.

Install & Setup

Web App

Application Deploy

Deployment Errors

Organisation Setup

Organisation Deploy

Destructive Changes

The destruction gate

Findings

The ticket

The verbs

pin

recreate

forget

abort and repair

Renames

Consenting interactively

Consenting with flags

Consents fail closed

Other ticket surfaces

Exit codes

Exit code 4 in CI

Next Steps

fjall drift

fjall deploy

CI/CD Integration

fjall destroy

​The destruction gate

​Findings

​The ticket

​The verbs

​pin

​recreate

​forget

​abort and repair

​Renames

​Consenting interactively

​Consenting with flags

​Consents fail closed

​Plan first, consent bound to the plan

​Other ticket surfaces

​Exit codes

​Exit code 4 in CI

​Next Steps

fjall drift

fjall deploy

CI/CD Integration

fjall destroy

The destruction gate

Findings

The ticket

The verbs

pin

recreate

forget

abort and repair

Renames

Consenting interactively

Consenting with flags

Consents fail closed

Plan first, consent bound to the plan

Other ticket surfaces

Exit codes

Exit code 4 in CI

Next Steps