Skip to content

docs(homepage): revamp install UX & share how we build Lambda Layer #1978

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Mar 6, 2023
Merged

docs(homepage): revamp install UX & share how we build Lambda Layer #1978

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d10c5ec
docs(homepage): use new powertools description
heitorlessa Mar 3, 2023
d8b9369
docs(install): revamp UX for install and local development
heitorlessa Mar 3, 2023
299e091
docs(install): make all deps in bold
heitorlessa Mar 3, 2023
233e65b
docs(install): explain how we build our layers along with links
heitorlessa Mar 3, 2023
4ec6738
docs(layer): make aws cli layer command to be more visible
heitorlessa Mar 3, 2023
cf5f71b
docs: shorten local development wording, new banner for those new to …
heitorlessa Mar 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 35 additions & 38 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: AWS Lambda Powertools for Python

<!-- markdownlint-disable MD043 MD013 -->

A suite of utilities for AWS Lambda functions to ease adopting best practices such as tracing, structured logging, custom metrics, idempotency, batching, [**and more**](#features).
Powertools is a developer toolkit to implement Serverless best practices and increase developer velocity.

???+ tip
Powertools is also available for [Java](https://awslabs.github.io/aws-lambda-powertools-java/){target="_blank"}, [TypeScript](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/){target="_blank"}, and [.NET](https://awslabs.github.io/aws-lambda-powertools-dotnet/){target="_blank"}
Expand All @@ -24,41 +24,52 @@ A suite of utilities for AWS Lambda functions to ease adopting best practices su

## Install

Powertools is available in the following formats:
You can install Powertools using one of the following options:

* **Lambda Layer (x86_64)**: [**arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV2:23**](#){: .copyMe}:clipboard:
* **Lambda Layer (arm64)**: [**arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV2-Arm64:23**](#){: .copyMe}:clipboard:
* **PyPi**: **`pip install "aws-lambda-powertools"`**
* **Pip**: **[`pip install "aws-lambda-powertools"`](#){: .copyMe}:clipboard:**

???+ info "Some utilities require additional dependencies"
You can stop reading if you're using Lambda Layer.

[Tracer](./core/tracer.md){target="_blank"}, [Validation](./utilities/validation.md){target="_blank"} and [Parser](./utilities/parser.md){target="_blank"} require additional dependencies. If you prefer to install all of them, use `pip install "aws-lambda-powertools[all]"`.
??? question "Using Pip? You might need to install additional dependencies."
[**Tracer**](./core/tracer.md){target="_blank"}, [**Validation**](./utilities/validation.md){target="_blank"} and [**Parser**](./utilities/parser.md){target="_blank"} require additional dependencies. If you prefer to install all of them, use [**`pip install "aws-lambda-powertools[all]"`**](#){: .copyMe}:clipboard:.

For example:

* [Tracer](./core/tracer.md#install){target="_blank"}: **`pip install "aws-lambda-powertools[tracer]"`**
* [Validation](./utilities/validation.md#install){target="_blank"}: **`pip install "aws-lambda-powertools[validation]"`**
* [Parser](./utilities/parser.md#install){target="_blank"}: **`pip install "aws-lambda-powertools[parser]"`**
* [Tracer](./core/tracer.md#install){target="_blank"} and [Parser](./utilities/parser.md#install){target="_blank"}: **`pip install "aws-lambda-powertools[tracer,parser]"`**
* **Tracer**: **[`pip install "aws-lambda-powertools[tracer]"`](#){: .copyMe}:clipboard:**
* **Validation**: **[`pip install "aws-lambda-powertools[validation]"`](#){: .copyMe}:clipboard:**
* **Parser**: **[`pip install "aws-lambda-powertools[parser]"`](#){: .copyMe}:clipboard:**
* **Tracer** and **Parser**: **[`pip install "aws-lambda-powertools[tracer,parser]"`](#){: .copyMe}:clipboard:**

### Local development

Powertools relies on the AWS SDK bundled in the Lambda runtime. This helps us achieve an optimal package size and initialization.
!!! info "Using Powertools via Lambda Layer? Simply add [**`"aws-lambda-powertools[all]"`**](#){: .copyMe}:clipboard: as a development dependency."

Powertools relies on the [AWS SDK bundled in the Lambda runtime](https://docs.aws.amazon.com/lambda/latest/dg/lambda-python.html){target="_blank"}. This helps us achieve an optimal package size and initialization. However, when developing locally, you need to install AWS SDK as a development dependency (not as a production dependency):

* **Pip**: [**`pip install "aws-lambda-powertools[aws-sdk]"`**](#){: .copyMe}:clipboard:
* **Poetry**: [**`poetry add "aws-lambda-powertools[aws-sdk]" --group dev`**](#){: .copyMe}:clipboard:
* **Pipenv**: [**`pipenv install --dev "aws-lambda-powertools[aws-sdk]"`**](#){: .copyMe}:clipboard:

??? question "Why is that necessary?"
Powertools relies on the AWS SDK being available to use in the target runtime (AWS Lambda).

This means you need to add AWS SDK as a development dependency (not as a production dependency).
As a result, it affects your favorite IDE in terms of code auto-completion, or running your tests suite locally with no Lambda emulation such as [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html){target="_blank"}.

* **Pip**: `pip install "aws-lambda-powertools[aws-sdk]"`
* **Poetry**: `poetry add "aws-lambda-powertools[aws-sdk]" --group dev`
* **Pipenv**: `pipenv install --dev "aws-lambda-powertools[aws-sdk]"`
**A word about dependency resolution**

???+ note "Local emulation"
If you're running your code locally with [AWS SAM CLI](https://github.com/aws/aws-sam-cli){target="_blank"}, and not with your Python/IDE interpreter directly, this is not necessary. SAM CLI already brings the AWS SDK in its emulation image.
In this context, `[aws-sdk]` is an alias to the `boto3` package. Due to dependency resolution, it'll either install:

* **(A)** the SDK version available in [Lambda runtime](https://docs.aws.amazon.com/lambda/latest/dg/lambda-python.html){target="_blank"}
* **(B)** a more up-to-date version if another package you use also depends on `boto3`, for example [Powertools Tracer](core/tracer.md){target="_blank"}

### Lambda Layer

???+ warning "As of now, Container Image deployment (OCI) or inline Lambda functions do not support Lambda Layers."

[Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html){target="_blank"} is a .zip file archive that can contain additional code, pre-packaged dependencies, data, or configuration files. Layers promote code sharing and separation of responsibilities so that you can iterate faster on writing business logic.

For our Layers, we compile and optimize [all dependencies](https://github.com/awslabs/aws-lambda-powertools-python/blob/develop/pyproject.toml#L98){target="_blank"}, and [remove duplicate dependencies already available in the Lambda runtime](https://github.com/awslabs/cdk-aws-lambda-powertools-layer/blob/main/layer/Python/Dockerfile#L36){target="_blank"} to achieve the most optimal size.

You can include Powertools Lambda Layer using [AWS Lambda Console](https://docs.aws.amazon.com/lambda/latest/dg/invocation-layers.html#invocation-layers-using){target="_blank"}, or your preferred deployment framework.

??? note "Note: Click to expand and copy any regional Lambda Layer ARN"
Expand Down Expand Up @@ -271,16 +282,6 @@ You can include Powertools Lambda Layer using [AWS Lambda Console](https://docs.
? Do you want to edit the local lambda function now? No
```

=== "Get the Layer .zip contents"

Change {region} to your AWS region, e.g. `eu-west-1`

```bash title="AWS CLI"
aws lambda get-layer-version-by-arn --arn arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV2:23 --region {region}
```

The pre-signed URL to download this Lambda Layer will be within `Location` key.

=== "arm64"

=== "SAM"
Expand Down Expand Up @@ -439,18 +440,14 @@ You can include Powertools Lambda Layer using [AWS Lambda Console](https://docs.
? Do you want to edit the local lambda function now? No
```

=== "Get the Layer .zip contents"
Change {region} to your AWS region, e.g. `eu-west-1`
??? question "Want to inspect the contents of the Layer?"
Change {region} to your AWS region, e.g. `eu-west-1`

```bash title="AWS CLI"
aws lambda get-layer-version-by-arn --arn arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV2-Arm64:23 --region {region}
```

The pre-signed URL to download this Lambda Layer will be within `Location` key.

???+ warning "Warning: Limitations"
```bash title="AWS CLI"
aws lambda get-layer-version-by-arn --arn arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV2:23 --region {region}
```

Container Image deployment (OCI) or inline Lambda functions do not support Lambda Layers.
The pre-signed URL to download this Lambda Layer will be within `Location` key.

#### SAR

Expand Down