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.
Newer engines deploying older applications are always supported. The constructs deliberately never stamp an upper bound, so upgrading fjall cannot lock you out of redeploying an application synthesised by an earlier version. The check only bites in the unsafe direction: an old engine driving newer infrastructure code.
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 34.x engine deploys every 34.x application and every older application; a 33.x engine cannot deploy a 34.x application. Fjall never refuses a newer engine. When your application moves to @fjall/components-infrastructure 34.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, 32.x to 33 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.

​
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