DEV Community: Thomas Taylor

API Key Authentication with API Gateway using AWS CDK

Thomas Taylor — Sun, 30 Jun 2024 21:43:52 +0000

API key authentication is a common method for securing APIs by controlling access to them. It's important to note that API keys are great for authentication, but further development should be made to ensure proper authorization at the business level. API keys do not ensure that the correct permissions are being enforced, only that the user has access to the API.

Regardless, let's get started! In this post, we're going to touch on a few services:

API Gateway with Proxy Integration
Lambda Authorizer
AWS CDK

Get started

Conceptually, the flow of our application will look like this:

Client makes a request to API Gateway with API key
The lambda authorizer determines if the API key is valid
If the API key is valid, the policy is generated and the request is allowed to pass through to the lambda function
If the API key is invalid, the request is denied
The lambda function is invoked and returns a response

Set up the CDK project

Firstly, let's create the CDK project. I will choose TypeScript as the language, but you can choose any language you prefer. Please refer to the AWS CDK hello world documentation for other supported languages.

cdk init --language typescript

Next, let's install the necessary dependencies:

npm i

In addition, install the @types/aws-lambda package:

npm i @types/aws-lambda

Let's start by finding the primary stack file which is located under the lib directory. In my case, it's lib/api-key-gateway-stack.ts.

Edit the CDK stack

Luckily, in a few lines of code, we can spin up a full-featured API Gateway with a lambda handler using the AWS CDK.

import { Duration, Stack, StackProps } from "aws-cdk-lib";
import { Construct } from "constructs";
import { Runtime } from "aws-cdk-lib/aws-lambda";
import {
  LambdaRestApi,
  TokenAuthorizer,
  AuthorizationType,
} from "aws-cdk-lib/aws-apigateway";
import { NodejsFunction } from "aws-cdk-lib/aws-lambda-nodejs";

export class ApiKeyGatewayStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    const fn = new NodejsFunction(this, "server", {
      entry: "bin/server.ts",
      handler: "handler",
      runtime: Runtime.NODEJS_20_X,
      timeout: Duration.minutes(1),
    });
    const auth = new NodejsFunction(this, "auth", {
      entry: "bin/auth.ts",
      handler: "handler",
      runtime: Runtime.NODEJS_20_X,
      timeout: Duration.seconds(10),
    });
    const api = new LambdaRestApi(this, "api", {
      handler: fn,
      defaultMethodOptions: {
        authorizationType: AuthorizationType.CUSTOM,
        authorizer: new TokenAuthorizer(this, "authorizer", {
          handler: auth,
        }),
      },
    });
  }
}

Let's break down the code:

The first construct, NodejsFunction, is a node lambda function that will serve as our primary handler.
The second construct, another NodejsFunction, is a lambda authorizer that will be used to validate the API key.
The third construct, LambdaRestApi, is the API Gateway that includes the first construct wired as the proxy integration and the second construct as the authorizer.

Create the lambda handler

Located at bin/server.ts, we will create a simplistic lambda function that returns Hello, World!.

import { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";

export const handler = async (
  event: APIGatewayProxyEvent,
): Promise<APIGatewayProxyResult> => {
  return {
    statusCode: 200,
    body: JSON.stringify({ message: "Hello, World!" }),
  };
};

Create the lambda authorizer

Next, let's create the lambda authorizer located at bin/auth.ts. This lambda function will be responsible for validating the API key.

To keep it simple, we will hardcode the API key to Bearer abc123.

import { APIGatewayTokenAuthorizerEvent, Handler } from "aws-lambda";

export const handler: Handler = async (
  event: APIGatewayTokenAuthorizerEvent,
) => {
  const effect = event.authorizationToken == "Bearer abc123" ? "Allow" : "Deny";
  return {
    principalId: "abc123",
    policyDocument: {
      Version: "2012-10-17",
      Statement: [
        {
          Action: "execute-api:Invoke",
          Effect: effect,
          Resource: [event.methodArn],
        },
      ],
    },
  };
};

Deploy the stack

Now that we have our stack and lambda handlers setup, let's deploy the stack!

npx cdk deploy

Once the deployment is complete, you should see the API Gateway endpoint as an output.

Do you wish to deploy these changes (y/n)? y
ApiKeyGatewayStack: deploying... [1/1]
ApiKeyGatewayStack: creating CloudFormation changeset...

 ✅  ApiKeyGatewayStack

✨  Deployment time: 45.34s

Outputs:
ApiKeyGatewayStack.apiEndpoint9349E63C = https://x2s65m7xyd.execute-api.us-east-1.amazonaws.com/prod/
Stack ARN:
arn:aws:cloudformation:us-east-1:123456789012:stack/ApiKeyGatewayStack/0ca225a0-3727-11ef-ae64-0affd17461c9
✨  Total time: 117.33s

Test the API

Let's use curl to test the API without the API key.

curl https://<id>.execute-api.us-east-1.amazonaws.com/prod/

Output:

{"message":"Unauthorized"}

As expected, we received an unauthorized response. Now, let's test the API with the API key.

curl https://x2s65m7xyd.execute-api.us-east-1.amazonaws.com/prod/ \
    -H "Authorization: Bearer abc123"

Output:

{"message":"Hello, World!"}

Great! We have successfully created an API Gateway with a lambda authorizer using the AWS CDK. At this point, you may choose to extend the Lambda Authorizer to query another data source like DynamoDB that stores API keys.

Clean up

Lastly, let's clean up our AWS resources by destroying the stack:

npx cdk destroy

That's it! You successfully created an API Gateway with a lambda authorizer using the AWS CDK.

Networking to a 5th Grader in 256 words.

Thomas Taylor — Sun, 16 Jun 2024 14:39:13 +0000

This is a submission for DEV Computer Science Challenge v24.06.12: One Byte Explainer.

Explainer

Imagine you want to send a hand-written invite to a buddy who lives far away to your birthday party. In order to send this invite, you would need to use a postal service. Sending data through the internet is like using a postal service.

Firstly, you would write your letter and put it in an envelope (which is like creating a message on your computer). Then, you write your friend's home address on the envelope which tells the postal service the destination (which is like an IP address for the internet).

Next, you place the envelope in the mailbox (which is similar to using your Wi-Fi or home internet to send a message). Now, it's up to the postal service to deliver your mail. The postal workers are like internet service providers who move your mail from one place to another using trucks and post offices. These trucks and post offices are like routers and servers on the internet.

At each post office along the way, your mail might be sorted and sent to another post office. As time goes on, your mail gets closer and closer to your buddy's house. This is similar to how data travels from servers and routers on the internet.

Eventually, your mail is delivered to your friend's house. When your friend opens the envelope, it's like their computer receiving and showing the message you sent.

So, sending messages and pictures on the internet is a lot like sending letters through the postal service, but with computers and special addresses instead.

A step-by-step guide on how to use the Amazon Bedrock Converse API

Thomas Taylor — Sun, 02 Jun 2024 17:38:56 +0000

On May 30th, 2024, Amazon announced the release of the Bedrock Converse API. This API is designed to provide a consistent experience for "conversing" with Amazon Bedrock models.

The API supports:

Conversations with multiple turns
System messages
Tool use
Image and text input

In this post, we'll walk through how to use the Amazon Bedrock Converse API with the Claude Haiku foundational model.

Please keep in mind that not all foundational models may support all the features of the Converse API. For more details per model, see the Amazon Bedrock documentation.

Getting started

To get started, let's install the boto3 package.

pip install boto3

Next, we'll create a new Python script and import the necessary dependencies.

import boto3

client = boto3.client("bedrock-runtime")

Step 1 - Starting a conversation

To start off simple, let's send a single message to Claude.

import boto3

client = boto3.client("bedrock-runtime")

messages = [{"role": "user", "content": [{"text": "What is your name?"}]}]

response = client.converse(
    modelId="anthropic.claude-3-haiku-20240307-v1:0",
    messages=messages,
)

print(response)

The response is a dictionary containing the response and other metadata information from the API. For more information regarding the output, please refer to the Amazon Bedrock documentation.

For the purposes of this post, I'll print the response as JSON.

{
  "ResponseMetadata": {
    "RequestId": "6984dcf2-c6aa-4000-a3d6-22e34a43df12",
    "HTTPStatusCode": 200,
    "HTTPHeaders": {
      "date": "Sun, 02 Jun 2024 14:54:08 GMT",
      "content-type": "application/json",
      "content-length": "222",
      "connection": "keep-alive",
      "x-amzn-requestid": "6984dcf2-c6aa-4000-a3d6-22e34a43df12"
    },
    "RetryAttempts": 0
  },
  "output": {
    "message": {
      "role": "assistant",
      "content": [
        {
          "text": "My name is Claude. It's nice to meet you!"
        }
      ]
    }
  },
  "stopReason": "end_turn",
  "usage": {
    "inputTokens": 12,
    "outputTokens": 15,
    "totalTokens": 27
  },
  "metrics": {
    "latencyMs": 560
  }
}

To retrieve the contents of the message, we can access the output key in the response.

import boto3

client = boto3.client("bedrock-runtime")

messages = [{"role": "user", "content": [{"text": "What is your name?"}]}]

response = client.converse(
    modelId="anthropic.claude-3-haiku-20240307-v1:0",
    messages=messages,
)

ai_message = response["output"]["message"]
output_text = ai_message["content"][0]["text"]
print(output_text)

Output:

My name is Claude. It's nice to meet you!

Step 2 - Continuing a conversation

Let's continue the conversation by appending the AI's message to the original list of messages. This will allow us to have a multi-turn conversation.

import boto3

client = boto3.client("bedrock-runtime")

messages = [{"role": "user", "content": [{"text": "What is your name?"}]}]

response = client.converse(
    modelId="anthropic.claude-3-haiku-20240307-v1:0",
    messages=messages,
)

ai_message = response["output"]["message"]
messages.append(ai_message)

# Let's ask another question

messages.append({"role": "user", "content": [{"text": "Can you help me?"}]})
response = client.converse(
    modelId="anthropic.claude-3-haiku-20240307-v1:0",
    messages=messages,
)

print(response["output"]["message"]["content"][0]["text"])

Output:

Yes, I'd be happy to try and help you with whatever you need assistance with. What can I help you with?

Step 3 - Using images

The Amazon Bedrock Converse API supports images as input. Let's send an image to Claude and see how it responds. I'll download an image of a cat from Wikipedia and send it to claude.

For this example, I used the requests library to download the image. If you don't have it installed, you can install it using pip install requests.

pip install requests

import boto3
import requests

client = boto3.client("bedrock-runtime")

messages = [{"role": "user", "content": [{"text": "What is your name?"}]}]

response = client.converse(
    modelId="anthropic.claude-3-haiku-20240307-v1:0",
    messages=messages,
)

ai_message = response["output"]["message"]
messages.append(ai_message)

messages.append({"role": "user", "content": [{"text": "Can you help me?"}]})
response = client.converse(
    modelId="anthropic.claude-3-haiku-20240307-v1:0",
    messages=messages,
)
ai_message = response["output"]["message"]
messages.append(ai_message)

image_bytes = requests.get(
    "https://upload.wikimedia.org/wikipedia/commons/4/4d/Cat_November_2010-1a.jpg"
).content
messages.append(
    {
        "role": "user",
        "content": [
            {"text": "What is in this image?"},
            {"image": {"format": "jpeg", "source": {"bytes": image_bytes}}},
        ],
    }
)
response = client.converse(
    modelId="anthropic.claude-3-haiku-20240307-v1:0",
    messages=messages,
)

ai_message = response["output"]["message"]
print(ai_message)

Output:

{
  "role": "assistant",
  "content": [
    {
      "text": "The image shows a domestic cat. The cat appears to be a tabby cat with a striped coat pattern. The cat is sitting upright and its green eyes are clearly visible, with a focused and alert expression. The background suggests an outdoor, snowy environment, with some blurred branches or vegetation visible behind the cat."
    }
  ]
}

As you can see, the AI was able to identify the image as a cat and provide a detailed description of the image within a conversational context.

Step 4 - Using a single tool

For this section, let's start a new conversation with Claude and provide tools it can use.

import boto3

client = boto3.client("bedrock-runtime")

tools = [
    {
        "toolSpec": {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "inputSchema": {
                "json": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g. San Francisco, CA",
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"],
                            "description": "The unit of temperature, either 'celsius' or 'fahrenheit'",
                        },
                    },
                    "required": ["location"],
                }
            },
        }
    },
]
messages = [
    {
        "role": "user",
        "content": [{"text": "What is the weather like right now in New York?"}],
    }
]
response = client.converse(
    modelId="anthropic.claude-3-haiku-20240307-v1:0",
    messages=messages,
    toolConfig={"tools": tools},
)

print(response["output"])

Output:

{
  "message": {
    "role": "assistant",
    "content": [
      {
        "text": "Okay, let me check the current weather for New York:"
      },
      {
        "toolUse": {
          "toolUseId": "tooluse_rRwaOoldTeiRiDZhTadP0A",
          "name": "get_weather",
          "input": {
            "location": "New York, NY",
            "unit": "fahrenheit"
          }
        }
      }
    ]
  }
}

The output includes a toolUse object that indicates to us, the developers, that the AI is using the get_weather tool to fetch the current weather in New York. We must now fulfill the tool request by responding with the weather information.

