Add extensions documentation

getlift · May 24, 2022 · b51f877 · b51f877
1 parent c658358
commit b51f877
Show file tree

Hide file tree

Showing 8 changed files with 182 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -159,6 +159,24 @@ To eject:
 - copy the parts you want to turn into CloudFormation and paste them in the [`resources` section of serverless.yml](https://www.serverless.com/framework/docs/providers/aws/guide/resources/)
 - don't forget to remove from `serverless.yml` the Lift constructs you have turned into CloudFormation
 
+## Extend Lift constructs
+
+Lift packages production-ready features in the form of highly opinionated construts with minimal configuration options in order to avoid confusion for serverless early adopters. In order to empower more advanced developpers, every construct ships with an `extensions` property allowing overrides on the underlying Cloudformation Resources.
+
+In the exemple below, the S3 Bucket CloudFormation Resource generated by the `avatars` storage construct will be extened with the new `AccessControl: PublicRead` CloudFormation property.
+
+```yaml
+constructs:
+    avatars:
+        type: storage
+        extensions:
+            bucket:
+                Properties:
+                    AccessControl: PublicRead
+```
+
+Each construct documentation lists available underlying CloudFormation resources that can be extended using the `extensions` key.
+
 ## TypeScript definitions
 
 TypeScript users can use `serverless.ts` instead of `serverless.yml`. Lift provides [type definitions to help](docs/serverless-types.md).

diff --git a/docs/database-dynamodb-single-table.md b/docs/database-dynamodb-single-table.md
@@ -115,6 +115,26 @@ constructs:
 
 > :warning: Modifying a table local secondary indexes configuration requires table re-creation. If you modify this setting after the table has been populated with data, you'll need to transfer all data from old table to the new one. You however won't loose any data as all tables are configured to be left as is when removed from a CloudFormation template.
 
+## Extensions
+
+You can specify an `extensions` property on the `database/dynamodb-single-table` construct to extend the underlying CloudFormation resources. In the exemple below, the DynamoDB Table CloudFormation resource generated by the `myTable` dynamodb-single-table construct will be extended with the new `TableClass: STANDARD_INFREQUENT_ACCESS` CloudFormation property.
+
+```yaml
+constructs:
+    myTable:
+        type: database/dynamodb-single-table
+        extensions:
+            table:
+                Properties:
+                    TableClass: STANDARD_INFREQUENT_ACCESS
+```
+
+### Available extensions
+
+| Extension key 	| CloudFormation resource 	| CloudFormation documentation                                                                            	|
+|---------------	|-------------------------	|---------------------------------------------------------------------------------------------------------	|
+| table         	| AWS::DynamoDB::Table    	| [Link](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-dynamodb-table.html) 	|
+
 ### More options
 
-Looking for more options in the construct configuration? [Open a GitHub issue](https://github.com/getlift/lift/issues/new).
+Feel like a common extension pattern should be implemented as part of the construct configuration? [Open a GitHub issue](https://github.com/getlift/lift/issues/new).
diff --git a/docs/queue.md b/docs/queue.md
@@ -398,7 +398,30 @@ It contains the identifier of the messages you consider as failed in the `itemId
 
 You can learn more in the [official AWS documentation](https://docs.aws.amazon.com/lambda/latest/dg/with-sqs.html#services-sqs-batchfailurereporting).
 
+## Extensions
+
+You can specify an `extensions` property on the queue construct to extend the underlying CloudFormation resources. In the exemple below, the SQS Queue CloudFormation resource generated by the `my-queue` queue construct will be extended with the new `MaximumMessageSize: 1024` CloudFormation property.
+
+```yaml
+constructs:
+    my-queue:
+        type: queue
+        worker:
+            handler: src/worker.handler
+        extensions:
+            queue:
+                Properties:
+                    MaximumMessageSize: 1024
+```
+
+### Available extensions
+
+| Extension key 	| CloudFormation resource 	| CloudFormation documentation                                                                              	|
+|---------------	|-------------------------	|-----------------------------------------------------------------------------------------------------------	|
+| queue         	| AWS::SQS::Queue         	| [Link](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sqs-queue.html)        	|
+| dlq           	| AWS::SQS::Queue         	| [Link](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sqs-queue.html)        	|
+| alarm         	| AWS::CloudWatch::Alarm  	| [Link](https://docs.aws.amazon.com/fr_fr/AWSCloudFormation/latest/UserGuide/aws-properties-cw-alarm.html) 	|
 
 ### More options
 
-Looking for more options in the construct configuration? [Open a GitHub issue](https://github.com/getlift/lift/issues/new).
+Feel like a common extension pattern should be implemented as part of the construct configuration? [Open a GitHub issue](https://github.com/getlift/lift/issues/new).
diff --git a/docs/server-side-website.md b/docs/server-side-website.md
@@ -346,6 +346,30 @@ constructs:
 
 CloudFront accepts maximum 10 headers.
 
+## Extensions
+
+You can specify an `extensions` property on the `server-side-website` construct to extend the underlying CloudFormation resources. In the exemple below, the CloudFront Distribution CloudFormation resource generated by the `website` server-side-website construct will be extended with the new `Comment: Landing distribution` CloudFormation property.
+
+```yaml
+constructs:
+    website:
+        type: server-side-website
+        assets:
+            '/css/*': public/css
+            '/js/*': public/js
+        extensions:
+            distribution:
+                Properties:
+                    Comment: Landing distribution
+```
+
+### Available extensions
+
+| Extension key 	| CloudFormation resource       	| CloudFormation documentation                                                                                           	|
+|---------------	|-------------------------------	|------------------------------------------------------------------------------------------------------------------------	|
+| distribution  	| AWS::CloudFront::Distribution 	| [Link](https://docs.aws.amazon.com/fr_fr/AWSCloudFormation/latest/UserGuide/aws-resource-cloudfront-distribution.html) 	|
+
 ### More options
 
-Looking for more options in the construct configuration? [Open a GitHub issue](https://github.com/getlift/lift/issues/new).
+Feel like a common extension pattern should be implemented as part of the construct configuration? [Open a GitHub issue](https://github.com/getlift/lift/issues/new).
+
diff --git a/docs/single-page-app.md b/docs/single-page-app.md
@@ -220,6 +220,28 @@ constructs:
             allowIframe: true
 ```
 
+## Extensions
+
+You can specify an `extensions` property on the `single-page-app` construct to extend the underlying CloudFormation resources. In the exemple below, the CloudFront Distribution CloudFormation resource generated by the `landing` single-page-app construct will be extended with the new `Comment: Landing distribution` CloudFormation property.
+
+```yaml
+constructs:
+    landing:
+        type: single-page-app
+        path: public
+        extensions:
+            distribution:
+                Properties:
+                    Comment: Landing distribution
+```
+
+### Available extensions
+
+| Extension key 	| CloudFormation resource       	| CloudFormation documentation                                                                                           	|
+|---------------	|-------------------------------	|------------------------------------------------------------------------------------------------------------------------	|
+| distribution  	| AWS::CloudFront::Distribution 	| [Link](https://docs.aws.amazon.com/fr_fr/AWSCloudFormation/latest/UserGuide/aws-resource-cloudfront-distribution.html) 	|
+
 ### More options
 
-Looking for more options in the construct configuration? [Open a GitHub issue](https://github.com/getlift/lift/issues/new).
+Feel like a common extension pattern should be implemented as part of the construct configuration? [Open a GitHub issue](https://github.com/getlift/lift/issues/new).
+
diff --git a/docs/static-website.md b/docs/static-website.md
@@ -223,6 +223,28 @@ constructs:
             allowIframe: true
 ```
 
+## Extensions
+
+You can specify an `extensions` property on the `static-website` construct to extend the underlying CloudFormation resources. In the exemple below, the CloudFront Distribution CloudFormation resource generated by the `landing` static-website construct will be extended with the new `Comment: Landing distribution` CloudFormation property.
+
+```yaml
+constructs:
+    landing:
+        type: static-website
+        path: public
+        extensions:
+            distribution:
+                Properties:
+                    Comment: Landing distribution
+```
+
+### Available extensions
+
+| Extension key 	| CloudFormation resource       	| CloudFormation documentation                                                                                           	|
+|---------------	|-------------------------------	|------------------------------------------------------------------------------------------------------------------------	|
+| distribution  	| AWS::CloudFront::Distribution 	| [Link](https://docs.aws.amazon.com/fr_fr/AWSCloudFormation/latest/UserGuide/aws-resource-cloudfront-distribution.html) 	|
+
 ### More options
 
-Looking for more options in the construct configuration? [Open a GitHub issue](https://github.com/getlift/lift/issues/new).
+Feel like a common extension pattern should be implemented as part of the construct configuration? [Open a GitHub issue](https://github.com/getlift/lift/issues/new).
+
diff --git a/docs/storage.md b/docs/storage.md
@@ -91,6 +91,26 @@ constructs:
         encryption: kms
 ```
 
+## Extensions
+
+You can specify an `extensions` property on the storage construct to extend the underlying CloudFormation resources. In the exemple below, the S3 Bucket CloudFormation resource generated by the `avatars` storage construct will be extended with the new `AccessControl: PublicRead` CloudFormation property.
+
+```yaml
+constructs:
+    avatars:
+        type: storage
+        extensions:
+            bucket:
+                Properties:
+                    AccessControl: PublicRead
+```
+
+### Available extensions
+
+| Extension key 	| CloudFormation resource 	| CloudFormation documentation                                                                         	|
+|---------------	|-------------------------	|------------------------------------------------------------------------------------------------------	|
+| bucket        	| AWS::S3::Bucket         	| [Link](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket.html) 	|
+
 ### More options
 
-Looking for more options in the construct configuration? [Open a GitHub issue](https://github.com/getlift/lift/issues/new).
+Feel like a common extension pattern should be implemented as part of the construct configuration? [Open a GitHub issue](https://github.com/getlift/lift/issues/new).
diff --git a/docs/webhook.md b/docs/webhook.md
@@ -161,3 +161,30 @@ constructs:
 ```
 
 Always favor dynamic path selector to ensure the minimum amount of compute is executed downstream. The list of available dynamic selector is available in [API Gateway documentation](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-aws-services.html#http-api-develop-integrations-aws-services-parameter-mapping).
+
+## Extensions
+
+You can specify an `extensions` property on the webhook construct to extend the underlying CloudFormation resources. In the exemple below, the EventBridge Bus CloudFormation resource generated by the `stripe` webhook construct will be extended with the new `Name: StripeBus` CloudFormation property.
+
+```yaml
+constructs:
+    stripe:
+        type: webhook
+        insecure: true
+        path: /stripe
+        extensions:
+            bus:
+                Properties:
+                    Name: StripeBus
+```
+
+### Available extensions
+
+| Extension key 	| CloudFormation resource 	| CloudFormation documentation                                                                              	|
+|---------------	|-------------------------	|-----------------------------------------------------------------------------------------------------------	|
+| api           	| AWS::ApiGatewayV2::Api  	| [Link](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html) 	|
+| bus           	| AWS::Events::EventBus   	| [Link](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket.html)      	|
+
+### More options
+
+Feel like a common extension pattern should be implemented as part of the construct configuration? [Open a GitHub issue](https://github.com/getlift/lift/issues/new).