diff --git a/README.md b/README.md index 1cf1b799..6d306e69 100644 --- 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 index 17b392c6..3bf621ea 100644 --- 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 index 92ae72de..22ffdc0b 100644 --- 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 index 5b0aea0b..2c0fe78f 100644 --- 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 index c51cf33e..afa874dd 100644 --- 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 index 0d90f351..1fa887e0 100644 --- 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 index 4ce555aa..5e4e74bd 100644 --- 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 index a58c0786..984919fa 100644 --- 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).