Skip to content

Commit 5ff638b

Browse files
leandrodamascenaleandrodamascena
authored
docs(build_recipes): add initial build recipes structure (#7163)
* Adding build recipes section * Adding build recipes section * Adding build recipes section * Adding build recipes section * Adding build recipes section * Adding build recipes section * Fix sonar issues * Reorganizing docs files * Adding initial structure * Adding initial structure * Adding initial structure
1 parent 6d5ab2a commit 5ff638b

File tree

4 files changed

+100
-6
lines changed

4 files changed

+100
-6
lines changed

‎.pre-commit-config.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ repos:
3434
entry: poetry run cfn-lint
3535
language: system
3636
types: [yaml]
37-
exclude: examples/homepage/install/.*?/serverless\.yml$
37+
exclude: examples/build_recipes/*
3838
files: examples/.*
3939
- repo: https://github.com/rhysd/actionlint
4040
rev: "fd7ba3c382e13dcc0248e425b4cbc3f1185fa3ee" # v1.6.24

‎docs/build_recipes/getting-started.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: Getting Started
3+
description: Prerequisites and setup for building Lambda functions with Powertools
4+
---
5+
6+
<!-- markdownlint-disable MD043 -->
7+
8+
## Prerequisites
9+
10+
Before using any of these recipes, ensure you have:
11+
12+
* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html){target="_blank"} configured
13+
* Python 3.10+ installed
14+
* Your preferred build tool installed (see individual recipes)
15+
16+
## Choosing the right tool
17+
18+
Each build tool has its strengths and is optimized for different use cases. Consider your project complexity, team preferences, and deployment requirements when selecting the best approach.
19+
20+
| Tool | Best for | Considerations |
21+
| --------------------- | --------------------------------- | ------------------------------------------- |
22+
| **[pip](build-with-pip.md)** | Simple projects, CI/CD | Lightweight, universal |
23+
| **[poetry](build-with-poetry.md)** | Modern Python projects | Excellent dependency management, lock files |
24+
| **[uv](build-with-uv.md)** | Fast builds, performance-critical | Extremely fast, Rust-based |
25+
| **[pants](build-with-pants.md)** | Monorepos, complex projects | Advanced build system, incremental builds |
26+
| **[SAM](build-with-sam.md)** | AWS-native deployments | Integrated with AWS, local testing |
27+
| **[CDK](build-with-cdk.md)** | Infrastructure as code | Programmatic infrastructure, type safety |
28+
29+
???+ tip
30+
All examples in this guide are available in the [project repository](https://github.com/aws-powertools/powertools-lambda-python/tree/develop/examples/build_recipes){target="_blank"}.

‎docs/build_recipes/index.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: Build Recipes
3+
description: Lambda function packaging recipes with Powertools for AWS
4+
---
5+
6+
<!-- markdownlint-disable MD043 MD013 -->
7+
8+
As the Python ecosystem continues to evolve with new package managers, build tools, and dependency resolution strategies, choosing the right approach for Lambda deployments has become increasingly complex. Modern Python applications often involve compiled extensions, platform-specific dependencies, and sophisticated toolchains that require careful consideration for serverless environments.
9+
10+
This guide provides practical recipes for packaging Lambda functions with Powertools for AWS Lambda (Python) using different build tools and dependency managers.
11+
12+
## Key benefits
13+
14+
* **Optimized packaging** - Reduce deployment package size and cold start times
15+
* **Dependency management** - Handle complex dependency trees efficiently
16+
* **Build reproducibility** - Consistent builds across environments
17+
* **Layer optimization** - Leverage Lambda Layers for better performance
18+
* **Multi-tool support** - Choose the right tool for your workflow
19+
20+
## Terminology
21+
22+
Understanding these key terms will help you navigate the build recipes more effectively:
23+
24+
| Term | Definition |
25+
|------|------------|
26+
| **Deployment Package** | A ZIP archive or container image containing your Lambda function code and all its dependencies, ready for deployment to AWS Lambda |
27+
| **Lambda Layer** | A ZIP archive containing libraries, custom runtimes, or other function dependencies that can be shared across multiple Lambda functions |
28+
| **Build Tool** | Software that automates the process of compiling, packaging, and preparing your code for deployment (e.g., pip, poetry, uv, pants) |
29+
| **Dependency Manager** | Tool responsible for resolving, downloading, and managing external libraries your project depends on |
30+
| **Lock File** | A file that records the exact versions of all dependencies used in your project, ensuring reproducible builds (e.g., poetry.lock, uv.lock) |
31+
| **Cold Start** | The initialization time when AWS Lambda creates a new execution environment for your function, including loading your deployment package |
32+
| **SAM (Serverless Application Model)** | AWS framework for building serverless applications, providing templates and CLI tools for deploying Lambda functions and related resources |
33+
| **CDK (Cloud Development Kit)** | AWS framework for defining cloud infrastructure using familiar programming languages, enabling infrastructure as code for Lambda deployments |
34+
35+
## Guide sections
36+
37+
This guide is organized into focused sections to help you find exactly what you need:
38+
39+
### 📚 Fundamentals
40+
41+
* **[Getting started](getting-started.md)** - Prerequisites, tool selection, and basic setup
42+
* **[Cross-platform builds](cross-platform.md)** - Handle architecture differences and compiled dependencies
43+
44+
### 🔧 Build tools
45+
46+
* **[Build with pip](build-with-pip.md)** - Simple, universal package management
47+
* **[Build with Poetry](build-with-poetry.md)** - Modern dependency management with lock files
48+
* **[Build with uv](build-with-uv.md)** - Extremely fast Rust-based package manager
49+
* **[Build with SAM](build-with-sam.md)** - AWS Serverless Application Model integration
50+
* **[Build with CDK](build-with-cdk.md)** - Infrastructure as code with type safety
51+
* **[Build with Pants](build-with-pants.md)** - Advanced build system for monorepos
52+
53+
### ⚡ Advanced topics
54+
55+
* **[Performance optimization](performance-optimization.md)** - Reduce cold starts and package size
56+
* **[CI/CD integration](cicd-integration.md)** - Automate builds with GitHub Actions and CodeBuild
57+
* **[Troubleshooting](troubleshooting.md)** - Common issues and solutions

‎mkdocs.yml

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,9 @@ nav:
99
- Homepage:
1010
- index.md
1111
- Changelog: changelog.md
12-
- API reference: api/" target="_blank
13-
- Upgrade guide: upgrade.md
14-
- We Made This (Community): we_made_this.md
12+
- Tutorial: tutorial/index.md
1513
- Workshop 🆕: https://s12d.com/powertools-for-aws-lambda-workshop" target="_blank
16-
- Roadmap: roadmap.md
14+
- API reference: api/" target="_blank
1715
- Features:
1816
- core/tracer.md
1917
- core/logger.md
@@ -40,10 +38,16 @@ nav:
4038
- utilities/middleware_factory.md
4139
- utilities/jmespath_functions.md
4240
- CloudFormation Custom Resources: https://github.com/aws-cloudformation/custom-resource-helper" target="_blank
41+
- Build recipes:
42+
- build_recipes/index.md
43+
- Getting started: build_recipes/getting-started.md
44+
- Upgrade guide: upgrade.md
45+
- We Made This (Community): we_made_this.md
46+
- Roadmap: roadmap.md
4347
- Resources:
4448
- "llms.txt": ./llms.txt
4549
- "llms.txt (full version)": ./llms-full.txt
46-
- Tutorial: tutorial/index.md
50+
4751
- Processes:
4852
- Security: security.md
4953
- Automation: automation.md
@@ -233,6 +237,9 @@ plugins:
233237
- utilities/jmespath_functions.md
234238
Tutorial:
235239
- tutorial/index.md
240+
Build recipes:
241+
- build_recipes/index.md
242+
- build_recipes/getting-started.md
236243

237244
- mkdocstrings:
238245
default_handler: python

0 commit comments

Comments
 (0)