Skip to content

Commit f7d0b52

Browse files
leandrodamascenaleandrodamascena
authored
docs(build_recipes): add build tools page (#7201)
* Adding build tools page * Adding build tools page * Adding build tools page * Adding build tools page
1 parent 14ec182 commit f7d0b52

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

51 files changed

+2127
-13
lines changed

‎docs/build_recipes/build-tools.md

Lines changed: 525 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/build_recipes/getting-started.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,12 @@ Each build tool has its strengths and is optimized for different use cases. Cons
1919

2020
| Tool | Best for | Considerations |
2121
| --------------------- | --------------------------------- | ------------------------------------------- |
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 |
22+
| **[pip](build-tools.md#pip)** | Simple projects, CI/CD | Lightweight, universal |
23+
| **[uv](build-tools.md#uv)** | Fast builds, performance-critical | Extremely fast, Rust-based |
24+
| **[poetry](bbuild-tools.md#poetry)** | Modern Python projects | Excellent dependency management, lock files |
25+
| **[SAM](build-tools.md#sam)** | AWS-native deployments | Integrated with AWS, local testing |
26+
| **[CDK](build-tools.md#cdk)** | Infrastructure as code | Programmatic infrastructure, type safety |
27+
| **[pants](build-tools.md#pants)** | Monorepos, complex projects | Advanced build system, incremental builds |
2828

2929
???+ tip
3030
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: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -39,16 +39,16 @@ This guide is organized into focused sections to help you find exactly what you
3939
### 📚 Fundamentals
4040

4141
* **[Getting started](getting-started.md)** - Prerequisites, tool selection, and basic setup
42-
* **[Cross-platform builds](cross-platform.md)** - Handle architecture differences and compiled dependencies
42+
* **[Cross-platform builds](cross-integration.md)** - Handle architecture differences and compiled dependencies
4343

4444
### 🔧 Build tools
4545

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
46+
* **[Build with pip](build-tools.md#pip)** - Simple, universal package management
47+
* **[Build with uv](build-tools.md#uv)** - Extremely fast Rust-based package manager
48+
* **[Build with Poetry](build-tools.md#poetry)** - Modern dependency management with lock files
49+
* **[Build with SAM](build-tools.md#sam)** - AWS Serverless Application Model integration
50+
* **[Build with CDK](build-tools.md#cdk)** - Infrastructure as code with type safety
51+
* **[Build with Pants](build-tools.md#pants)** - Advanced build system for monorepos
5252

5353
### ⚡ Advanced topics
5454

‎examples/build_recipes/cdk/basic/app.py

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
#!/usr/bin/env python3
2+
import aws_cdk as cdk
3+
from aws_cdk import (
4+
Duration,
5+
Stack,
6+
)
7+
from aws_cdk import (
8+
aws_apigateway as apigateway,
9+
)
10+
from aws_cdk import (
11+
aws_lambda as _lambda,
12+
)
13+
from aws_cdk import (
14+
aws_logs as logs,
15+
)
16+
from constructs import Construct
17+
18+
19+
class PowertoolsLambdaStack(Stack):
20+
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
21+
super().__init__(scope, construct_id, **kwargs)
22+
23+
# Use public Powertools layer
24+
powertools_layer = _lambda.LayerVersion.from_layer_version_arn(
25+
self,
26+
"PowertoolsLayer",
27+
layer_version_arn="arn:aws:lambda:us-east-1:017000801446:layer:AWSLambdaPowertoolsPythonV3-python313-x86_64:1",
28+
)
29+
30+
# Lambda Function
31+
api_function = _lambda.Function(
32+
self,
33+
"ApiFunction",
34+
runtime=_lambda.Runtime.PYTHON_3_13,
35+
handler="lambda_function.lambda_handler",
36+
code=_lambda.Code.from_asset("src"),
37+
layers=[powertools_layer],
38+
timeout=Duration.seconds(30),
39+
memory_size=512,
40+
environment={
41+
"POWERTOOLS_SERVICE_NAME": "api-service",
42+
"POWERTOOLS_METRICS_NAMESPACE": "MyApp",
43+
"POWERTOOLS_LOG_LEVEL": "INFO",
44+
},
45+
log_retention=logs.RetentionDays.ONE_WEEK,
46+
)
47+
48+
# API Gateway
49+
api = apigateway.RestApi(
50+
self,
51+
"ApiGateway",
52+
rest_api_name="Powertools API",
53+
description="API powered by Lambda with Powertools",
54+
)
55+
56+
# API Integration
57+
integration = apigateway.LambdaIntegration(api_function)
58+
api.root.add_proxy(
59+
default_integration=integration,
60+
any_method=True,
61+
)
62+
63+
# Outputs
64+
cdk.CfnOutput(
65+
self,
66+
"ApiUrl",
67+
value=api.url,
68+
description="API Gateway URL",
69+
)
70+
71+
72+
app = cdk.App()
73+
PowertoolsLambdaStack(app, "PowertoolsLambdaStack")
74+
app.synth()

‎examples/build_recipes/cdk/basic/build-cdk.sh

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
#!/bin/bash
2+
3+
echo "🏗️ Building CDK application..."
4+
5+
# Install CDK dependencies
6+
pip install -r requirements.txt
7+
8+
# Bootstrap CDK (first time only)
9+
# cdk bootstrap
10+
11+
# Deploy stack
12+
cdk deploy --require-approval never
13+
14+
echo "✅ CDK application deployed successfully"

‎examples/build_recipes/cdk/basic/cdk-commands.sh

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
#!/bin/bash
2+
# Install Python dependencies
3+
pip install -r requirements.txt
4+
5+
# Synthesize CloudFormation template
6+
cdk synth
7+
8+
# Deploy stack
9+
cdk deploy
10+
11+
# Deploy specific stack
12+
cdk deploy MyLambdaStack
13+
14+
# Destroy stack
15+
cdk destroy
16+
17+
# List all stacks
18+
cdk list
19+
20+
# Compare deployed stack with current state
21+
cdk diff

‎examples/build_recipes/cdk/basic/cdk.json

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
{
2+
"app": "python app.py",
3+
"watch": {
4+
"include": [
5+
"**"
6+
],
7+
"exclude": [
8+
"README.md",
9+
"cdk*.json",
10+
"requirements*.txt",
11+
"source.bat",
12+
"**/__pycache__",
13+
"**/.venv"
14+
]
15+
},
16+
"context": {
17+
"@aws-cdk/aws-lambda:recognizeLayerVersion": true,
18+
"@aws-cdk/core:checkSecretUsage": true,
19+
"@aws-cdk/core:target-partitions": ["aws", "aws-cn"],
20+
"@aws-cdk-containers/ecs-service-extensions:enableDefaultLogDriver": true,
21+
"@aws-cdk/aws-ec2:uniqueImdsv2TemplateName": true,
22+
"@aws-cdk/aws-ecs:arnFormatIncludesClusterName": true,
23+
"@aws-cdk/core:validateSnapshotRemovalPolicy": true,
24+
"@aws-cdk/aws-codepipeline:crossAccountKeyAliasStackSafeResourceName": true,
25+
"@aws-cdk/aws-s3:createDefaultLoggingPolicy": true,
26+
"@aws-cdk/aws-sns-subscriptions:restrictSqsDescryption": true,
27+
"@aws-cdk/aws-apigateway:disableCloudWatchRole": true,
28+
"@aws-cdk/core:enablePartitionLiterals": true,
29+
"@aws-cdk/aws-events:eventsTargetQueueSameAccount": true,
30+
"@aws-cdk/aws-iam:minimizePolicies": true,
31+
"@aws-cdk/core:validateSnapshotRemovalPolicy": true,
32+
"@aws-cdk/aws-codepipeline:crossAccountKeysDefaultValueToFalse": true,
33+
"@aws-cdk/aws-s3:serverAccessLogsUseBucketPolicy": true,
34+
"@aws-cdk/aws-route53-patters:useCertificate": true,
35+
"@aws-cdk/customresources:installLatestAwsSdkDefault": false
36+
}
37+
}

‎examples/build_recipes/cdk/basic/setup-cdk.sh

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
#!/bin/bash
2+
# Install AWS CDK CLI
3+
npm install -g aws-cdk
4+
5+
# Verify installation
6+
cdk --version
7+
8+
# Bootstrap CDK in your AWS account (one-time setup)
9+
cdk bootstrap aws://ACCOUNT-ID/REGION

‎examples/build_recipes/cdk/basic/src/lambda_function.py

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
from aws_lambda_powertools import Logger, Metrics, Tracer
2+
from aws_lambda_powertools.event_handler import APIGatewayRestResolver
3+
from aws_lambda_powertools.logging import correlation_paths
4+
from aws_lambda_powertools.metrics import MetricUnit
5+
6+
logger = Logger()
7+
tracer = Tracer()
8+
metrics = Metrics()
9+
app = APIGatewayRestResolver()
10+
11+
12+
@app.get("/health")
13+
def health_check():
14+
return {"status": "healthy", "service": "powertools-cdk"}
15+
16+
17+
@app.get("/metrics")
18+
def get_metrics():
19+
metrics.add_metric(name="MetricsEndpointCalled", unit=MetricUnit.Count, value=1)
20+
return {"message": "Metrics recorded"}
21+
22+
23+
@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
24+
@tracer.capture_lambda_handler
25+
@metrics.log_metrics(capture_cold_start_metric=True)
26+
def lambda_handler(event, context):
27+
return app.resolve(event, context)

‎examples/build_recipes/cdk/multi-stack/app_multi_stack.py

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
#!/usr/bin/env python3
2+
import aws_cdk as cdk
3+
from stacks.powertools_cdk_stack import PowertoolsStack
4+
5+
app = cdk.App()
6+
7+
# Get environment from context or default to dev
8+
environment = app.node.try_get_context("environment") or "dev"
9+
10+
# Create stack for the specified environment
11+
PowertoolsStack(
12+
app,
13+
f"PowertoolsStack-{environment}",
14+
environment=environment,
15+
env=cdk.Environment(
16+
account=app.node.try_get_context("account"),
17+
region=app.node.try_get_context("region") or "us-east-1",
18+
),
19+
)
20+
21+
app.synth()

0 commit comments

Comments
 (0)