docs(build_recipes): add Lambda build recipes for pip, poetry, uv, SAM, CDK, and pants #7149
Conversation
pull-request-size
bot
added
the
size/XXL
|
Not all issues are linked correctly. Please link each issue to the PR either manually or using a closing keyword in the format If mentioning more than one issue, separate them with commas: i.e. |
boring-cyborg
bot
added
documentation
|
2 similar comments
|
|
|
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #7149 +/- ##
========================================
Coverage 96.35% 96.35%
========================================
Files 275 275
Lines 12980 12980
Branches 965 965
========================================
Hits 12507 12507
Misses 366 366
Partials 107 107 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
Hi @phipag, I'm not sure I understand your question, but I assume you're asking about the assets Pls let me know if this answer is enough |
Yes, thanks. This is what I meant. |
|
Will review this PR? Please read this comments: 1/ You don't need to test every script; I've tested it extensively and it's working as expected. But if you want, please go ahead. |
|
Hi @phipag @sthulb @dreamorosi @svozza, I asked you for a review on this PR. Please read this comment before reviewing: #7149 (comment) |
leandrodamascena
requested review from
svozza
and removed request for
anafalcao
|
| powertools_layer = _lambda.LayerVersion.from_layer_version_arn( | ||
| self, | ||
| "PowertoolsLayer", | ||
| layer_version_arn="arn:aws:lambda:us-east-1:017000801446:layer:AWSLambdaPowertoolsPythonV3-python313-x86_64:1", |
|
| cd build && zip -r ../lambda-deployment.zip . && cd .. | ||
|
|
||
| - name: Upload artifact | ||
| uses: actions/upload-artifact@v4 |
There was a problem hiding this comment.
Use hashes wherever possible
There was a problem hiding this comment.
Thats a good point! The idea of not using hashes here was to avoid more dependabot bumps, but I think this will decrease our scorecard score. Thanks for flagging that, I'll change.
There was a problem hiding this comment.
I was thinking more of sharing/encouraging best practices in the examples we give customers.
If you want to avoid Dependabot spam on these, you can add a section to its config to explicitly exclude this (and other) files.
| powertools_layer = _lambda.LayerVersion.from_layer_version_arn( | ||
| self, | ||
| "PowertoolsLayer", | ||
| layer_version_arn="arn:aws:lambda:us-east-1:017000801446:layer:AWSLambdaPowertoolsPythonV3-python313-x86_64:1", |
There was a problem hiding this comment.
This looks like an old version
There was a problem hiding this comment.
Yep! @svozza flagged that and I'll update
| ) | ||
|
|
||
| # Lambda Function | ||
| api_function = _lambda.Function( |
There was a problem hiding this comment.
Why not use the Python function package in CDK that does the packaging for you?
docs/build_recipes.md
Outdated
| |------|------------| | ||
| | **Deployment Package** | A ZIP archive or container image containing your Lambda function code and all its dependencies, ready for deployment to AWS Lambda | | ||
| | **Lambda Layer** | A ZIP archive containing libraries, custom runtimes, or other function dependencies that can be shared across multiple Lambda functions | | ||
| | **Build Tool** | Software that automates the process of compiling, packaging, and preparing your code for deployment (e.g., pip, poetry, uv, pants) | |
There was a problem hiding this comment.
| | **Build Tool** | Software that automates the process of compiling, packaging, and preparing your code for deployment (e.g., pip, poetry, uv, pants) | | |
| | **Build Tool** | Software that automates the process of compiling, packaging, and preparing your code for deployment (e.g., `pip`, `poetry`, `uv`, `pants`) | |
docs/build_recipes.md
Outdated
| | **Lambda Layer** | A ZIP archive containing libraries, custom runtimes, or other function dependencies that can be shared across multiple Lambda functions | | ||
| | **Build Tool** | Software that automates the process of compiling, packaging, and preparing your code for deployment (e.g., pip, poetry, uv, pants) | | ||
| | **Dependency Manager** | Tool responsible for resolving, downloading, and managing external libraries your project depends on | | ||
| | **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) | |
There was a problem hiding this comment.
| | **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) | | |
| | **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`) | |
docs/build_recipes.md
Outdated
|
|
||
| ### CDK | ||
|
|
||
| **AWS CDK (Cloud Development Kit)** allows you to define cloud infrastructure using familiar programming languages like Python, TypeScript, or Java. It provides type safety, IDE support, and the ability to create reusable constructs, making it perfect for complex infrastructure requirements and teams that prefer code over YAML. |
There was a problem hiding this comment.
| **AWS CDK (Cloud Development Kit)** allows you to define cloud infrastructure using familiar programming languages like Python, TypeScript, or Java. It provides type safety, IDE support, and the ability to create reusable constructs, making it perfect for complex infrastructure requirements and teams that prefer code over YAML. | |
| The **AWS CDK (Cloud Development Kit)** allows you to define cloud infrastructure using familiar programming languages like Python, TypeScript, or Java. It provides type safety, IDE support, and the ability to create reusable constructs, making it perfect for complex infrastructure requirements and teams that prefer code over YAML. |
docs/build_recipes.md
Outdated
| ### Best Practices for CI/CD | ||
|
|
||
| 1. **Use Linux runners** (ubuntu-latest) to ensure Lambda compatibility | ||
| 2. **Cache dependencies** to speed up builds (uv, poetry cache, pip cache) |
There was a problem hiding this comment.
| 2. **Cache dependencies** to speed up builds (uv, poetry cache, pip cache) | |
| 2. **Cache dependencies** to speed up builds (`uv`, `poetry cache`, `pip cache`) |
There was a problem hiding this comment.
The content is good, but I think we can do better when it comes to structure and placement, right now it's a wall of text that can be hard to navigate and digest both for humans and LLMs.
From a doc architecture perspective, I don't think this should be a separate tab but instead just be a collapsible section on the left-side menu.
Personally, I'd move a couple things around and have like:
-
Homepage
-
Install/Getting Started (future PR)
-
Changelog
-
Tutorial
-
Workshop
-
Build recipes (this PR - section is collapsed by default, below sections are revealed only when clicking)
index.mdGetting Started (includes intro, key benefits, Terminology, and Getting Started sections)- Cross Platform
- Build with pip
- Build with poetry
- Build with uv
- Build with SAM
- Build with CDK
- Build with Pants
- Performance optimization
- CI/CD integration
- Troubleshooting
-
Features
- Tracer
- Logger
- ...
-
Environment variables (future PR)
-
Upgrade guide
-
Community content (renamed from We Made This)
-
Roadmap
-
Changelog
-
Resources (LLMs)
This structure would also basically break down each section in its own page - since in most cases imo for this topic you rarely want to read top to bottom, but are interested in a specific area/section, this way it's easier to consume/save/share/read for both humans and LLMs.
This is great feedback! I was thinking this document was too information-heavy, but I'm not sure about one thing: this way, won't we take up too much space for Features meny? Maybe these Features sections should always be visible in the menu. Maybe a tab in the top menu isn't the best idea, I agree. But what do you think about this feature issue? I can do a test and see the experience |
I was thinking of having a single item called "Build recipes" that is closed by default like this image below, so that it takes only one space: 
its sub-items would show only if you click on it. And yes, I'd leave "Features" as always visible for now. |
Hey @dreamorosi I'm probably doing something stupid, but I can't make it collapse under 
|
|
|
|
I'm closing this PR because I'll be opening other smaller ones to make reviewing easier. |
Issue number: #3518
Summary
This PR introduces a Build Recipes documentation that addresses challenges when developers are packaging Lambda functions with Python and compiled libraries, especially. Rather than leaving developers to figure out packaging on their own, we now provide recipes for every major Python build tool, complete with working examples, troubleshooting guides, and production-ready CI/CD configurations.
Changes
docs/build_recipes.md- Complete build recipes guideWorking Examples:
examples/build_recipes/pip/- Basic and advanced pip configurations with layersexamples/build_recipes/poetry/- Poetry with Docker builds and lock filesexamples/build_recipes/uv/- Fast uv-based builds with reproducible environmentsexamples/build_recipes/sam/- SAM templates (no-layers, with-layers, multi-env)examples/build_recipes/cdk/- CDK stacks (basic and multi-stack architectures)examples/build_recipes/pants/- Pants build system for monoreposCI/CD Integration:
examples/build_recipes/cicd/github-actions/- GitHub Actions workflowsexamples/build_recipes/cicd/codebuild/- AWS CodeBuild exampleUser experience
Checklist
If your change doesn't seem to apply, please leave them unchecked.
Is this a breaking change?
RFC issue number:
Checklist:
Acknowledgment
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.
Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.