AWS controltower: Document AFT plan-only runs with plan_only parameter

Service: controltower · 2026-10-06 · Documentation medium

File: controltower/latest/userguide/aft-account-customization-options.md

Summary

Adds documentation and a Step Functions input example for running AFT customizations in plan-only mode (terraform plan instead of apply), plus a note that plan JSON is exported to an encrypted S3 bucket.

Security assessment

Documents a preview-before-apply workflow that reduces risk of unintended changes and references an encrypted plan-output bucket, which is a security-relevant best practice, but no specific vulnerability or CVE is addressed.

Evidence

+To preview the changes that AFT would make to an account without applying them, use a plan-only run. To start one, include a `plan_only` parameter set to `true` in the Step Functions input.

Diff

diff --git a/controltower/latest/userguide/aft-account-customization-options.md b/controltower/latest/userguide/aft-account-customization-options.md
index d50d14e..17f87cc 100644
--- a//controltower/latest/userguide/aft-account-customization-options.md
+++ b//controltower/latest/userguide/aft-account-customization-options.md
@@ -168,0 +169,28 @@ If your version of AWS Control Tower Account Factory for Terraform (AFT) is 1.6.
+To preview the changes that AFT would make to an account without applying them, use a plan-only run. To start one, include a `plan_only` parameter set to `true` in the Step Functions input. When you set `"plan_only": true`, AFT runs `terraform plan` for your global and account customizations instead of `terraform apply`. You can then review the changes that an account would receive before you apply them. Plan-only runs work across all supported Terraform distributions, including Community Edition, HCP Terraform (Terraform Cloud), and Terraform Enterprise.
+
+The following example shows a Step Functions input that performs a plan-only run for a specific account by setting `plan_only` to `true` and specifying the account ID in the `include` block.
+    
+    
+    {
+      "include": [
+        {
+          "type": "accounts",
+          "target_value": ["123456789012"]
+        }
+      ],
+      "plan_only": true
+    }
+
+In the preceding example, replace the following value with your own information:
+
+  * `123456789012` – Replace this value with the AWS account ID that you want to target for the plan-only run.
+
+
+
+
+After you review the plan output, re-run the customizations pipeline without the `plan_only` parameter (a normal run) to apply the changes to your accounts.
+
+###### Note
+
+On the Community Edition (open source) distribution, AFT exports each plan's JSON output to the encrypted plan-output Amazon S3 bucket in the AFT management account. This export happens on every plan-only run. On the HCP Terraform (Terraform Cloud) and Terraform Enterprise distributions, you can view the plan results in the HCP Terraform run UI. You can also optionally export each plan's JSON output to the bucket. For more information, see [Export Terraform plan output to Amazon S3](./aft-feature-options.html#plan-output-export-option).
+