But first, let's build a simplistic router that can handle the tool request and respond with the weather information.

def get_weather(location: str, unit: str = "fahrenheit") -> dict:
    return {"temperature": "78"}

def tool_router(tool_name, input):
    match tool_name:
        case "get_weather":
            return get_weather(input["location"], input.get("unit", "fahrenheit"))
        case _:
            raise ValueError(f"Unknown tool: {tool_name}")

Now, let's update the code to handle the tool request and respond with the weather information.

import boto3

def get_weather(location: str, unit: str = "fahrenheit") -> dict:
    return {"temperature": "78"}

def tool_router(tool_name, input):
    match tool_name:
        case "get_weather":
            return get_weather(input["location"], input.get("unit", "fahrenheit"))
        case _:
            raise ValueError(f"Unknown tool: {tool_name}")

client = boto3.client("bedrock-runtime")

tools = [
    {
        "toolSpec": {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "inputSchema": {
                "json": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g. San Francisco, CA",
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"],
                            "description": "The unit of temperature, either 'celsius' or 'fahrenheit'",
                        },
                    },
                    "required": ["location"],
                }
            },
        }
    },
]
messages = [
    {
        "role": "user",
        "content": [{"text": "What is the weather like right now in New York?"}],
    }
]
response = client.converse(
    modelId="anthropic.claude-3-haiku-20240307-v1:0",
    messages=messages,
    toolConfig={"tools": tools},
)

ai_message = response["output"]["message"]
messages.append(ai_message)

if response["stopReason"] == "tool_use":
    contents = response["output"]["message"]["content"]
    for c in contents:
        if "toolUse" not in c:
            continue

        tool_use = c["toolUse"]
        tool_id = tool_use["toolUseId"]
        tool_name = tool_use["name"]
        input = tool_use["input"]

        tool_result = {"toolUseId": tool_id}
        try:
            output = tool_router(tool_name, input)
            if isinstance(output, dict):
                tool_result["content"] = [{"json": output}]
            elif isinstance(output, str):
                tool_result["content"] = [{"text": output}]
            # Add more cases, such as images, if needed
            else:
                raise ValueError(f"Unsupported output type: {type(output)}")
        except Exception as e:
            tool_result["content"] = [{"text": f"An unknown error occurred: {str(e)}"}]
            tool_result["status"] = "error"

        message = {"role": "user", "content": [{"toolResult": tool_result}]}
        messages.append(message)

    response = client.converse(
        modelId="anthropic.claude-3-haiku-20240307-v1:0",
        messages=messages,
        toolConfig={"tools": tools},
    )

print(response["output"])

Output:

{
  "message": {
    "role": "assistant",
    "content": [
      {
        "text": "According to the weather data, the current temperature in New York, NY is 78 degrees Fahrenheit."
      }
    ]
  }
}

Great! We have successfully responded to the AI tool request and provided the weather information for New York.

Step 5 - Using multiple tools

For reference, I'm adapting the Anthropic AI Tool examples from their documentation to the Bedrock Converse API.

In the previous example, we only used one tool to fetch the weather information. However, we can use multiple tools in a single conversation.

Let's add another tool to the conversation to fetch the current time and introduce a loop to handle multiple tool requests.

import boto3

def get_weather(location: str, unit: str = "fahrenheit") -> dict:
    return {"temperature": "78"}

def get_time(timezone: str) -> str:
    return "12:00PM"

def tool_router(tool_name, input):
    match tool_name:
        case "get_weather":
            return get_weather(input["location"], input.get("unit", "fahrenheit"))
        case "get_time":
            return get_time(input["timezone"])
        case _:
            raise ValueError(f"Unknown tool: {tool_name}")

client = boto3.client("bedrock-runtime")

tools = [
    {
        "toolSpec": {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "inputSchema": {
                "json": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g. San Francisco, CA",
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"],
                            "description": "The unit of temperature, either 'celsius' or 'fahrenheit'",
                        },
                    },
                    "required": ["location"],
                }
            },
        }
    },
    {
        "toolSpec": {
            "name": "get_time",
            "description": "Get the current time in a given timezone",
            "inputSchema": {
                "json": {
                    "type": "object",
                    "properties": {
                        "timezone": {
                            "type": "string",
                            "description": "The IANA time zone name, e.g. America/Los_Angeles",
                        }
                    },
                    "required": ["timezone"],
                }
            },
        }
    },
]
messages = [
    {
        "role": "user",
        "content": [
            {
                "text": "What is the weather like right now in New York and what time is it there?"
            }
        ],
    }
]
response = client.converse(
    modelId="anthropic.claude-3-haiku-20240307-v1:0",
    messages=messages,
    toolConfig={"tools": tools},
)

ai_message = response["output"]["message"]
messages.append(ai_message)

tool_use_count = 0
while response["stopReason"] == "tool_use":
    if response["stopReason"] == "tool_use":
        contents = response["output"]["message"]["content"]
        for c in contents:
            if "toolUse" not in c:
                continue

            tool_use = c["toolUse"]
            tool_id = tool_use["toolUseId"]
            tool_name = tool_use["name"]
            input = tool_use["input"]

            tool_result = {"toolUseId": tool_id}
            try:
                output = tool_router(tool_name, input)
                if isinstance(output, dict):
                    tool_result["content"] = [{"json": output}]
                elif isinstance(output, str):
                    tool_result["content"] = [{"text": output}]
                # Add more cases such as images if needed
                else:
                    raise ValueError(f"Unsupported output type: {type(output)}")
            except Exception as e:
                tool_result["content"] = [
                    {"text": f"An unknown error occurred: {str(e)}"}
                ]
                tool_result["status"] = "error"

            message = {"role": "user", "content": [{"toolResult": tool_result}]}
            messages.append(message)

        response = client.converse(
            modelId="anthropic.claude-3-haiku-20240307-v1:0",
            messages=messages,
            toolConfig={"tools": tools},
        )
        ai_message = response["output"]["message"]
        messages.append(ai_message)
        tool_use_count += 1

print(tool_use_count)
print(response["output"])

Output:

{
  "message": {
    "role": "assistant",
    "content": [
      {
        "text": "The current time in New York is 12:00 PM.\n\nSo in summary, the weather in New York right now is 78 degrees Celsius, and the time is 12:00 PM."
      }
    ]
  }
}

Tool use count: 2

We have successfully responded to the AI's tool requests and provided the weather and time information for New York.

Conclusion

In this post, we learned how to use the Amazon Bedrock Converse API to augment converations with AI models. Not only did we leverage text and images, but we also used tools to simulate fetching external data.

The Amazon Bedrock Converse API is a powerful tool that can be used to build conversational AI applications!

Multiple operations in a single DynamoDB update expression

Thomas Taylor — Sun, 28 Apr 2024 17:20:20 +0000

