README unclear in regards to DIST_OUTPUT_BUCKET, appending AWS::REGION, and $SOLUTION_NAME

[CameronMcAuley]

Describe the issue

• README instructs to create dist bucket, and env variable $DIST_OUTPUT_BUCKET.
• S3 upload AWSCLI command uploads to $DIST_OUTPUT_BUCKET-$AWS_REGION.
• The name of that variable is unclear. It isn't the name of the dist bucket. It's the name of the dist bucket without the appended region.
• This can cause confusion it appears -- look at all of the GitHub issues raised related to this which are referenced below. If the user doesn't realise that region needs to be appended to the end of the bucket name when creating it, the awscli upload command fails. (Bucket doesn't exist).
• If the user does create the bucket with the region appended, but makes the mistake of making the variable DIST_OUTPUT_BUCKET something like "my_bucket_dist_us-east_1", it will cause issues down the line when the stack tries to find the appropriate S3 bucket for the Helper resource, as it does a !Join on the 'SourceBucket' (generated by build-s3-dist.sh) with AWS region:

S3Bucket: !Join ['-', [!FindInMap ["SourceCode", "General", "SourceBucket"], !Ref 'AWS::Region']]

• So if you are like me, you got confused by the README, and created a bucket with format 'my-bucket-dist-us-east-1', exported this as the $DIST_OUTPUT_BUCKET variable, but then cloudformation did a !Join and looked for 'my-bucket-dist-us-east-1-us-east-1', resulting in failed stack creation.

Changes Needed

• The readme needs to be clearer or variable names reworked. There are multiple people creating GitHub issues in regards to this and I'm pretty sure it is because they have misunderstood this variable/s3 bucket name.

[CameronMcAuley]

In addition, the README also tells the user to upload the template/dist to the following s3 location: s3://$DIST_OUTPUT_BUCKET-$AWS_REGION/aws-waf-security-automations/$VERSION

If the user ran sudo ./build-s3-dist.sh $TEMPLATE_OUTPUT_BUCKET $DIST_OUTPUT_BUCKET $SOLUTION_NAME $VERSION with a custom $SOLUTION_NAME, this is the directory within S3 that CloudFormation will look for. If it doesn't find it, it will fail.

So, these AWSCLI S3 commands need to reference the $SOLUTION_NAME variable created earlier, i.e:

aws s3 cp ./deployment/global-s3-assets s3://$TEMPLATE_OUTPUT_BUCKET/$SOLUTION_NAME/$VERSION --recursive --acl bucket-owner-full-control
aws s3 cp ./deployment/regional-s3-assets s3://$DIST_OUTPUT_BUCKET-$AWS_REGION/$SOLUTION_NAME/$VERSION --recursive --acl bucket-owner-full-control

In general, this README needs to be much more verbose. I've wasted quite a few hours due to things that weren't clear.

[aijunpeng]

Thanks for reporting the issue. We updated the readme in our most recent release to make it more clear. For example we give an explanation of each env variable and documented when to use each variable. However we do understand there are still confusions caused by missing details. We have added your request to our backlog so it will be addressed in future releases. We thank you for your contribution.

[aijunpeng]

The readme instructions have been updated to provide more clarity. close the ticket.