Skip to content

Commit 5a4b2a0

Browse files
leandrodamascenadreamorosi
leandrodamascena
and
dreamorosi
authored
docs(build_recipes): add cicd page (#7176)
Adding CICD page Co-authored-by: Andrea Amorosi <dreamorosi@gmail.com>
1 parent e20a105 commit 5a4b2a0

9 files changed

Lines changed: 645 additions & 0 deletions

File tree

‎docs/build_recipes/cicd-integration.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
title: CI/CD Integration
3+
description: Automate Lambda function builds and deployments
4+
---
5+
6+
<!-- markdownlint-disable MD043 -->
7+
8+
Automate your Lambda function builds and deployments using popular CI/CD platforms. These examples show how to build and deploy Lambda functions with Powertools for AWS with proper cross-platform compatibility and deploy them reliably.
9+
10+
## GitHub Actions
11+
12+
**GitHub Actions** provides a powerful, integrated CI/CD platform that runs directly in your GitHub repository. It offers excellent integration with AWS services, supports matrix builds for testing multiple configurations, and provides a rich ecosystem of pre-built actions.
13+
14+
=== "Modern AWS Lambda deploy action"
15+
16+
```yaml
17+
--8<-- "examples/build_recipes/cicd/github-actions/deploy-modern.yml"
18+
```
19+
20+
=== "Multi-environment deployment"
21+
22+
```yaml
23+
--8<-- "examples/build_recipes/cicd/github-actions/deploy-multi-env.yml"
24+
```
25+
26+
=== "Simple source code deployment"
27+
28+
```yaml
29+
--8<-- "examples/build_recipes/cicd/github-actions/deploy-simple.yml"
30+
```
31+
32+
=== "S3 deployment method"
33+
34+
```yaml
35+
--8<-- "examples/build_recipes/cicd/github-actions/deploy-s3.yml"
36+
```
37+
38+
=== "Build tool integration"
39+
40+
```yaml
41+
--8<-- "examples/build_recipes/cicd/github-actions/deploy-build-tools.yml"
42+
```
43+
44+
## AWS CodeBuild
45+
46+
**AWS CodeBuild** is a fully managed build service that compiles source code, runs tests, and produces deployment packages. It integrates seamlessly with other AWS services and provides consistent build environments with automatic scaling.
47+
48+
=== "Basic CodeBuild Configuration"
49+
50+
```yaml
51+
--8<-- "examples/build_recipes/cicd/codebuild/buildspec.yml"
52+
```
53+
54+
## Best Practices for CI/CD
55+
56+
1. **Use Linux runners** (ubuntu-latest) to ensure Lambda compatibility
57+
2. **Cache dependencies** to speed up builds (uv, poetry cache, pip cache)
58+
3. **Run tests first** before building deployment packages
59+
4. **Use matrix builds** to test multiple Python versions or configurations
60+
5. **Implement proper secrets management** with GitHub Secrets or AWS Parameter Store
61+
6. **Add deployment gates** for production environments
62+
7. **Monitor deployment success** with CloudWatch metrics and alarms
63+
64+
???+ tip "Performance Optimization"
65+
- Use **uv** for fastest dependency installation in CI/CD
66+
- **Cache virtual environments** between builds when possible
67+
- **Parallelize builds** for multiple environments
68+
- **Use container images** for complex dependencies or large packages

‎examples/build_recipes/cicd/codebuild/buildspec-advanced.yml‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
version: 0.2
2+
3+
env:
4+
variables:
5+
PYTHON_VERSION: "3.13"
6+
BUILD_STAGE: "build"
7+
parameter-store:
8+
POWERTOOLS_VERSION: "/build/powertools-version"
9+
10+
batch:
11+
fast-fail: false
12+
build-list:
13+
- identifier: test
14+
env:
15+
variables:
16+
BUILD_STAGE: "test"
17+
- identifier: build_dev
18+
env:
19+
variables:
20+
BUILD_STAGE: "build"
21+
ENVIRONMENT: "dev"
22+
depend-on:
23+
- test
24+
- identifier: build_prod
25+
env:
26+
variables:
27+
BUILD_STAGE: "build"
28+
ENVIRONMENT: "prod"
29+
depend-on:
30+
- test
31+
32+
phases:
33+
install:
34+
runtime-versions:
35+
python: $PYTHON_VERSION
36+
commands:
37+
- echo "Build stage: $BUILD_STAGE, Environment: $ENVIRONMENT"
38+
- pip install --upgrade pip uv
39+
40+
pre_build:
41+
commands:
42+
- |
43+
if [ "$BUILD_STAGE" = "test" ]; then
44+
echo "Installing test dependencies..."
45+
uv venv test-env
46+
source test-env/bin/activate
47+
uv pip install aws-lambda-powertools[all]==$POWERTOOLS_VERSION pytest pytest-cov
48+
cp -r src/ test-src/
49+
else
50+
echo "Installing build dependencies..."
51+
uv venv build-env
52+
source build-env/bin/activate
53+
uv pip install aws-lambda-powertools[all]==$POWERTOOLS_VERSION
54+
uv pip install pydantic requests
55+
fi
56+
57+
build:
58+
commands:
59+
- |
60+
if [ "$BUILD_STAGE" = "test" ]; then
61+
echo "Running tests..."
62+
source test-env/bin/activate
63+
cd test-src
64+
pytest tests/ --cov=. --cov-report=xml --cov-report=term
65+
echo "Tests completed successfully"
66+
else
67+
echo "Building deployment package for $ENVIRONMENT..."
68+
source build-env/bin/activate
69+
70+
# Create environment-specific package
71+
mkdir -p package-$ENVIRONMENT/
72+
cp -r build-env/lib/python*/site-packages/* package-$ENVIRONMENT/
73+
cp -r src/* package-$ENVIRONMENT/
74+
75+
# Environment-specific optimizations
76+
if [ "$ENVIRONMENT" = "prod" ]; then
77+
echo "Applying production optimizations..."
78+
find package-$ENVIRONMENT/ -name "*.pyc" -delete
79+
find package-$ENVIRONMENT/ -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null || true
80+
find package-$ENVIRONMENT/ -name "tests" -type d -exec rm -rf {} + 2>/dev/null || true
81+
find package-$ENVIRONMENT/ -name "*.dist-info" -type d -exec rm -rf {} + 2>/dev/null || true
82+
fi
83+
84+
# Create deployment ZIP
85+
cd package-$ENVIRONMENT && zip -r ../lambda-$ENVIRONMENT.zip . && cd ..
86+
87+
echo "Package size for $ENVIRONMENT: $(du -sh lambda-$ENVIRONMENT.zip)"
88+
fi
89+
90+
post_build:
91+
commands:
92+
- |
93+
if [ "$BUILD_STAGE" = "build" ]; then
94+
echo "Deploying to $ENVIRONMENT environment..."
95+
96+
# Deploy to environment-specific function
97+
aws lambda update-function-code \
98+
--function-name powertools-app-$ENVIRONMENT \
99+
--zip-file fileb://lambda-$ENVIRONMENT.zip \
100+
--region $AWS_DEFAULT_REGION
101+
102+
# Update environment-specific configuration
103+
LOG_LEVEL="INFO"
104+
if [ "$ENVIRONMENT" = "dev" ]; then
105+
LOG_LEVEL="DEBUG"
106+
fi
107+
108+
aws lambda update-function-configuration \
109+
--function-name powertools-app-$ENVIRONMENT \
110+
--environment Variables="{
111+
ENVIRONMENT=$ENVIRONMENT,
112+
POWERTOOLS_SERVICE_NAME=powertools-app-$ENVIRONMENT,
113+
POWERTOOLS_METRICS_NAMESPACE=MyApp/$ENVIRONMENT,
114+
POWERTOOLS_LOG_LEVEL=$LOG_LEVEL
115+
}" \
116+
--region $AWS_DEFAULT_REGION
117+
118+
echo "Deployment to $ENVIRONMENT completed successfully!"
119+
fi
120+
121+
artifacts:
122+
files:
123+
- lambda-*.zip
124+
- coverage.xml
125+
name: lambda-artifacts-$(date +%Y-%m-%d-%H-%M-%S)
126+
127+
cache:
128+
paths:
129+
- 'build-env/**/*'
130+
- 'test-env/**/*'
131+

‎examples/build_recipes/cicd/codebuild/buildspec.yml‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
version: 0.2
2+
3+
env:
4+
variables:
5+
PYTHON_VERSION: "3.13"
6+
POWERTOOLS_VERSION: "3.18.0"
7+
parameter-store:
8+
FUNCTION_NAME: "/lambda/powertools-app/function-name"
9+
10+
phases:
11+
install:
12+
runtime-versions:
13+
python: $PYTHON_VERSION
14+
commands:
15+
- echo "Installing build dependencies..."
16+
- pip install --upgrade pip
17+
- pip install uv poetry # Install fast package managers
18+
19+
pre_build:
20+
commands:
21+
- echo "Pre-build phase started on $(date)"
22+
- echo "Python version: $(python --version)"
23+
- echo "Installing application dependencies..."
24+
25+
# Use uv for fast dependency installation
26+
- uv venv build-env
27+
- source build-env/bin/activate
28+
- uv pip install aws-lambda-powertools[all]==$POWERTOOLS_VERSION
29+
- uv pip install pydantic requests
30+
31+
build:
32+
commands:
33+
- echo "Build started on $(date)"
34+
- echo "Creating deployment package..."
35+
36+
# Create optimized deployment package
37+
- mkdir -p package/
38+
- cp -r build-env/lib/python*/site-packages/* package/
39+
- cp -r src/* package/
40+
41+
# Remove unnecessary files to reduce package size
42+
- find package/ -name "*.pyc" -delete
43+
- find package/ -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null || true
44+
- find package/ -name "tests" -type d -exec rm -rf {} + 2>/dev/null || true
45+
- find package/ -name "*.dist-info" -type d -exec rm -rf {} + 2>/dev/null || true
46+
47+
# Create deployment ZIP
48+
- cd package && zip -r ../lambda-deployment.zip . && cd ..
49+
50+
# Show package info
51+
- echo "Package size: $(du -sh lambda-deployment.zip)"
52+
- echo "Package contents:"
53+
- unzip -l lambda-deployment.zip | head -20
54+
55+
post_build:
56+
commands:
57+
- echo "Build completed on $(date)"
58+
- echo "Deploying Lambda function..."
59+
60+
# Deploy to Lambda
61+
- aws lambda update-function-code \
62+
--function-name $FUNCTION_NAME \
63+
--zip-file fileb://lambda-deployment.zip \
64+
--region $AWS_DEFAULT_REGION
65+
66+
# Update environment variables
67+
- aws lambda update-function-configuration \
68+
--function-name $FUNCTION_NAME \
69+
--environment Variables="{
70+
POWERTOOLS_SERVICE_NAME=powertools-codebuild,
71+
POWERTOOLS_METRICS_NAMESPACE=MyApp/CodeBuild,
72+
POWERTOOLS_LOG_LEVEL=INFO
73+
}" \
74+
--region $AWS_DEFAULT_REGION
75+
76+
- echo "Deployment completed successfully!"
77+
78+
artifacts:
79+
files:
80+
- lambda-deployment.zip
81+
name: lambda-deployment-$(date +%Y-%m-%d-%H-%M-%S)
82+
83+
cache:
84+
paths:
85+
- 'build-env/**/*' # Cache virtual environment for faster builds

‎examples/build_recipes/cicd/github-actions/deploy-build-tools.yml‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
name: Deploy with Different Build Tools
2+
3+
on:
4+
push:
5+
branches: [main]
6+
7+
jobs:
8+
deploy-poetry:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
12+
13+
- name: Set up Python
14+
uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
15+
with:
16+
python-version: '3.13'
17+
18+
- name: Install Poetry
19+
run: pip install --upgrade pip poetry
20+
21+
- name: Build with Poetry
22+
run: |
23+
# Create deployment directory
24+
mkdir -p poetry-deploy/
25+
26+
# Export and install dependencies
27+
poetry export -f requirements.txt --output requirements.txt --without-hashes
28+
pip install --platform manylinux2014_x86_64 --only-binary=:all: \
29+
--python-version 3.13 -r requirements.txt -t poetry-deploy/
30+
31+
# Copy source code
32+
cp -r src/* poetry-deploy/
33+
34+
- name: Configure AWS credentials
35+
uses: aws-actions/configure-aws-credentials@209f2a4450bb4b277e1dedaff40ad2fd8d4d0a4c # v4.3.0
36+
with:
37+
role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
38+
aws-region: us-east-1
39+
40+
- name: Deploy Poetry build
41+
uses: aws-actions/aws-lambda-deploy@246115fccc1ad110c97f729696574d09eb5c690d
42+
with:
43+
function-name: powertools-poetry-function
44+
code-artifacts-dir: poetry-deploy/
45+
handler: app.lambda_handler
46+
runtime: python3.13
47+
environment: '{"POWERTOOLS_SERVICE_NAME":"powertools-poetry","POWERTOOLS_METRICS_NAMESPACE":"MyApp","POWERTOOLS_LOG_LEVEL":"INFO"}'
48+
role: ${{ secrets.LAMBDA_EXECUTION_ROLE_ARN }}
49+
50+
deploy-uv:
51+
runs-on: ubuntu-latest
52+
steps:
53+
- uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
54+
55+
- name: Set up Python
56+
uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
57+
with:
58+
python-version: '3.13'
59+
60+
- name: Build with uv (fastest)
61+
run: |
62+
# Install uv
63+
pip install uv
64+
65+
# Create deployment directory
66+
mkdir -p uv-deploy/
67+
68+
# Install dependencies with uv (much faster)
69+
uv pip install \
70+
--target uv-deploy/ \
71+
--python-version 3.13 \
72+
--platform manylinux2014_x86_64 --only-binary=:all: \
73+
aws-lambda-powertools[all] pydantic requests
74+
75+
# Copy source code
76+
cp -r src/* uv-deploy/
77+
78+
- name: Configure AWS credentials
79+
uses: aws-actions/configure-aws-credentials@209f2a4450bb4b277e1dedaff40ad2fd8d4d0a4c # v4.3.0
80+
with:
81+
role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
82+
aws-region: us-east-1
83+
84+
- name: Deploy uv build
85+
uses: aws-actions/aws-lambda-deploy@246115fccc1ad110c97f729696574d09eb5c690d # v1.0.1
86+
with:
87+
function-name: powertools-uv-function
88+
code-artifacts-dir: uv-deploy/
89+
handler: app.lambda_handler
90+
runtime: python3.13
91+
environment: '{"POWERTOOLS_SERVICE_NAME":"powertools-uv","POWERTOOLS_METRICS_NAMESPACE":"MyApp","POWERTOOLS_LOG_LEVEL":"INFO"}'
92+
role: ${{ secrets.LAMBDA_EXECUTION_ROLE_ARN }}

0 commit comments

Comments
 (0)