docs: document new CloudFormation engine and its implications (#188)

Co-authored-by: Simon Walker <[email protected]>
Co-authored-by: Brian Rinaldi <[email protected]>

Author: 3 people

src/content/docs/aws/services/cloudformation.mdx

@@ -11,6 +11,40 @@ import { Tabs, TabItem } from '@astrojs/starlight/components';
 
 ## Introduction
 
+:::note
+With LocalStack version 4.8.0 (and above) we've introduced a **new CloudFormation engine** with Change Sets at its core, which would allow proper update and rollback support in the near future.
+
+This includes internal changes that may affect existing stacks or deployment behavior. Most users will benefit from the new behavior automatically, but there are a few important notes to be aware of:
+
+- **Persistence is not backwards-compatible:** If you use persistent state, your stacks may not load correctly between the new and old engines.
+- **Default behavior has changed:** If your deployment logic depends on specific legacy quirks or unsupported update behavior, you may encounter issues.
+- **New features and improvements:** are now available under the new engine.
+
+If you encounter problems or regressions you can **revert to the legacy engine** by setting:
+
+```bash
+PROVIDER_OVERRIDE_CLOUDFORMATION=engine-legacy
+```
+:::
+
+:::note
+
+## Upcoming Change in Handling Unsupported Resource Types
+
+In a future LocalStack release, the behavior of the CloudFormation engine will change when stacks contain **unsupported AWS resource types**.
+
+**Currently**, unsupported resources are silently ignored or mocked so that the rest of the stack can proceed.
+
+**With the upcoming change**, CloudFormation will instead **fail the deployment** if the template includes unsupported resource types.
+
+To keep the current behavior and prepare for this breaking change ahead, you can enable it manually: 
+
+```bash
+CFN_IGNORE_UNSUPPORTED_RESOURCE_TYPES=1
+```
+
+:::
+
 CloudFormation is a service provided by Amazon Web Services (AWS) that allows you to define and provision infrastructure as code.
 It enables you to create, update, and manage resources in a repeatable and automated manner using declarative templates.
 With CloudFormation, you can use JSON or YAML templates to define your desired infrastructure state.