chore(docs): Add serverless application guide

[ansgarm]

Adds a guide explaining the end to end serverless example.

rendered version
Repo with end to end serverless example: https://github.com/hashicorp/cdktf-integration-serverless-example (also linked in guide)

What do you think having this guide inside the newly created docs/full-guide directory? Happy to move it elsewhere if that seems off.

Resolves #733

[jsteinich]

Looks interesting. Some possible future changes to the example:

• Lock down the S3 bucket so that all requests need to go through CloudFront.
• Use the S3 bucket object resource instead of syncing
• Use IAM Floyd or similar to provide code first iam policies
• Call out that the different environments are different stack

[ansgarm]

Thank you for the great feedback, @jsteinich!

Lock down the S3 bucket so that all requests need to go through CloudFront.

We need to use the web hosting feature of the S3 bucket to serve the index.html for all unknown paths (due to the frontend being a single page application). I could not find a way to restrict the S3 bucket website hosting to only CloudFront and directly serving the files does not work for the application. Is there a way to achieve this that I overlooked?

Use the S3 bucket object resource instead of syncing

I thought about that as well. However it didn't feel right. Currently the frontend has ~10ish files that are deployed to the S3 Bucket, however that number could grow substantially for a bigger application. This would result in the same number of (generated) S3 bucket object resources in Terraform.
One alternative could be to build a custom resource / custom Terraform resource which takes care of the copying. As far as I know the AWS CDK bundles files in a zip and uses a Lambda that extracts the files into an S3 Bucket for a similar use case.

Use IAM Floyd or similar to provide code first iam policies

Great idea. Noted.

Call out that the different environments are different stack

Done.

[jsteinich]

I thought about that as well. However it didn't feel right. Currently the frontend has ~10ish files that are deployed to the S3 Bucket,

Makes sense. For some reason I was thinking it was single file

[jsteinich]

I could not find a way to restrict the S3 bucket website hosting to only CloudFront and directly serving the files does not work for the application. Is there a way to achieve this that I overlooked?

Here's some code that we have:

private VariableConditionResource<CloudfrontOriginAccessIdentity> ApplyBucketPolicy(S3Bucket bucket)
        {
            {//public
                var publicBucketPolicy = new PolicyDocument
                {
                    Statements = {new S3().ToGetObject().OnObject(Config.WebSiteDomain, "*").ForPublic()}
                };

                new VariableConditionResource<S3BucketPolicy>(!Config.UseCloudFront,
                    new S3BucketPolicy(this, "public_s3_policy", new S3BucketPolicyConfig
                    {
                        Bucket = bucket.Id,
                        Policy = publicBucketPolicy.ToJson()
                    }), true);
            }

            {//cloudfront
                new VariableConditionResource<S3BucketPublicAccessBlock>(Config.UseCloudFront,
                    new S3BucketPublicAccessBlock(this, "access_block", new S3BucketPublicAccessBlockConfig
                    {
                        Bucket = bucket.Id,
                        IgnorePublicAcls = true
                    }));

                var accessIdentity = new VariableConditionResource<CloudfrontOriginAccessIdentity>(Config.UseCloudFront,
                    new CloudfrontOriginAccessIdentity(this, "cf_access_identity", new CloudfrontOriginAccessIdentityConfig
                    {
                        Comment = "Access S3 bucket content only through CloudFront"
                    }));

                var cfBucketPolicy = new PolicyDocument
                {
                    Statements =
                    {
                        new S3().ToGetObject().OnObject(Config.WebSiteDomain, "*")
                            .For(accessIdentity.StringValue(nameof(accessIdentity.Resource.IamArn)))
                    }
                };
                
                new VariableConditionResource<S3BucketPolicy>(Config.UseCloudFront,
                    new S3BucketPolicy(this, "cf_s3_policy", new S3BucketPolicyConfig
                    {
                        Bucket = bucket.Id,
                        Policy = cfBucketPolicy.ToJson()
                    }));

                return accessIdentity;
            }
        }

//within cloud front distribution
Origin = new ICloudfrontDistributionOrigin[]
                {
                    new CloudfrontDistributionOrigin
                    {
                        DomainName = bucket.BucketDomainName,
                        OriginId = $"s3-origin-{bucket.Id}",
                        OriginPath = "",
                        
                        S3OriginConfig = new ICloudfrontDistributionOriginS3OriginConfig[]
                        {
                            new CloudfrontDistributionOriginS3OriginConfig
                            {
                                OriginAccessIdentity = cfAccessIdentity.StringValue(nameof(cfAccessIdentity.Resource.CloudfrontAccessIdentityPath))
                            }
                        }
                    }
                },

[ansgarm]

Thanks @jsteinich!
Added it to the ideas for future iterations.

[DanielMSchmidt]

Quite a different style from my version, but I like it!

[github-actions]

I'm going to lock this pull request because it has been closed for 30 days. This helps our maintainers find and focus on the active issues. If you've found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.