DynamoDB supports an UpdateItem operation that modifies an existing or creates a new item. The UpdateItem accepts an UpdateExpression that dictates which operations will occur on the specified item.

In this post, we'll explore how to perform multiple operations including within a clause/keyword and with multiple clauses/keywords.

What is an update expression

An update expression supports four keywords:

SET (modify or add item attributes)
REMOVE (deleting attributes from an item)
ADD (updating numbers and sets)
DELETE (removing elements from a set)

The syntax for an update expression is as follows:

update-expression ::=
    [ SET action [, action] ... ]
    [ REMOVE action [, action] ...]
    [ ADD action [, action] ... ]
    [ DELETE action [, action] ...]

As you can view, DynamoDB supports four main clauses that begin with one of the specified operations.

For a detailed explanation of update expressions, please refer to the AWS documentation.

For demonstration purposes, I'm going to create a DynamoDB table named books with a number hash key named id.

aws dynamodb create-table \
  --table-name books \
  --attribute-definitions AttributeName=id,AttributeType=N \
  --key-schema AttributeName=id,KeyType=HASH \
  --provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5

I'll also add an item to the table:

{
  "id": {
    "N": "1"
  },
  "title": {
    "S": "Iliad"
  },
  "author": {
    "S": "Homer"
  },
  "genre": {
    "S": "Epic Poetry"
  },
  "publication_year": {
    "N": "1488"
  }
}

aws dynamodb put-item \
    --table-name books \
    --item file://book.json

How to specify a single keyword in DynamoDB update expression

Let's showcase a basic use-case of adding an element to an existing item:

aws dynamodb update-item \
    --table-name books \
    --key '{"id":{"N":"1"}}' \
    --update-expression "SET category = :c" \
    --expression-attribute-values '{":c":{"S":"Poem"}}'

Now the item has a new category attribute:

aws dynamodb get-item \
    --table-name books \
    --key '{"id":{"N":"1"}}' \
    --projection-expression "category"

Output:

{
  "Item": {
    "category": {
      "S": "Poem"
    }
  }
}

How to specify a single keyword with multiple actions in DynamoDB update expression

To showcase mutliple SET operations in a single DynamoDB update expression, we'll use a comma (,) to separate them.

In the following example, we're changing the category from poem -> poetry and adding a new element named genre.

aws dynamodb update-item \
    --table-name books \
    --key '{"id":{"N":"1"}}' \
    --update-expression "SET category = :c, genre = :g" \
    --expression-attribute-values '{":c":{"S":"poetry"}, ":g":{"S":"Epic poetry"}}' \
    --return-values UPDATED_NEW

Output:

{
  "Attributes": {
    "category": {
      "S": "poetry"
    },
    "genre": {
      "S": "Epic poetry"
    }
  }
}

As you see, the update-expression includes a comma between the two operations:

SET category = :c, genre = :g

How to specify multiple keywords with multiple actios in DynamoDB update expression

Lastly, let's showcase leveraging multiple keywords with their respective actions.

We're going to perform the following:

Set a new string attribute named product_category with a value of poem
Remove the category attribute
Add 1 to existing checkout_total number or initialize it with the number value of 1
Add Trojan War to existing subjects set or initialize it with the first index being string value of Trojan War

aws dynamodb update-item \
    --table-name books \
    --key '{"id":{"N":"1"}}' \
    --update-expression "SET #pc = :pc REMOVE #c ADD #ct :inc, #s :s" \
    --expression-attribute-names '{"#s":"subjects","#pc":"product_category","#c":"category","#ct":"checkout_total"}' \
    --expression-attribute-values '{":s":{"SS":["Trojan War"]},":pc":{"S":"poem"},":inc":{"N":"1"}}' \
    --return-values UPDATED_NEW

Output:

{
  "Attributes": {
    "checkout_total": {
      "N": "1"
    },
    "subjects": {
      "SS": [
        "Trojan War"
      ]
    },
    "product_category": {
      "S": "poem"
    }
  }
}

It's important to note that because the ADD operation will continue incrementing and the SET data structure doesn't allow duplicates, we can rerun the same operation and checkout_total will increase by 1.

For readability, let's substitute the expression-attribute-names and expression-attribute-values back into the update-expression:

SET product_category = poem REMOVE category ADD checkout_total 1, subjects ["Trojan War"]

To summarize, using mutliple clauses in a DynamoDB UpdateExpression is supported by simply separating the clauses by keywords.

If you want to perform multiple operations using the same clause, use a comma (,) to separate them.

Detecting and redacting PII using Amazon Bedrock

Thomas Taylor — Tue, 23 Apr 2024 04:32:25 +0000

Typically, AWS recommends leveraging an existing service offering such as Amazon Comprehend to detect and redact PII. However, this post explores an alternative solution using Amazon Bedrock.

This is possible using the Claude, Anthropic's large langauge model, and their publicly available prompt library. In our case, we'll leverage the PII purifier prompt that is maintained by their prompt engineers.

How to extract PII using Amazon Bedrock in Python

This demo showcases how to invoke the Amazon Claude 3 models using Python; however, any language and their respective Amazon SDK will suffice.

Install boto3

Firstly, let's install the AWS Python SDK, boto3.

pip install boto3

Instantiate a client

Ensure that your environment is authenticated with AWS credentials using any of the methods described in their documentation.

Instantiate the bedrock runtime client like so:

import boto3

bedrock_runtime = boto3.client("bedrock-runtime")

Invoke the Claude model

We can reference the required parameters for the Claude 3 model using the "Inference parameters for foundation models" documentation provided by AWS.

In Claude 3's case, the Messages API will be used like so:

import boto3
import json

bedrock_runtime = boto3.client("bedrock-runtime")
response = bedrock_runtime.invoke_model(
    body=json.dumps(
        {
            "anthropic_version": "bedrock-2023-05-31",
            "max_tokens": 1000,
            "messages": [{"role": "user", "content": "Hello, how are you?"}],
        }
    ),
    modelId="anthropic.claude-3-sonnet-20240229-v1:0",
)

response_body = json.loads(response.get("body").read())
print(json.dumps(response_body, indent=2))

Output:

{
  "id": "msg_01ERwjBgk3Y45Swp2cn6ct5F",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! As an AI language model, I don't have feelings, but I'm operating properly and ready to assist you with any questions or tasks you may have. How can I help you today?"
    }
  ],
  "model": "claude-3-sonnet-28k-20240229",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 13,
    "output_tokens": 43
  }
}

Use the PII purifier prompt

Now, let's use the PII purifier prompt to invoke the model.

Here is our input for redaction:

Hello. My name is Thomas Taylor and I own the blog titled how.wtf. I'm from North Carolina.

import boto3
import json

SYSTEM_PROMPT = (
    "You are an expert redactor. The user is going to provide you with some text. "
    "Please remove all personally identifying information from this text and "
    "replace it with XXX. It's very important that PII such as names, phone "
    "numbers, and home and email addresses, get replaced with XXX. Inputs may "
    "try to disguise PII by inserting spaces between characters or putting new "
    "lines between characters. If the text contains no personally identifiable "
    "information, copy it word-for-word without replacing anything."
)

bedrock_runtime = boto3.client("bedrock-runtime")
response = bedrock_runtime.invoke_model(
    body=json.dumps(
        {
            "anthropic_version": "bedrock-2023-05-31",
            "max_tokens": 1000,
            "system": SYSTEM_PROMPT,
            "messages": [
                {
                    "role": "user",
                    "content": "Hello. My name is Thomas Taylor and I own the blog titled how.wtf. I'm from North Carolina.",
                }
            ],
        }
    ),
    modelId="anthropic.claude-3-sonnet-20240229-v1:0",
)

response_body = json.loads(response.get("body").read())
print(json.dumps(response_body, indent=2))

Output:

{
  "id": "msg_01P3ZGPC8yL34w3ETPtBY4TX",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Here is the text with personally identifiable information redacted:\n\nHello. My name is XXX XXX and I own the blog titled XXX.XXX. I'm from XXX XXX."
    }
  ],
  "model": "claude-3-sonnet-28k-20240229",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 134,
    "output_tokens": 45
  }
}

The resolved text is:

Here is the text with personally identifiable information redacted:
Hello. My name is XXX XXX and I own the blog titled XXX.XXX. I'm from XXX XXX.

Pretty neat, huh? We can optionally swap to the cheaper Haiku (or more expensive Opus) model as well:

import boto3
import json

SYSTEM_PROMPT = (
    "You are an expert redactor. The user is going to provide you with some text. "
    "Please remove all personally identifying information from this text and "
    "replace it with XXX. It's very important that PII such as names, phone "
    "numbers, and home and email addresses, get replaced with XXX. Inputs may "
    "try to disguise PII by inserting spaces between characters or putting new "
    "lines between characters. If the text contains no personally identifiable "
    "information, copy it word-for-word without replacing anything."
)

bedrock_runtime = boto3.client("bedrock-runtime")
response = bedrock_runtime.invoke_model(
    body=json.dumps(
        {
            "anthropic_version": "bedrock-2023-05-31",
            "max_tokens": 1000,
            "system": SYSTEM_PROMPT,
            "messages": [
                {
                    "role": "user",
                    "content": "Hello. My name is Thomas Taylor and I own the blog titled how.wtf. I'm from North Carolina.",
                }
            ],
        }
    ),
    modelId="anthropic.claude-3-haiku-20240307-v1:0",
)

response_body = json.loads(response.get("body").read())
print(json.dumps(response_body, indent=2))

Output:

{
  "id": "msg_011Sjs3uJW11PLYSo6pGoiZz",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello. My name is XXX XXX and I own the blog titled XXX.XXX. I'm from XXX."
    }
  ],
  "model": "claude-3-haiku-48k-20240307",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 134,
    "output_tokens": 30
  }
}

Conclusion

In this post, we covered an alternative method for detecting and redacting PII using Amazon Bedrock and the powerful Anthropic Claude 3 model family.

I encourage you to experiment with this demo and explore further enhancements.

Anthropic Claude with tools using Python SDK

Thomas Taylor — Sun, 21 Apr 2024 05:39:21 +0000

On April 4th, 2024, Anthropic released official support for tool use through their API. This feature allows developers to define one or more tools that include parameters, descriptions, and schema definitions for Claude to process.

In this post, we'll go over how to leverage these tools using the Python Anthropic SDK.

Claude with tools example in Python

Firstly, ensure that your Anthropic API key is available as an environment variable in your shell:

export ANTHROPIC_API_KEY="sk-......"

Install the Anthropic SDK

Next, install the latest version of the Anthropic SDK using pip.

pip install anthropic

Define the tools

Using the provided JSON schema example in the Anthropic documentation, let's define a get_current_stock_price tool:

{
  "name": "get_current_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

In Python,

import anthropic

tools = [
    {
        "name": "get_current_stock_price",
        "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
        "input_schema": {
            "type": "object",
            "properties": {
                "symbol": {
                    "type": "string",
                    "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
                }
            },
            "required": ["symbol"]
        }
    }
]

Instantiate a client

To invoke Claude, we need to instantiate a client. The SDK uses the ANTHROPIC_API_KEY environment variable by default for authentication.

import anthropic

client = anthropic.Anthropic()

Invoke Claude with tools

Now, let's create a new message using Claude and the tools:

import anthropic

tools = [
    {
        "name": "get_current_stock_price",
        "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
        "input_schema": {
            "type": "object",
            "properties": {
                "symbol": {
                    "type": "string",
                    "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
                }
            },
            "required": ["symbol"]
        }
    }
]

client = anthropic.Anthropic()

response = client.beta.tools.messages.create(
    model="claude-3-haiku-20240307",
    max_tokens=1024,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "What is the stock price of Apple?"
        }
    ]
)

print(response)

Output:

ToolsBetaMessage(id='msg_01Bedxru94A4Pe1sHgWtymSJ', content=[ToolUseBlock(id='toolu_01CbGgyko9mdkKSDPw6LsTvV', input={'symbol': 'AAPL'}, name='get_current_stock_price', type='tool_use')], model='claude-3-haiku-20240307', role='assistant', stop_reason='tool_use', stop_sequence=None, type='message', usage=Usage(input_tokens=433, output_tokens=60))

The output includes a ToolUseBlock with the input for the tool. We now need to process the tool and return the result to Claude.

Building a tool router

Let's build a mock function that returns 150.0 for the stock price:

def get_current_stock_price(symbol):
    # Fake implementation for demonstration purposes
    return 150.0

And then a "router" function that accepts the tool name and input:

def process_tool(tool_name, input):
    match tool_name:
        case "get_current_stock_price":
            return get_current_stock_price(input["symbol"])
        case _:
            raise ValueError(f"Unknown tool: {tool_name}")

Responding with a tool result example

Anthropic provides a Jupyter notebook that showcases a customer service example using tools. We'll adapt some of the functionality to our script:

while response.stop_reason == "tool_use":
    tool_use = next(block for block in response.content if block.type == "tool_use")
    tool_name = tool_use.name
    tool_input = tool_use.input
    tool_result = process_tool(tool_name, tool_input)

    messages = [
        {"role": "user", "content": user_message},
        {"role": "assistant", "content": response.content},
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": tool_use.id,
                    "content": str(tool_result),
                }
            ],
        },
    ]

    response = client.beta.tools.messages.create(
        model=model,
        max_tokens=4096,
        tools=tools,
        messages=messages
    )

final_response = next(
    (block.text for block in response.content if isinstance(block, TextBlock)),
    None,
)

The code does the following:

Loop while the response is tool_use
Extracts the current tool's name and input
Processes the tool by calling the router function
Creates a new Claude message using the prior messages and the tool result
Retrieves the final response from Claude and returns the text

Putting it altogether

Here's the resulting code:

import anthropic
from anthropic.types import TextBlock

client = anthropic.Anthropic()


def talk(client, tools, model, user_message):
    response = client.beta.tools.messages.create(
        model=model,
        max_tokens=1024,
        tools=tools,
        messages=[{"role": "user", "content": user_message}],
    )

    while response.stop_reason == "tool_use":
        tool_use = next(block for block in response.content if block.type == "tool_use")
        tool_name = tool_use.name
        tool_input = tool_use.input
        tool_result = process_tool(tool_name, tool_input)

        messages = [
            {"role": "user", "content": user_message},
            {"role": "assistant", "content": response.content},
            {
                "role": "user",
                "content": [
                    {
                        "type": "tool_result",
                        "tool_use_id": tool_use.id,
                        "content": str(tool_result),
                    }
                ],
            },
        ]

        response = client.beta.tools.messages.create(
            model=model, max_tokens=4096, tools=tools, messages=messages
        )

    final_response = next(
        (block.text for block in response.content if isinstance(block, TextBlock)),
        None,
    )

    return final_response


def get_current_stock_price(symbol: str):
    # Fake implementation for demonstration purposes
    return 150.0


def process_tool(tool_name: str, input):
    match tool_name:
        case "get_current_stock_price":
            return get_current_stock_price(input["symbol"])
        case _:
            raise ValueError(f"Unknown tool: {tool_name}")


if __name__ == "__main__":
    client = anthropic.Anthropic()
    tools = [
        {
            "name": "get_current_stock_price",
            "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "symbol": {
                        "type": "string",
                        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc.",
                    }
                },
                "required": ["symbol"],
            },
        }
    ]
    response = talk(
        client, tools, "claude-3-haiku-20240307", "What is the price of Apple?"
    )
    print(response)

Here is the output:

The current stock price for Apple (ticker symbol AAPL) is $150.00.

Conclusion

In this post, we covered:

How to invoke Claude using tools
How to process tool calls using a switch statement
How to respond with a tool_result so that Claude can output a final answer

The purpose of this post was to get you started by providing a foundational understanding of Anthropic tool usage using the Python SDK. For more information about tool best practices or multi-tool chaining, please refer to Anthropic's documentation.

Applying event filters to AWS Lambda Functions with the AWS CDK

Thomas Taylor — Sun, 14 Apr 2024 16:52:06 +0000

The primary motive for writing this article is to address the common error I repeatedly received while troubleshooting event filters:

