Skip to main content

​
Three versions, one deploy

Every Fjall deploy involves three independently versioned pieces: Your application pins its constructs version. The CLI that runs the deploy is chosen separately, on your machine or in CI. If the engine is older than the constructs that synthesised your infrastructure, the deploy can go wrong silently: services dropped from the build set, images built without the options your runtime needs, or permissions that no longer line up. Fjall closes this gap with an engine-compatibility check.

​
How the check runs

  1. At synth, the constructs stamp an engineCompat block into the cloud assembly (cdk.out/fjall-manifest.json). It carries the minimum deploy-engine version and the minimum bundled AWS CDK CLI version those constructs need.
  2. After the final synth, before any build, push, or CloudFormation call, the engine reads that block and classifies the pairing.
  3. Incompatible pairings refuse loudly. A refusal always happens before anything in AWS is changed.
The chokepoint covers application deploys and organisation-tier deploys and destroys alike, including the organisation cascade.
The compatibility check never refuses a newer engine deploying an older application. The constructs deliberately never stamp an upper bound, so this check cannot lock you out of redeploying an application synthesised by an earlier version. It only bites in the unsafe direction: an old engine driving newer infrastructure code.Two gates sit outside it and can refuse a newer engine: the capacity-identity pin gate and, from fjall 38, the backup-vault ownership gate. Both are covered under Emergency override.
Two cases carry no constraint at all and deploy exactly as before. Assemblies synthesised by constructs older than 4.3.0 predate the stamp entirely. And the stamp is fail-safe: if the constructs cannot resolve their own version, or it has a non-integer major, they stamp no block rather than a garbage one. An unresolvable version degrades to a constraint-free deploy, never to a refusal.

​
Refusal messages and their cures

One more verdict never refuses. An engine newer than an assembly’s declared maximum is warned about and then proceeds. That verdict is dormant by design, not by accident: capping a newer engine would break the ordinary upgrade-then-redeploy path, so the constructs never emit an upper bound and no Fjall-synthesised application can reach this state. It exists for reading a foreign assembly that stamped a maximum by hand.

​
Keep the engine and constructs in step

The rule is a floor, not an equality: the engine major must be at least the constructs major. A 38.x engine deploys every 38.x application and every older application. A 37.x engine cannot deploy a 38.x application. The engine-compatibility check never refuses a newer engine. Two gates outside that check can refuse a newer engine against an older assembly: the capacity-identity pin gate and, from fjall 38, the backup-vault ownership gate. Both are covered under Emergency override. When your application moves to @fjall/components-infrastructure 39.x, upgrade the engine everywhere a deploy runs:
In CI, set the plugin’s cli-version input:
The same steps apply to any earlier major move, 36.x to 37 and so on.

​
Emergency override

If you have verified an engine and constructs pairing yourself and need to push a deploy through anyway, set:
This downgrades the refusal to an audit-logged warning for that run. Treat it as an emergency escape hatch, not a workflow. Deploying across an engine skew can make silently wrong infrastructure changes, which is exactly the failure the check exists to stop. There is no CLI flag for this. The environment variable is the only operator surface, and it works identically in local runs and in both CI plugins. An empty value is not an override: FJALL_ALLOW_ENGINE_SKEW="" from a CI env-file leaves the refusal in place.
The override does not cover the capacity-identity pin gate. If a deploy refuses with carries capacity-identity pins … but this assembly was synthesised by constructs that predate the pin-consuming anchor model, the two remedies are direct: restore the @fjall/components-infrastructure pin to >=7.0.0 and re-synth, or revert the capacity config to its pre-pin values and remove the application’s capacityIdentity entries from fjall-config.json.From fjall 38 it does not cover the backup-vault ownership gate either. An organisation-tier deploy refuses with Backup vault "backupVault" exists outside the account stack and is about to be imported, but this assembly was synthesised by constructs that predate the ownership verdict, or with is owned by the account stack on a key outside it in place of exists outside the account stack and is about to be imported. The message reports the assembly’s declared floor alongside the one it needs: re-owning a vault requires >=38.0.0.The cure is the one the message names: restore the @fjall/components-infrastructure pin to >=38.0.0 and re-synth. The override is withheld because constructs older than 38 read a retired boolean, so a re-owned verdict reaches them as no context at all and they would declare a new vault and a new key under the live name. There is nothing for an operator to verify.

​
Next Steps

CI/CD Integration

Pin or auto-derive the engine version in your pipelines

Install the Fjall CLI

Install or upgrade the fjall CLI

Deploy Application

Run a deploy and read the approval gate

Boot Gates & Deployment Safety

The other gates Fjall puts in front of a bad task