From f52adf67c8137b981e79af257faf6aa5221d98f5 Mon Sep 17 00:00:00 2001
From: Otavio Macedo <otaviomacedo@protonmail.com>
Date: Tue, 8 Jun 2021 15:55:09 +0100
Subject: [PATCH] chore(pipelines): added troubleshooting sub-section for the
 "S3 error: Access Denied" case (#14986)

Related to #14944

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
---
 packages/@aws-cdk/pipelines/README.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/packages/@aws-cdk/pipelines/README.md b/packages/@aws-cdk/pipelines/README.md
index a99dba1630f3c..d59446e8b8b7e 100644
--- a/packages/@aws-cdk/pipelines/README.md
+++ b/packages/@aws-cdk/pipelines/README.md
@@ -815,6 +815,26 @@ After turning on `privilegedMode: true`, you will need to do a one-time manual c
 pipeline to get it going again (as with a broken 'synth' the pipeline will not be able to self 
 update to the right state). 
 
+### S3 error: Access Denied
+
+Some constructs, such as EKS clusters, generate nested stacks. When CloudFormation tries 
+to deploy those stacks, it may fail with this error:
+
+```console
+S3 error: Access Denied For more information check http://docs.aws.amazon.com/AmazonS3/latest/API/ErrorResponses.html
+```
+
+This happens because the pipeline is not self-mutating and, as a consequence, the `FileAssetX` 
+build projects get out-of-sync with the generated templates. To fix this, make sure the 
+`selfMutating` property is set to `true`:
+
+```typescript
+const pipeline = new CdkPipeline(this, 'MyPipeline', {
+  selfMutating: true,
+  ...
+});
+```
+
 ## Current Limitations
 
 Limitations that we are aware of and will address: