CLD-485: only create cloud trail if nesessary

[johnnally]

EventBridge receives Route 53 management events from any active trail in the account - it does not require a specific trail. Most AWS accounts already have a default multi-region trail (e.g. management-events) with IncludeGlobalServiceEvents enabled, which is sufficient. The custom trail we were creating was a redundant duplicate costing customers ~$3/month extra (2nd trail + KMS key + S3 storage).

Changes:

• Add CreateCloudTrail parameter (default: false) with AllowedValues true/false
• Add ShouldCreateTrail condition gating TrailKMSKey, TrailS3Bucket, TrailBucketPolicy and Trail behind it
• Use !If in ConfigureCustomResource to pass an empty CloudTrailBucketName when the bucket was not created
• Use !If with AWS::NoValue in ConfigureFunctionRole to omit S3 policy statements when the bucket does not exist
• Guard S3 bucket cleanup in configure/app.py behind a non-empty bucket name check to avoid errors on stack delete when no bucket was created
• Document the new parameter in README.md

Customers who have no existing trail can set CreateCloudTrail=true to retain the previous behaviour.

One Key Point is :

• During upgrades it is risky to auto delete the Cloud Trail bucket. If the bucket is large (maybe a few months old) - it can take > 1 hour to delete. This prolongs the upgrade but if it exceeds the 1 hour mark cloud formation can give up and attempt a rollback, which may even fail if the original cloud trail has aleady beenb deleted.
  So safest option is to not try and uto delete the bucket, but warn the user to manually delete it after.

I have more detailed and test details documented here: https://ns1inc.atlassian.net/browse/CLD-485?focusedCommentId=1655636

[johnnally]

rebased with main branch in above push -f to resolve conflicts to template file after Mounika's PR was merged to main

[johnnally]

next steps:

1. need to be reviewed
2. if review is ok , generate documentation tickets
3. create package
4. publish package and release docs

NB version has increased to v0.4.4 on main recently, so this version will need to be bumped also before merging

[johnnally]

rebased with main in above push -f

[johnnally]

status update in https://nsone.slack.com/archives/D097YJXHP5G/p1785413015439009

[johnnally]

Key Points for IBM docs

1. New parameter: CreateCloudTrail
Available from v0.4.6 onwards. Most customers should set it to false — if your AWS account already has an active CloudTrail trail (e.g. management-events), CloudSync doesn't need to create its own. Setting false saves ~$3/month. Only set true if you have no existing trail or are unsure.

Note: If you set CreateCloudTrail to false, the CloudTrailName parameter is completely ignored — you can leave it as the default or set it to anything. It only has effect when CreateCloudTrail is true.

2. DNS sync is not interrupted
EventBridge listens to any active trail — not a specific one. Removing the CloudSync-managed trail has no effect on DNS sync as long as another trail is active in your account.

3. Changing CreateCloudTrail on an existing stack

Scenario	CreateCloudTrail before	CreateCloudTrail after	What happens automatically
Upgrading from v0.4.5 or earlier (trail was always created) to v0.4.6 or later	n/a — parameter did not exist	false	Trail stopped and deleted, KMS key deleted, S3 bucket retained — manual cleanup required
Already on v0.4.6, disabling the trail	true	false	Trail stopped and deleted, KMS key deleted, S3 bucket retained — manual cleanup required
Already on v0.4.6, re-enabling the trail	false	true	New trail, KMS key and S3 bucket created — DNS sync continues uninterrupted
Upgrading to a future version, no change to parameter	true	true	No trail changes — stack resources updated as normal
Upgrading to a future version, no change to parameter	false	false	No trail changes — stack resources updated as normal

4. S3 log bucket is NOT automatically deleted — manual cleanup required
Whenever a trail is removed (rows 1 and 2 above), the cloudsync-trail-bucket-* bucket is retained. No new logs will be written to it once the trail is stopped, but it will continue to incur minor S3 storage charges until you empty and delete it manually. The bucket name is shown in the stack's RetainedCloudTrailBucket output.

aws s3 rm s3://cloudsync-trail-bucket-<suffix> --recursive
aws s3 rb s3://cloudsync-trail-bucket-<suffix>

5. Expect ~10 minutes of CloudFormation cleanup noise — this is normal
After any upgrade that removes the trail, CloudFormation will attempt to delete the retained bucket 3 times, fail each time, and eventually reach UPDATE_COMPLETE with "Update successful. One or more resources could not be deleted." This is expected. Your stack is fully operational throughout — there is no downtime.

6. Check the Outputs tab after deploying
The CloudTrailStatus output confirms whether your stack is managing a trail and what action to take. The RetainedCloudTrailBucket output shows the name of any bucket left behind for manual cleanup. If something looks wrong after deploying, this is the first place to check.

7. Downgrading from v0.4.6

There is no one-click rollback in AWS CloudFormation.
CloudFormation has no internal version history — it only knows the currently active template.
To "downgrade" you must proactively redeploy the old template yourself.
CloudFormation treats this as a forward update using the old code you supply.

Recommended approach — avoid needing to downgrade at all:
Redeploy v0.4.6 with CreateCloudTrail=true to restore trail-per-stack behaviour.
No old template needed, no stack deletion required.

Full rollback via sam deploy (non-SAR stacks):
Redeploying an older template with the same stack name works cleanly — CloudFormation runs a forward update using the old template. Only fails if a different stack name is used (hardcoded resource name conflicts).

Full rollback for SAR-installed stacks:
The SAR console only offers the latest published
version — it cannot deploy an older version. To roll back a SAR stack you must delete it
entirely and reinstall the previous version from SAR. You must manually empty and delete the
cloudsync-trail-bucket-* bucket first, otherwise the reinstall will fail due to a name conflict.

Auto-rollback risk:

If a v0.4.6 deployment fails after the configure Lambda has already
deleted the trail, CloudFormation will roll back the stack state but the trail deletion is
not reversed. Redeploy with CreateCloudTrail=true to recreate it. Use
sam deploy --no-execute-changeset to review the changeset before executing.