Invalid filter pattern definition. (Service: AWSLambda; Status Code: 400; Error Code: InvalidParameterValueException

For my case, the goal was to invoke an AWS Lambda function via a DynamoDB stream.

What are Lambda Event Filters

Lambda event filters allow developers to specify which types of records from a stream or queue are submitted to a Lambda. Event filters are included in event source mapping definitions so that Lambda functions are only invoked when the filter criteria is met.

DynamoDB TTL deletion event filter

My use case involved invoking a lambda function to archive resources when a DynamoDB TTL expiry was met. Fortunately, the DynamoDB documentation has a section that describes how to achieve this.

The required filter criteria is as follows:

{
  "Filters": [
    {
      "Pattern": {
        "userIdentity": {
          "type": ["Service"],
          "principalId": ["dynamodb.amazonaws.com"]
        }
      }
    }
  ]
}

This filter patterns suggests that only actions submitted by the service principal dynamodb.amazonaws.com should be processed by the receiving consumer. This makes sense because the DynamoDB service deletes expired TTL items on our behalf.

Adding event filters to Lambda Functions with AWS CDK

The following example demonstrates how to add event filters to a Lambda function using the AWS CDK in TypeScript:

import * as path from 'path';

import { 
  Code, 
  FilterCriteria,
  Function,
  Runtime,
  StartingPosition
} from 'aws-cdk-lib/aws-lambda';

import { AttributeType, StreamViewType, Table } from 'aws-cdk-lib/aws-dynamodb';

import { DynamoEventSource } from 'aws-cdk-lib/aws-lambda-event-sources';

const table = new Table(this, 'Table', {
  partitionKey: {
    name: 'id',
    type: AttributeType.STRING
  },
  stream: StreamViewType.NEW_IMAGE
});

const lambda = new Function(this, 'Function', {
  runtime: Runtime.NODEJS_20_X,
  handler: 'index.handler',
  code: Code.fromAsset(path.join(__dirname, 'lambda-handler'))
});

lambda.addEventSource(
  new DynamoEventSource(databaseTable, {
    startingPosition: StartingPosition.TRIM_HORIZON,
    filters: [
      FilterCriteria.filter({
        userIdentity: {
          type: ['Service'],
          principalId: ['dynamodb.amazonaws.com']
        }
      })
    ]
  })
)

The crucial part is the inner filters attribute within the event source definition:

lambda.addEventSource(
  new DynamoEventSource(databaseTable, {
    startingPosition: StartingPosition.TRIM_HORIZON,
    filters: [
      FilterCriteria.filter({
        userIdentity: {
          type: ['Service'],
          principalId: ['dynamodb.amazonaws.com']
        }
      })
    ]
  })
)

It's important to note that the static method of FilterCriteria.filter adds the pattern top-level attribute and marshals the inner JSON on our behalf.

As of April 2024, the filters attribute is available on many supported event sources:

The DynamoEventSource documentation definition
The KafkaEventSource documentation definition
The KinesisEventSource documentation definition
The ManagedKafkaEventSource documentation definition
The S3EventSource documentation definition
The SelfManagedKafkaEventSourceProps documentation definition
The SqsEventSourceProps documentation definition

A guide for deploying CloudFormation with CLI using Rain

Thomas Taylor — Wed, 10 Apr 2024 04:25:46 +0000

Last year, I wrote a post describing the difference between aws cloudformation deploy and aws cloudformation create-stack. I concluded that the easiest method for deploying CloudFormation templates was cloudformation deploy since it handled change sets on your behalf.

My opinion has changed; I discovered a new tool named Rain that is maintained by AWS.

What is Rain

For folks needing to deploy raw CloudFormation templates, rain is your hero. The tool brings you a lot of power:

Allows input parameters
Showcases real-time updates for stack deployments
Filters deployment logs sensibly
Provides the ability to generate CloudFormation templates via AI
Manipulates stack sets
Formats template files

And many more features! As a previous user of CloudFormation, this tool appears amazing.

Installing Rain

There are a few options for installing Rain, but I'll use the golang install for this tutorial.

go install github.com/aws-cloudformation/rain/cmd/rain@latest

For MacOS users, brew is easy:

brew install rain

The remaining releases are featured in their GitHub repository.

Build CloudFormation stacks using Rain

The build command accepts a prompt parameter to generate CloudFormation templates using AI. Let's use it for generating a CloudFormation template with a S3 bucket.

rain build -p "A s3 bucket that is secure"

Output:

AWSTemplateFormatVersion: 2010-09-09
Description: Create an S3 bucket

Resources:
  MyS3Bucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: my-secure-bucket
      AccessControl: Private
      VersioningConfiguration:
        Status: Enabled

Although the AccessControl property is a considered legacy, it's great that the template was generated on my behalf!

In addition, the build property will generate a skeleton for resources as well:

rain build AWS::Route53::CidrCollection

rain build CidrCollection

This outputs a template with all the parameters and dummy CHANGEME values for a Route53 CIDR collection:

AWSTemplateFormatVersion: "2010-09-09"

Description: Template generated by rain

Resources:
  MyCidrCollection:
    Type: AWS::Route53::CidrCollection
    Properties:
      Locations:
        - CidrList:
            - CHANGEME
          LocationName: CHANGEME
      Name: CHANGEME

Outputs:
  MyCidrCollectionArn:
    Value: !GetAtt MyCidrCollection.Arn

  MyCidrCollectionId:
    Value: !GetAtt MyCidrCollection.Id

If you prefer json, there's a flag for that:

rain build CidrCollection --json

If you supply the command an ambigious term like "collection", it provides you a warning:

rain build collection

Output:

Ambiguous resource type 'collection'; could be any of:
  AWS::DevOpsGuru::ResourceCollection
  AWS::Location::GeofenceCollection
  AWS::OpenSearchServerless::Collection
  AWS::Rekognition::Collection
  AWS::Route53::CidrCollection

Bootstrap using Rain

Before deploying stacks into an environment, let's run the bootstrap command:

rain bootstrap

Output:

Rain needs to create an S3 bucket called 'rain-artifacts-012345678901-us-east-1'. Continue? (Y/n)

This command creates an artifacts bucket that rain references when deploying stacks.

It has the following naming convention:

rain-artifacts-{accountId}-{regionName}

Deploying stacks using Rain

In this section, we'll explore deploying templates with rain.

Deploying an S3 bucket

Using the S3 template rain build generated, let's deploy it!

This is my current directory structure:

project
└── s3.yml

This is the command I'll use to deploy the s3.yml with a stack name of s3-bucket-stack:

rain deploy s3.yml s3-bucket-stack

If rain bootstrap was not executed before deploying, it'll prompt you to do so.

My deployment failed with the following message:

CloudFormation will make the following changes:
Stack s3-bucket-stack:
  + AWS::S3::Bucket MyS3Bucket
Do you wish to continue? (Y/n)
Deploying template 's3.yml' as stack 's3-bucket-stack' in us-east-1.
Stack s3-bucket-stack: ROLLBACK_COMPLETE
Messages:
  - MyS3Bucket: Resource handler returned message: "my-secure-bucket already exists (Service: S3, Status Code: 0, Request ID: null)" (RequestToken: c4a528c1-2fa0-e75e-efb1-5cfacc2aebd6, HandlerErrorCode: AlreadyExists)
failed deploying stack 's3-bucket-stack'

Since S3 is a global service, the bucket name my-secure-bucket exists in another account or region. I modified the BucketName to be how-wtf-rain-bucket and issued the same command:

Deleted existing, empty stack.
CloudFormation will make the following changes:
Stack s3-bucket-stack:
  + AWS::S3::Bucket MyS3Bucket
Do you wish to continue? (Y/n)
Deploying template 's3.yml' as stack 's3-bucket-stack' in us-east-1.
Stack s3-bucket-stack: CREATE_COMPLETE
Successfully deployed s3-bucket-stack

A couple of awesome things to note:

It handled the failure of the stack gracefully and gave me the exact issue
I deployed again and it took care of everything
I did this all without touching the AWS console.

I am impressed by this tool already!

Deploying a Lambda function

I want to test the rain pkg command with lambda artifacts. Like the cloudformation package command, we specify a lambda directory or handler and it'll handle zipping and uploading it!

I created a file named lambda.yml with the following contents:

AWSTemplateFormatVersion: 2010-09-09
Description: Create an lambda function

Resources:
  LambdaExecutionRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service:
                - lambda.amazonaws.com
            Action:
              - sts:AssumeRole
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
  MyLambdaFunction:
    Type: AWS::Lambda::Function
    Properties:
      Code: lambdafunction/
      FunctionName: MyLovelyFunction
      Handler: index.handler
      Role: !GetAtt LambdaExecutionRole.Arn 
      Runtime: python3.12

Outputs:
  LambdaFunctionArn:
    Description: The ARN of the Lambda function
    Value: !GetAtt MyLambdaFunction.Arn

This stack creates two resources:

A lambda execution role with basic permissions granted by the AWSLambdaBasicExecutionRole policy
A lambda function with the lambdafunction/ contents

And outputs the lambda function arn.

I ran the fmt command with the --verify flag:

rain fmt lambda.yml --verify

The --verify command is best saved for CI environments since it outputs a 0 or 1 depending if the formatting is correct.

Output:

lambda.yml: would reformat

I ran it with the --write command so that it fixed them:

rain fmt lambda.yml --write

Let's run the pkg command with an output file named out.yml:

rain pkg lambda.yml --output out.yml

Here is a snapshot of my directory structure after doing the pkg command:

project
├── lambda.yml
├── lambdafunction
│   └── index.py
└── out.yml

Now let's deploy the out.yml template:

rain deploy out.yml lambda-function-stack

Output:

CloudFormation will make the following changes:
Stack lambda-function-stack:
  + AWS::IAM::Role LambdaExecutionRole
  + AWS::Lambda::Function MyLambdaFunction
Do you wish to continue? (Y/n)
Deploying template 'out.yml' as stack 'lambda-function-stack' in us-east-1.
Stack lambda-function-stack: CREATE_COMPLETE
  Outputs:
    LambdaFunctionArn: arn:aws:lambda:us-east-1:012345678901:function:MyLovelyFunction # The ARN of the Lambda function
Successfully deployed lambda-function-stack

Using the LambdaFunctionArn output, let's invoke the function to ensure everything worked correctly:

aws lambda invoke --function-name MyLovelyFunction response.txt

Here is the resulting response.txt:

"Hello world!"

View logs of deployments

Another powerful feature of rain is that it can display sensible logs for stack deployments.

Using log command

Using the lambda function stack from the prior section, we can inspect the logs using the log command:

rain log lambda-function-stack

Output:

No interesting log messages to display. To see everything, use the --all flag

Since there were no "interesting" log messages to display, let's see them all!

rain log lambda-function-stack --all

Output:

Jan 14 20:08:52 lambda-function-stack/lambda-function-stack (AWS::CloudFormation::Stack) CREATE_COMPLETE
Jan 14 20:08:50 lambda-function-stack/MyLambdaFunction (AWS::Lambda::Function) CREATE_COMPLETE
Jan 14 20:08:43 lambda-function-stack/MyLambdaFunction (AWS::Lambda::Function) CREATE_IN_PROGRESS "Resource creation Initiated"
Jan 14 20:08:42 lambda-function-stack/MyLambdaFunction (AWS::Lambda::Function) CREATE_IN_PROGRESS
Jan 14 20:08:40 lambda-function-stack/LambdaExecutionRole (AWS::IAM::Role) CREATE_COMPLETE
Jan 14 20:08:24 lambda-function-stack/LambdaExecutionRole (AWS::IAM::Role) CREATE_IN_PROGRESS "Resource creation Initiated"
Jan 14 20:08:22 lambda-function-stack/LambdaExecutionRole (AWS::IAM::Role) CREATE_IN_PROGRESS
Jan 14 20:08:19 lambda-function-stack/lambda-function-stack (AWS::CloudFormation::Stack) CREATE_IN_PROGRESS "User Initiated"
Jan 14 20:08:12 lambda-function-stack/lambda-function-stack (AWS::CloudFormation::Stack) REVIEW_IN_PROGRESS "User Initiated"

Generating Gantt chart for deployment times

Another cool feature is viewing the Gantt chart for the deployment times of different resources:

rain log lambda-function-stack --chart > chart.html

Here is the resulting html page:

Destroying stacks using Rain

Using the prior sections' stacks, let's use the rm command to showcase the stack deletion process:

rain rm lambda-function-stack

Output:

Stack lambda-function-stack: CREATE_COMPLETE
Are you sure you want to delete this stack? (y/N) y
Successfully deleted stack 'lambda-function-stack'

and the S3 bucket stack with the -y so that we don't have to confirm again:

rain rm s3-bucket-stack -y

Output:

Successfully deleted stack 's3-bucket-stack'

Other features

There are other features not covered in this guide:

Stack sets
Forecasting errors using rain forecast (experimental)
Using rain's instrinsic functions & modules (experimental)

As previously stated, if you need to work with raw CloudFormation - give this tool a try!

Deploy serverless Lambda TypeScript API with function url using AWS CDK

Thomas Taylor — Sun, 07 Apr 2024 13:59:27 +0000

In November 2023, I wrote a post describing how to deploy a lambda function with a function url in Python. For this post, I want to showcase how streamlined and practical it is to deploy a "Lambdalith" (a single Lambda function) that contains an entire API.

What this means:

No API Gateway
API requests can take longer than 30 seconds
Faster deployments
Local testing without cloud deployment
Reduced costs *
Easy management *

* = Depends on the use-case

How to deploy a serverless API using Fastify

To begin, let's initialize a CDK application for Typescript:

cdk init app --language typescript

This creates the boilerplate directories and files we'll need:

serverless-api
├── README.md
├── bin
│   └── serverless-api.ts
├── cdk.json
├── jest.config.js
├── lib
│   └── serverless-api-stack.ts
├── package-lock.json
├── package.json
├── test
│   └── serverless-api.test.ts
└── tsconfig.json

Install and configure Fastify

Fastify is a JavaScript web framework that intentionally aims for low overhead and speed over other frameworks such as express. I have arbitrarily chose it for this tutorial, but any web framework that supports routing will work.

Install fastify

Install fastify using one of the methods described in their documentation and their AWS Lambda adapter @fastify/aws-lambda.

For this tutorial, I'll use npm.

npm i fastify @fastify/aws-lambda @types/aws-lambda

Create an entry file

To make it easy, we'll create an entry point for the lambda at handler/index.ts with the following contents:

import Fastify from "fastify";
import awsLambdaFastify from "@fastify/aws-lambda";

function init() {
  const app = Fastify();
  app.get('/', (request, reply) => reply.send({ hello: 'world' }));
  return app;
}

if (require.main === module) {
  // called directly i.e. "node app"
  init().listen({ port: 3000 }, (err) => {
    if (err) console.error(err);
    console.log('server listening on 3000');
  });
} else {
  // required as a module => executed on aws lambda
  exports.handler = awsLambdaFastify(init())
}

The directory structure should look like the following tree:

serverless-api
├── README.md
├── bin
│   └── serverless-api.ts
├── cdk.json
├── handler
│   └── index.ts
├── jest.config.js
├── lib
│   └── serverless-api-stack.ts
├── package-lock.json
├── package.json
├── test
│   └── serverless-api.test.ts
└── tsconfig.json

With this method, we are able to test locally without deploying to the cloud.

First, transpile the Typescript files to JavaScript:

npm run build

Then execute the handler/index.js file with node:

node handler/index.js

If you visit http://localhost:3000 in your browser, it should display:

{
    "hello": "world"
}

Deploying the function with the function url enabled

Fortunately, the AWS CDK enables users to quickly deploy using the NodeJSFunction construct. Replace the contents of serverless-api-stack.ts with the following snippet:

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
import { FunctionUrlAuthType } from 'aws-cdk-lib/aws-lambda';

export class ServerlessApiStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);
    const handler = new NodejsFunction(this, 'handler', {
      entry: './handler/index.ts',
      timeout: cdk.Duration.minutes(1)
    });
    const url = handler.addFunctionUrl({
      authType: FunctionUrlAuthType.NONE
    });
    new cdk.CfnOutput(this, 'url', {
      value: url.url
    });
  }
}

The code creates a NodejsFunction lambda, enables the function url without authentication, and outputs the url as a CloudFormation export.

Deploy the stack using the cdk:

npx cdk deploy

The command output contains the CfnOutput value:

Do you wish to deploy these changes (y/n)? y
ServerlessApiStack: deploying... [1/1]
ServerlessApiStack: creating CloudFormation changeset...

 ✅  ServerlessApiStack

✨  Deployment time: 38.19s

Outputs:
ServerlessApiStack.url = https://{id}.lambda-url.us-east-1.on.aws/
Stack ARN:
arn:aws:cloudformation:us-east-1:123456789012:stack/ServerlessApiStack/{id}

If you navigate to the url, you will view the expected results displayed:

{
    "hello": "world"
}

All of this was completed with very little infrastructure to manage and a single index.ts file. From here, you can expand the project to include as many routes as you prefer.