Skip to content

Commit 33f2c8f

Browse files
leandrodamascenaleandrodamascena
authored
docs(homepage): reorganize homepage and create dedicated installation page (#7896)
docs: refactor docs page
1 parent c30d9d4 commit 33f2c8f

File tree

3 files changed

+300
-445
lines changed

3 files changed

+300
-445
lines changed

‎docs/getting-started/install.md‎

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
---
2+
title: Installation
3+
description: Installing Powertools for AWS Lambda (Python)
4+
---
5+
6+
<!-- markdownlint-disable MD043 MD013 -->
7+
8+
## Package manager
9+
10+
Most features use Python standard library and the AWS SDK _(boto3)_ that are available in the AWS Lambda runtime.
11+
12+
=== "pip"
13+
14+
```bash
15+
pip install "aws-lambda-powertools"
16+
```
17+
18+
=== "poetry"
19+
20+
```bash
21+
poetry add "aws-lambda-powertools"
22+
```
23+
24+
=== "pdm"
25+
26+
```bash
27+
pdm add "aws-lambda-powertools"
28+
```
29+
30+
=== "uv"
31+
32+
```bash
33+
uv add "aws-lambda-powertools"
34+
```
35+
36+
### Extra dependencies
37+
38+
Some features require additional dependencies. Install them as needed:
39+
40+
| Feature | Install | Default dependency |
41+
| ------- | ------- | ------------------ |
42+
| [Tracer](../core/tracer.md) | `pip install "aws-lambda-powertools[tracer]"` | `aws-xray-sdk` |
43+
| [Validation](../utilities/validation.md) | `pip install "aws-lambda-powertools[validation]"` | `fastjsonschema` |
44+
| [Parser](../utilities/parser.md) | `pip install "aws-lambda-powertools[parser]"` | `pydantic` |
45+
| [Data Masking](../utilities/data_masking.md) | `pip install "aws-lambda-powertools[datamasking]"` | `aws-encryption-sdk`, `jsonpath-ng` |
46+
| [Datadog Metrics](../core/metrics/datadog.md) | `pip install "aws-lambda-powertools[datadog]"` | `datadog-lambda` |
47+
| [Kafka (Avro)](../utilities/kafka.md) | `pip install "aws-lambda-powertools[kafka-consumer-avro]"` | `avro` |
48+
| [Kafka (Protobuf)](../utilities/kafka.md) | `pip install "aws-lambda-powertools[kafka-consumer-protobuf]"` | `protobuf` |
49+
| Redis | `pip install "aws-lambda-powertools[redis]"` | `redis` |
50+
| Valkey | `pip install "aws-lambda-powertools[valkey]"` | `valkey-glide` |
51+
| All at once | `pip install "aws-lambda-powertools[all]"` | All core extras |
52+
53+
### Local development
54+
55+
Powertools for AWS Lambda (Python) relies on the AWS SDK bundled in the Lambda runtime. When developing locally, install the SDK as a dev dependency:
56+
57+
```bash
58+
pip install "aws-lambda-powertools[aws-sdk]"
59+
```
60+
61+
### Alpha releases
62+
63+
We publish `prerelease` versions to PyPi for early feedback on unstable releases.
64+
65+
=== "pip"
66+
67+
```bash
68+
pip install --pre "aws-lambda-powertools"
69+
```
70+
71+
=== "poetry"
72+
73+
```bash
74+
poetry add --allow-prereleases "aws-lambda-powertools" --group dev
75+
```
76+
77+
=== "uv"
78+
79+
```bash
80+
uv add --prerelease allow "aws-lambda-powertools"
81+
```
82+
83+
## Lambda Layer
84+
85+
[Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html){target="_blank"} is a .zip file archive that contains pre-packaged dependencies. We compile and optimize all dependencies for both x86_64 and ARM architectures.
86+
87+
Replace `{region}` with your AWS region (e.g., `eu-west-1`) and `{python_version}` without the period (e.g., `python313` for Python 3.13).
88+
89+
| Architecture | Layer ARN |
90+
| ------------ | --------- |
91+
| x86_64 | `arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:27` |
92+
| ARM64 | `arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:27` |
93+
94+
### All regional Layer ARNs
95+
96+
=== "x86_64"
97+
--8<-- "docs/includes/_layer_homepage_x86.md"
98+
99+
=== "arm64"
100+
--8<-- "docs/includes/_layer_homepage_arm64.md"
101+
102+
??? tip "Want to inspect the Layer contents?"
103+
```bash
104+
aws lambda get-layer-version-by-arn --arn arn:aws:lambda:eu-west-1:017000801446:layer:AWSLambdaPowertoolsPythonV3-python313-x86_64:27 --region eu-west-1
105+
```
106+
The pre-signed URL will be in the `Location` key.
107+
108+
### Using SSM Parameter Store
109+
110+
We publish Layer ARNs to SSM Parameter Store for easier automation:
111+
112+
=== "CloudFormation"
113+
114+
```yaml
115+
MyFunction:
116+
Type: AWS::Lambda::Function
117+
Properties:
118+
Layers:
119+
- !Sub "{{resolve:ssm:/aws/service/powertools/python/${Architecture}/${PythonVersion}/latest}}"
120+
```
121+
122+
=== "Terraform"
123+
124+
```hcl
125+
data "aws_ssm_parameter" "powertools" {
126+
name = "/aws/service/powertools/python/x86_64/python3.13/latest"
127+
}
128+
129+
resource "aws_lambda_function" "example" {
130+
layers = [data.aws_ssm_parameter.powertools.value]
131+
}
132+
```
133+
134+
### Infrastructure as Code examples
135+
136+
=== "SAM"
137+
138+
```yaml hl_lines="11"
139+
--8<-- "examples/homepage/install/x86_64/sam.yaml"
140+
```
141+
142+
=== "CDK"
143+
144+
```python hl_lines="13 19"
145+
--8<-- "examples/homepage/install/x86_64/cdk_x86.py"
146+
```
147+
148+
=== "Serverless Framework"
149+
150+
```yaml hl_lines="13"
151+
--8<-- "examples/homepage/install/x86_64/serverless.yml"
152+
```
153+
154+
=== "Terraform"
155+
156+
```terraform hl_lines="9 37"
157+
--8<-- "examples/homepage/install/x86_64/terraform.tf"
158+
```
159+
160+
=== "Pulumi"
161+
162+
```python hl_lines="21-27"
163+
--8<-- "examples/homepage/install/x86_64/pulumi_x86.py"
164+
```
165+
166+
### AWS China regions
167+
168+
| Region | Architecture | Layer ARN |
169+
| ------ | ------------ | --------- |
170+
| cn-north-1 | x86_64 | `arn:aws-cn:lambda:cn-north-1:498634801083:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:27` |
171+
| cn-north-1 | ARM64 | `arn:aws-cn:lambda:cn-north-1:498634801083:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:27` |
172+
173+
### AWS GovCloud regions
174+
175+
| Region | Architecture | Layer ARN |
176+
| ------ | ------------ | --------- |
177+
| us-gov-east-1 | x86_64 | `arn:aws-us-gov:lambda:us-gov-east-1:165087284144:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:27` |
178+
| us-gov-east-1 | ARM64 | `arn:aws-us-gov:lambda:us-gov-east-1:165087284144:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:27` |
179+
| us-gov-west-1 | x86_64 | `arn:aws-us-gov:lambda:us-gov-west-1:165093116878:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:27` |
180+
| us-gov-west-1 | ARM64 | `arn:aws-us-gov:lambda:us-gov-west-1:165093116878:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:27` |
181+
182+
## Serverless Application Repository (SAR)
183+
184+
SAR deploys a CloudFormation stack with a copy of our Lambda Layer in your account. This allows you to use semantic versioning.
185+
186+
| Python | Architecture | SAR App |
187+
| ------ | ------------ | ------- |
188+
| 3.10 | x86_64 | [aws-lambda-powertools-python-layer-v3-python310-x86-64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python310-x86-64){target="_blank"} |
189+
| 3.11 | x86_64 | [aws-lambda-powertools-python-layer-v3-python311-x86-64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python311-x86-64){target="_blank"} |
190+
| 3.12 | x86_64 | [aws-lambda-powertools-python-layer-v3-python312-x86-64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python312-x86-64){target="_blank"} |
191+
| 3.13 | x86_64 | [aws-lambda-powertools-python-layer-v3-python313-x86-64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python313-x86-64){target="_blank"} |
192+
| 3.14 | x86_64 | [aws-lambda-powertools-python-layer-v3-python314-x86-64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python314-x86-64){target="_blank"} |
193+
| 3.10 | ARM64 | [aws-lambda-powertools-python-layer-v3-python310-arm64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python310-arm64){target="_blank"} |
194+
| 3.11 | ARM64 | [aws-lambda-powertools-python-layer-v3-python311-arm64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python311-arm64){target="_blank"} |
195+
| 3.12 | ARM64 | [aws-lambda-powertools-python-layer-v3-python312-arm64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python312-arm64){target="_blank"} |
196+
| 3.13 | ARM64 | [aws-lambda-powertools-python-layer-v3-python313-arm64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python313-arm64){target="_blank"} |
197+
| 3.14 | ARM64 | [aws-lambda-powertools-python-layer-v3-python314-arm64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python314-arm64){target="_blank"} |
198+
199+
??? note "SAR Infrastructure as Code examples"
200+
201+
=== "SAM"
202+
203+
```yaml hl_lines="6 9 10 17-19"
204+
--8<-- "examples/homepage/install/sar/sam.yaml"
205+
```
206+
207+
=== "CDK"
208+
209+
```python hl_lines="7 16-20 23-27"
210+
--8<-- "examples/homepage/install/sar/cdk_sar.py"
211+
```
212+
213+
=== "Terraform"
214+
215+
```terraform hl_lines="12-13 15-20 23-25 40"
216+
--8<-- "examples/homepage/install/sar/terraform.tf"
217+
```
218+
219+
??? question "Need least-privilege IAM permissions?"
220+
221+
```yaml hl_lines="21-52"
222+
--8<-- "examples/homepage/install/sar/scoped_down_iam.yaml"
223+
```

0 commit comments

Comments
 (0)