Skip to content

quickstart.md

Latest commit

 

History

History
239 lines (176 loc) · 6.56 KB

quickstart.md

File metadata and controls

239 lines (176 loc) · 6.56 KB
Raw

Quickstart

Create and deploy your first durable function using the AWS CLI. This guide covers TypeScript, Python, and Java.

!!! note "Adding all your dependencies to the deployment package"

This guide shows you how to package all your dependencies, including the Durable
Execution SDK, and deploy together with your custom code as a zip archive. This ensures
that you control the exact version of the Durable Execution SDK that your code uses. You
can create a durable function for quick testing purposes in the AWS Console, but then
the version of the SDK might be older and it might not contain the latest features and
optimizations.

Prerequisites

  • AWS CLI installed and configured with credentials

=== "TypeScript"

- Node.js 22+

=== "Python"

- Python 3.13+

=== "Java"

- Java 17+ and Maven 3.8+

Create the execution role

Create an IAM role that grants your function permission to perform checkpoint operations.

Save the following as trust-policy.json:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "lambda.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Create the role and attach the AWSLambdaBasicDurableExecutionRolePolicy managed policy:

# Replace durable-function-role with your preferred role name
aws iam create-role \
  --role-name durable-function-role \
  --assume-role-policy-document file://trust-policy.json

aws iam attach-role-policy \
  --role-name durable-function-role \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicDurableExecutionRolePolicy

Note the role ARN returned. You'll need it in the next step.

Write the durable function

=== "TypeScript"

Save as `index.mjs`

```typescript
--8<-- "examples/typescript/getting-started/quickstart.ts"
```

=== "Python"

Save as `lambda_function.py`

```python
--8<-- "examples/python/getting-started/quickstart.py"
```

=== "Java"

Save as `QuickstartFunction.java`

```java
--8<-- "examples/java/getting-started/quickstart.java"
```

The wait here is for 10 seconds just for an easy quick example, but it could as easily be 10 days without incurring extra compute.

Package and deploy

Replace 123456789012 with your AWS account ID and the role arn with that of the execution role you just created.

=== "TypeScript"

```console
mkdir my-function && cd my-function
npm init -y
npm install @aws/durable-execution-sdk-js
```

Save the function code above as `index.mjs`, then package and deploy:

```console
zip -r function.zip index.mjs node_modules/

aws lambda create-function \
  --function-name my-durable-function \
  --runtime nodejs22.x \
  --role arn:aws:iam::123456789012:role/durable-function-role \
  --handler index.handler \
  --zip-file fileb://function.zip \
  --durable-config '{"ExecutionTimeout": 900, "RetentionPeriodInDays": 1}'
```

=== "Python"

```console
mkdir -p package
pip install aws-durable-execution-sdk-python --target package/
cp lambda_function.py package/
cd package && zip -r ../function.zip . && cd ..

aws lambda create-function \
  --function-name my-durable-function \
  --runtime python3.14 \
  --role arn:aws:iam::123456789012:role/durable-function-role \
  --handler lambda_function.lambda_handler \
  --zip-file fileb://function.zip \
  --durable-config '{"ExecutionTimeout": 900, "RetentionPeriodInDays": 1}'
```

=== "Java"

Set up a Maven project with the following `pom.xml` dependencies:

```xml
<dependency>
    <groupId>software.amazon.lambda.durable</groupId>
    <artifactId>aws-durable-execution-sdk-java</artifactId>
    <version>1.1.0</version>
</dependency>
<dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-lambda-java-core</artifactId>
    <version>1.4.0</version>
</dependency>
```

Add the `maven-shade-plugin` to produce a fat jar with all dependencies bundled:

```xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.6.2</version>
    <configuration>
        <createDependencyReducedPom>false</createDependencyReducedPom>
    </configuration>
    <executions>
        <execution>
            <phase>package</phase>
            <goals><goal>shade</goal></goals>
        </execution>
    </executions>
</plugin>
```

Build the fat jar and deploy:

```console
mvn clean package -DskipTests

aws lambda create-function \
  --function-name my-durable-function \
  --runtime java21 \
  --role arn:aws:iam::123456789012:role/durable-function-role \
  --handler QuickstartFunction::handleRequest \
  --zip-file fileb://target/*.jar \
  --durable-config '{"ExecutionTimeout": 900, "RetentionPeriodInDays": 1}'
```

Publish a version

You must invoke a durable functions with a published version or alias to ensure deterministic replay.

For quick testing here in the Quickstart we can just invoke the durable function with $LATEST. Note that you should NOT do this for production workloads.

Be sure to publish a version if this is for production. Invoking $LATEST directly is not supported for production workloads.

aws lambda publish-version --function-name my-durable-function

Note the version number in the returned ARN (for example, :1).

Invoke

For synchronous invocation:

aws lambda invoke \
  --function-name 'my-durable-function:$LATEST' \
  --cli-binary-format raw-in-base64-out \
  --payload '{}' \
  response.json

cat response.json

The function runs step-1, then pauses for 10 seconds without consuming compute. After the wait, it resumes and returns the result.

Clean up

See delete durable functions to clean up your function and IAM role.

Next steps