docs: add article and other minor fixes as well ad deps updates (#869)

Co-authored-by: Ran Isenberg <[email protected]>

Author: ran-isenberg

.pre-commit-config.yaml

@@ -26,7 +26,7 @@ repos:
         exclude: "^(?!helpers/)"
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.5.5
+    rev: v0.6.1
     hooks:
       # Run the Ruff linter.
       - id: ruff

README.md

@@ -1,4 +1,3 @@
-
 # AWS Lambda Handler Cookbook (Python)
 
 [![license](https://img.shields.io/github/license/ran-isenberg/aws-lambda-handler-cookbook)](https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/master/LICENSE)
@@ -13,36 +12,47 @@
 
 This project provides a working, open source based, AWS Lambda handler skeleton Python code including DEPLOYMENT code with CDK and a pipeline.
 
-This project can serve as a template for new Serverless services - CDK deployment code, pipeline and handler are covered.
+This project can serve as a blueprint for new Serverless services - CDK deployment code, pipeline and handler are covered.
 
 **[📜Documentation](https://ran-isenberg.github.io/aws-lambda-handler-cookbook/)** | **[Blogs website](https://www.ranthebuilder.cloud)**
-> **Contact details | [email protected]**
+> **Contact details | mailto:[email protected]**
 
 [![Twitter Follow](https://img.shields.io/twitter/follow/IsenbergRan?label=Follow&style=social)](https://twitter.com/IsenbergRan)
 [![Website](https://img.shields.io/badge/Website-www.ranthebuilder.cloud-blue)](https://www.ranthebuilder.cloud/)
 
+## AWS Recommendation
+
+This repository was recommended in an AWS blog post [Best practices for accelerating development with serverless blueprints](https://aws.amazon.com/blogs/infrastructure-and-automation/best-practices-for-accelerating-development-with-serverless-blueprints/)
+
+![aws_article](https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/docs/media/article.png?raw=true)
+
+## Concepts
+
+I spoke at AWS re:invent 2023 with Heitor Lessa, former Chief Architect of Powertools for AWS Lambda about the concepts I implemented in this project.
+
+[![Watch the video](https://img.youtube.com/vi/52W3Qyg242Y/maxresdefault.jpg)](https://www.youtube.com/watch?v=52W3Qyg242Y)
+
 ## Getting Started
 
-You can start with a clean service out of this template repository without using the 'Template' button on GitHub.
+You can start with a clean service out of this blueprint repository without using the 'Template' button on GitHub.
 
 You can use Cookiecutter.
 
 * Cookiecutter - install with pip/brew ``brew install cookiecutter`` or ``pip install cookiecutter``
 
 Then run:
 
-```
+```bash
 cookiecutter gh:ran-isenberg/cookiecutter-serverless-python
 ```
 
 Answer the questions to select repo name, service name, etc.:
 
 ![logo](https://github.com/ran-isenberg/cookiecutter-serverless-python/blob/main/media/howto.png?raw=true)
 
-
 **That's it, your developer environment has been set! you are ready to deploy the service:**
 
-```
+```bash
 cd {new repo folder}
 poetry shell
 make deploy
@@ -54,99 +64,101 @@ You can also run 'make pr' will run all checks, synth, file formatters , unit te
 
 Starting a Serverless service can be overwhelming. You need to figure out many questions and challenges that have nothing to do with your business domain:
 
-- How to deploy to the cloud? What IAC framework do you choose?
-- How to write a SaaS-oriented CI/CD pipeline? What does it need to contain?
-- How do you handle observability, logging, tracing, metrics?
-- How do you write a Lambda function?
-- How do you handle testing?
-- What makes an AWS Lambda handler resilient, traceable, and easy to maintain? How do you write such a code?
-
+* How to deploy to the cloud? What IAC framework do you choose?
+* How to write a SaaS-oriented CI/CD pipeline? What does it need to contain?
+* How do you handle observability, logging, tracing, metrics?
+* How do you write a Lambda function?
+* How do you handle testing?
+* What makes an AWS Lambda handler resilient, traceable, and easy to maintain? How do you write such a code?
 
 ## **The Solution**
 
-This project aims to reduce cognitive load and answer these questions for you by providing a skeleton Python Serverless service template that implements best practices for AWS Lambda, Serverless CI/CD, and AWS CDK in one template project.
-
-## Concepts
-
-I spoke at AWS re:invent 2023 with Heitor Lessa, Chief Architect of Powertools for AWS Lambda about the concepts I implemented in this project.
-
-[![Watch the video](https://img.youtube.com/vi/52W3Qyg242Y/maxresdefault.jpg)](https://www.youtube.com/watch?v=52W3Qyg242Y)
+This project aims to reduce cognitive load and answer these questions for you by providing a skeleton Python Serverless service blueprint that implements best practices for AWS Lambda, Serverless CI/CD, and AWS CDK in one blueprint project.
 
 ### Serverless Service - The Order service
 
-- This project provides a working orders service where customers can create orders of items.
+* This project provides a working orders service where customers can create orders of items.
 
-- The project deploys an API GW with an AWS Lambda integration under the path POST /api/orders/ and stores data in a DynamoDB table.
+* The project deploys an API GW with an AWS Lambda integration under the path POST /api/orders/ and stores data in a DynamoDB table.
 
 ![design](https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/docs/media/design.png?raw=true)
 <br></br>
 
 #### **Monitoring Design**
+
 ![monitoring_design](https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/docs/media/monitoring_design.png?raw=true)
 <br></br>
-### **Features**
 
-- Python Serverless service with a recommended file structure.
-- CDK infrastructure with infrastructure tests and security tests.
-- CI/CD pipelines based on Github actions that deploys to AWS with python linters, complexity checks and style formatters.
-- CI/CD pipeline deploys to dev/staging and production environments with different gates between each environment
-- Makefile for simple developer experience.
-- The AWS Lambda handler embodies Serverless best practices and has all the bells and whistles for a proper production ready handler.
-- AWS Lambda handler uses [AWS Lambda Powertools](https://docs.powertools.aws.dev/lambda-python/).
-- AWS Lambda handler 3 layer architecture: handler layer, logic layer and data access layer
-- Features flags and configuration based on AWS AppConfig
-- Idempotent API
-- REST API protected by WAF with four AWS managed rules in production deployment
-- CloudWatch dashboards - High level and low level including CloudWatch alarms
-- Unit, infrastructure, security, integration and end to end tests.
-- Automatically generated OpenAPI endpoint: /swagger with Pydantic schemas for both requests and responses
-- CI swagger protection - fails the PR if your swagger JSON file (stored at docs/swagger/openapi.json) is out of date
-- Automated protection against API breaking changes
+### **Features**
 
+* Python Serverless service with a recommended file structure.
+* CDK infrastructure with infrastructure tests and security tests.
+* CI/CD pipelines based on Github actions that deploys to AWS with python linters, complexity checks and style formatters.
+* CI/CD pipeline deploys to dev/staging and production environments with different gates between each environment
+* Makefile for simple developer experience.
+* The AWS Lambda handler embodies Serverless best practices and has all the bells and whistles for a proper production ready handler.
+* AWS Lambda handler uses [AWS Lambda Powertools](https://docs.powertools.aws.dev/lambda-python/).
+* AWS Lambda handler 3 layer architecture: handler layer, logic layer and data access layer
+* Features flags and configuration based on AWS AppConfig
+* Idempotent API
+* REST API protected by WAF with four AWS managed rules in production deployment
+* CloudWatch dashboards - High level and low level including CloudWatch alarms
+* Unit, infrastructure, security, integration and end to end tests.
+* Automatically generated OpenAPI endpoint: /swagger with Pydantic schemas for both requests and responses
+* CI swagger protection - fails the PR if your swagger JSON file (stored at docs/swagger/openapi.json) is out of date
+* Automated protection against API breaking changes
 
 ## CDK Deployment
+
 The CDK code create an API GW with a path of /api/orders which triggers the lambda on 'POST' requests.
 
 The AWS Lambda handler uses a Lambda layer optimization which takes all the packages under the [packages] section in the Pipfile and downloads them in via a Docker instance.
 
 This allows you to package any custom dependencies you might have, just add them to the Pipfile under the [packages] section.
 
 ## Serverless Best Practices
+
 The AWS Lambda handler will implement multiple best practice utilities.
 
 Each utility is implemented when a new blog post is published about that utility.
 
 The utilities cover multiple aspect of a production-ready service, including:
 
-- [Logging](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-elevate-your-handler-s-code-part-1-logging)
-- [Observability: Monitoring and Tracing](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-elevate-your-handler-s-code-part-2-observability)
-- [Observability: Business KPIs Metrics](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-elevate-your-handler-s-code-part-3-business-domain-observability)
-- [Environment Variables](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-environment-variables)
-- [Input Validation](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-elevate-your-handler-s-code-part-5-input-validation)
-- [Dynamic Configuration & feature flags](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-part-6-feature-flags-configuration-best-practices)
-- [Start Your AWS Serverless Service With Two Clicks](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-part-7-how-to-use-the-aws-lambda-cookbook-github-template-project)
-- [CDK Best practices](https://github.com/ran-isenberg/aws-lambda-handler-cookbook)
-- [Serverless Monitoring](https://www.ranthebuilder.cloud/post/how-to-effortlessly-monitor-serverless-applications-with-cloudwatch-part-one)
-- [API Idempotency](https://www.ranthebuilder.cloud/post/serverless-api-idempotency-with-aws-lambda-powertools-and-cdk)
-- [Serverless OpenAPI Documentation with AWS Powertools](https://www.ranthebuilder.cloud/post/serverless-open-api-documentation-with-aws-powertools)
+* [Logging](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-elevate-your-handler-s-code-part-1-logging)
+* [Observability: Monitoring and Tracing](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-elevate-your-handler-s-code-part-2-observability)
+* [Observability: Business KPIs Metrics](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-elevate-your-handler-s-code-part-3-business-domain-observability)
+* [Environment Variables](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-environment-variables)
+* [Input Validation](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-elevate-your-handler-s-code-part-5-input-validation)
+* [Dynamic Configuration & feature flags](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-part-6-feature-flags-configuration-best-practices)
+* [Start Your AWS Serverless Service With Two Clicks](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-part-7-how-to-use-the-aws-lambda-cookbook-github-blueprint-project)
+* [CDK Best practices](https://github.com/ran-isenberg/aws-lambda-handler-cookbook)
+* [Serverless Monitoring](https://www.ranthebuilder.cloud/post/how-to-effortlessly-monitor-serverless-applications-with-cloudwatch-part-one)
+* [API Idempotency](https://www.ranthebuilder.cloud/post/serverless-api-idempotency-with-aws-lambda-powertools-and-cdk)
+* [Serverless OpenAPI Documentation with AWS Powertools](https://www.ranthebuilder.cloud/post/serverless-open-api-documentation-with-aws-powertools)
 
 ## Getting started
+
 Head over to the complete project documentation pages at GitHub pages at [https://ran-isenberg.github.io/aws-lambda-handler-cookbook](https://ran-isenberg.github.io/aws-lambda-handler-cookbook/)
 
 ## Code Contributions
+
 Code contributions are welcomed. Read this [guide.](https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/CONTRIBUTING.md)
 
 ## Code of Conduct
+
 Read our code of conduct [here.](https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/CODE_OF_CONDUCT.md)
 
 ## Connect
+
 * Email: [[email protected]](mailto:[email protected])
 * Blog Website [RanTheBuilder](https://www.ranthebuilder.cloud)
 * LinkedIn: [ranisenberg](https://www.linkedin.com/in/ranisenberg/)
 * Twitter: [IsenbergRan](https://twitter.com/IsenbergRan)
 
 ## Credits
+
 * [AWS Lambda Powertools (Python)](https://github.com/aws-powertools/powertools-lambda-python)
 
 ## License
+
 This library is licensed under the MIT License. See the [LICENSE](https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/LICENSE) file.

cdk/service/service_stack.py

@@ -14,7 +14,7 @@ def __init__(self, scope: Construct, id: str, is_production_env: bool, **kwargs)
         self._add_stack_tags()
 
         # This construct should be deployed in a different repo and have its own pipeline so updates can be decoupled
-        # from running the service pipeline and without redeploying the service lambdas. For the sake of this template
+        # from running the service pipeline and without redeploying the service lambdas. For the sake of this blueprint
         # example, it is deployed as part of the service stack
         self.dynamic_configuration = ConfigurationStore(
             self,
@@ -47,10 +47,10 @@ def _add_security_tests(self) -> None:
                 {'id': 'AwsSolutions-IAM4', 'reason': 'policy for cloudwatch logs.'},
                 {'id': 'AwsSolutions-IAM5', 'reason': 'policy for cloudwatch logs.'},
                 {'id': 'AwsSolutions-APIG2', 'reason': 'lambda does input validation'},
-                {'id': 'AwsSolutions-APIG1', 'reason': 'not mandatory in a sample template'},
-                {'id': 'AwsSolutions-APIG3', 'reason': 'not mandatory in a sample template'},
-                {'id': 'AwsSolutions-APIG6', 'reason': 'not mandatory in a sample template'},
-                {'id': 'AwsSolutions-APIG4', 'reason': 'authorization not mandatory in a sample template'},
+                {'id': 'AwsSolutions-APIG1', 'reason': 'not mandatory in a sample blueprint'},
+                {'id': 'AwsSolutions-APIG3', 'reason': 'not mandatory in a sample blueprint'},
+                {'id': 'AwsSolutions-APIG6', 'reason': 'not mandatory in a sample blueprint'},
+                {'id': 'AwsSolutions-APIG4', 'reason': 'authorization not mandatory in a sample blueprint'},
                 {'id': 'AwsSolutions-COG4', 'reason': 'not using cognito'},
                 {'id': 'AwsSolutions-L1', 'reason': 'False positive'},
             ],

docs/getting_started.md

@@ -12,7 +12,7 @@ description: AWS Lambda Cookbook Project Getting started
 
 ## Getting Started
 
-You can start with a clean service out of this template repository without using the 'Template' button on GitHub.
+You can start with a clean service out of this blueprint repository without using the 'Template' button on GitHub.
 
 You can use Cookiecutter.
 

docs/index.md

@@ -1,11 +1,23 @@
 ---
 title: Homepage
-description: AWS Lambda Handler Cookbook - a Serverless Service Template
+description: AWS Lambda Handler Cookbook - a Serverless Service Blueprint
 ---
-## **AWS Lambda Handler Cookbook - A Serverless Service Template**
+## **AWS Lambda Handler Cookbook - A Serverless Service Blueprint**
 
 [<img alt="alt_text" src="./media/banner.png" />](https://www.ranthebuilder.cloud/)
 
+## AWS Recommendation
+
+This repository was recommended in an AWS blog post [Best practices for accelerating development with serverless blueprints](https://aws.amazon.com/blogs/infrastructure-and-automation/best-practices-for-accelerating-development-with-serverless-blueprints/){:target="_blank" rel="noopener"}
+
+<img alt="aws article" src="./media/article.png" />
+
+## Concepts
+
+I spoke at AWS re:invent 2023 with Heitor Lessa, former Chief Architect of Powertools for AWS Lambda about the concepts I implemented in this project.
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/52W3Qyg242Y" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
 ## **The Problem**
 
 Starting a Serverless service can be overwhelming. You need to figure out many questions and challenges that have nothing to do with your business domain:
@@ -17,25 +29,19 @@ Starting a Serverless service can be overwhelming. You need to figure out many q
 
 ## **The Solution**
 
-This project aims to reduce cognitive load and answer these questions for you by providing a skeleton Python Serverless service template that implements best practices for AWS Lambda, Serverless CI/CD, and AWS CDK in one template project.
+This project aims to reduce cognitive load and answer these questions for you by providing a skeleton Python Serverless service blueprint that implements best practices for AWS Lambda, Serverless CI/CD, and AWS CDK in one blueprint project.
 
 ### Serverless Service - The Order service
 
-<img alt="alt_text" src="./media/design.png" />
+<img alt="design" src="./media/design.png" />
 
 - This project provides a working orders service where customers can create orders of items.
 
 - The project deploys an API GW with an AWS Lambda integration under the path POST /api/orders/ and stores orders data in a DynamoDB table.
 
 #### **Monitoring Design**
 
-<img alt="alt_text" src="./media/monitoring_design.png" />
-
-## Concepts
-
-I spoke at AWS re:invent 2023 with Heitor Lessa, Chief Architect of Powertools for AWS Lambda about the concepts I implemented in this project.
-
-<iframe width="560" height="315" src="https://www.youtube.com/embed/52W3Qyg242Y" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+<img alt="monitoring" src="./media/monitoring_design.png" />
 
 ### **Features**
 
@@ -55,7 +61,7 @@ I spoke at AWS re:invent 2023 with Heitor Lessa, Chief Architect of Powertools f
 - Automatically generated OpenAPI endpoint: /swagger with Pydantic schemas for both requests and responses
 - Automated protection against API breaking changes
 
-The GitHub template project can be found at [https://github.com/ran-isenberg/aws-lambda-handler-cookbook](https://github.com/ran-isenberg/aws-lambda-handler-cookbook){:target="_blank" rel="noopener"}.
+The GitHub blueprint project can be found at [https://github.com/ran-isenberg/aws-lambda-handler-cookbook](https://github.com/ran-isenberg/aws-lambda-handler-cookbook){:target="_blank" rel="noopener"}.
 
 ## **Serverless Best Practices**
 

docs/media/article.png

@@ -1,5 +1,5 @@
 {
     "dependencies": {
-        "aws-cdk": "2.150.0"
+        "aws-cdk": "2.152.0"
     }
 }