Blog

Building and Debugging AWS Workflows Locally with Flox, LocalStack, and Colima

Steve Swoyer | 11 December 2024

You can use Flox to create a shareable, turn-key local environment for developing and testing the workloads and build artifacts you deploy to AWS, as well as configuring the resources required to run them.

The magic comes via the community edition of LocalStack, a platform that emulates AWS services by running them in containers, and Colima, a lightweight Linux VM for macOS and Linux. With Colima, you can spin up LocalStack without installing a separate container runtime. Flox makes it easy to build both packages into a portable environment that Just Works across macOS, Linux, and Windows with WSL2.

If you live inside the AWS CLI, this pattern should drop right into your workflow. You use LocalStack’s awslocal wrapper to interact with 35 different LocalStack AWS services, running virtually any command you might with aws. This gives you a way to prototype and test locally with awslocal before deploying.

Keen to learn more? Let’s get to it!

YAPD: Yet another Priority Directive

Imagine that you work for “Fluffirmations,” a social media start-up where pet guardians connect to share thoughts, images, and videos. Your start-up monetizes by offering different types of monthly subscription packages. These are delivered to customers’ homes—but addressed to their pets by name.

Cute, yes. But you also have a business analyst who’s always dreaming up new priority tasks for you, which isn’t so cute. Their latest top-priority directive is a “microservice” (their word) that collects PDFs from pet product suppliers, vet-med pharmaceutical companies, digital libraries, and any other possible pet-oriented source, scraping them to extract and analyze raw text and images.

You’re tasked with building the data ingestion component of this “microservice.”

But you’ve been here before. And you know exactly what to do. You’ve got Flox, Colima, and Localstack.

This is gonna be … as close to a piece of cake as anything cloud infrastructure-related can get.

Setting up your local dev environment

The last time your CEO gave you a top-priority assignment, you used the AWS and AWS SAM CLIs to develop and debug your Lambda functions locally. Setting up your dev environment was as easy as running

flox activate

This time, your workflow is a little more complex: not only do you need to author a new Lambda function, but you also need to provision and configure new AWS resources. This is the perfect use case for LocalStack. You start by git clone-ing your project repo, then cd into your project directory, running flox activate like you did before. This puts you into a virtual environment—an isolated subshell—containing the AWS CLI, AWS SAM CLI, GitHub CLI, 1Password CLI, and a few other essential tools.

Next, you activate the shared Flox environment your org created for running LocalStack and Colima:

flox activate -s -r fluffirmations/localstack

What you’ve done is “layered” two Flox environments on top of another, creating the equivalent of a virtual software stack.

The -r switch tells Flox to activate localstack as a remote environment, which is roughly analogous to an isolated, on-demand virtual overlay that you can invoke and run in any project directory. It gives you a dead simple way to spin up a local AWS development environment when you need it, and turn it off when you don’t.

Look at the time: your LocalStack local stack is up, running, and open for business, but the Trader Joe's pollo asado burrito you popped into the microwave isn’t quite finished nuking yet. Give it another minute.

AWS services a go go

Before getting started, you procrastinate just a bit, double checking which AWS services are available:

localstack status services
┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Service                  ┃ Status      ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ acm                      │ ✔ available │
│ apigateway               │ ✔ available │
│ cloudformation           │ ✔ available │
│ cloudwatch               │ ✔ available │
│ config                   │ ✔ available │
│ dynamodb                 │ ✔ available │
│ dynamodbstreams          │ ✔ available │
│ ec2                      │ ✔ available │
│ es                       │ ✔ available │
│ events                   │ ✔ available │
│ firehose                 │ ✔ available │
│ iam                      │ ✔ available │
│ kinesis                  │ ✔ available │
│ kms                      │ ✔ available │
│ lambda                   │ ✔ available │
│ logs                     │ ✔ available │
│ opensearch               │ ✔ available │
│ redshift                 │ ✔ available │
│ resource-groups          │ ✔ available │
│ resourcegroupstaggingapi │ ✔ available │
│ route53                  │ ✔ available │
│ route53resolver          │ ✔ available │
│ s3                       │ ✔ available │
│ s3control                │ ✔ available │
│ scheduler                │ ✔ available │
│ secretsmanager           │ ✔ available │
│ ses                      │ ✔ available │
│ sns                      │ ✔ available │
│ sqs                      │ ✔ available │
│ ssm                      │ ✔ available │
│ stepfunctions            │ ✔ available │
│ sts                      │ ✔ available │
│ support                  │ ✔ available │
│ swf                      │ ✔ available │
│ transcribe               │ ✔ available │
└──────────────────────────┴─────────────┘

Just about everything you need! A few services are missing, like ECR, which is a LocalStack Pro option, but there’s still plenty to work with. Still procrastinating, you run flox list -c to see exactly what’s installed in this new environment. Along with some automation logic that (a) bootstraps the colima and localstack services and (b) sets up a Python venv, you see the following:

flox list -c -r fluffirmations/localstack
 
[install]
colima.pkg-path = "colima"
docker.pkg-path = "docker-client"
gum.pkg-path = "gum"
localstack.pkg-path = "localstack"
kubectl.pkg-path = "kubectl"
python311Full.pkg-path = "python311Full"
pip.pkg-path = "python311Packages.pip"
boto3.pkg-path = "python311Packages.boto3"

Fascinating! This is the complete software manifest for your Flox localstack environment.

Oops, there’s the microwave. Time to grab that breakfast burrito and get to work.

Creating IAM roles and S3 buckets … locally

First, you’ll need to create a new IAM role for running functions in Lambda. Your repo already contains a trust-policy.json, so you run awslocal with the appropriate sub-command to set this up in LocalStack.

Note: awslocal is a Python-based wrapper for aws; it seems to do everything the actual command does.

awslocal iam create-role --role-name LambdaS3ExecutionRole --assume-role-policy-document file://./trust-policy.json
{
    "Role": {
        "Path": "/",
        "RoleName": "LambdaS3ExecutionRole",
        "RoleId": "AROAQAAAAAAANK5Z6DEDJ",
        "Arn": "arn:aws:iam::3141592653589:role/LambdaS3ExecutionRole",
        "CreateDate": "2024-12-10T21:57:07.770000+00:00",
        "AssumeRolePolicyDocument": {
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Effect": "Allow",
                    "Principal": {
                        "Service": "lambda.amazonaws.com"
                    },
                    "Action": "sts:AssumeRole"
                }
            ]
        }
    }
}

Beautiful. The stuff in curly braces is the output of the awslocal iam create-role command. And it’s just what you expected. Noshing on your burrito, you switch to the task of creating new S3 buckets for your Lambda function’s workflow. You can do this in LocalStack just as you would in the actual AWS environment:

awslocal s3api create-bucket \
    --bucket peedeeeff-bucket \
    --region us-east-1
 
awslocal s3api create-bucket \
    --bucket lambda-lies-down-on-broadway \
    --region us-east-1
 
awslocal s3api create-bucket \
    --bucket rawtext-bucket \
    --region us-east-1
 
awslocal s3api create-bucket \
    --bucket rawimages-bucket \
    --region us-east-1

Deploying with CloudFormation … locally

Incredibly, LocalStack also bundles a version of AWS CloudFormation, which you can use instead.

Actually, when you do go to deploy your function to Lambda, your org expects you to use CloudFormation, because that way you’re defining your infrastructure as code. (This makes it easier to version, share, and replicate resources across deployments.) So you grab a cloudformation-template.yaml file and customize it to suit your needs. You “deploy” this file in LocalStack the same way you would in real-deal AWS:

awslocal cloudformation create-stack \
  --stack-name pdf-processing-stack \
  --template-body file://cloudformation-template.yaml \
  --capabilities CAPABILITY_NAMED_IAM
{
    "StackId": "arn:aws:cloudformation:us-east-1:3141592653589:stack/pdf-processing-stack/8351048e"
}

It looks like it worked, but did it? You double check just to make sure:

awslocal cloudformation describe-stacks --stack-name pdf-processing-stack
{
    "Stacks": [
        {
            "StackId": "arn:aws:cloudformation:us-east-1:3141592653589:stack/pdf-processing-stack/8351048e",
            "StackName": "pdf-processing-stack",
            "CreationTime": "2024-12-10T23:24:24.079000+00:00",
            "LastUpdatedTime": "2024-12-10T23:26:12.452000+00:00",
            "RollbackConfiguration": {},
            "StackStatus": "CREATE_COMPLETE",
            "DisableRollback": false,
            "NotificationARNs": [],
            "Capabilities": [
                "CAPABILITY_NAMED_IAM"
            ],
            "Tags": [],
            "EnableTerminationProtection": false,
            "DriftInformation": {
                "StackDriftStatus": "NOT_CHECKED"
            }
        }
    ]
}

You’ve just used CloudFormation to create your S3 buckets. Once you’ve authored and tested your Lambda function, you’ll include that in the cloudformation-template.yaml, too. You’ll also define an event-driven S3 trigger that fires each time a new batch of PDFs shows up in the PeeDeeEff bucket.

Note: LocalStack’s S3 implementation doesn’t support S3 event notifications, so during testing, you’ll need to manually run the awslocal lambda invoke command, specifying the name of your function. When you deploy your cloudformation-template.yaml to your production AWS environment, you'll provision all necessary resources and define their dependencies.

You’ve finished your burrito, and it’s time to start working on your Lambda function. You crack your fingers and commence to writing Python.

Deploying Your Lambdas … locally

By lunch you’ve got something you can work with. It’s time to deploy it for testing in LocalStack Lambda. The neat thing about building and testing your Lambdas locally is that you can go much, much faster. Not only are your feedback loops shorter, but you also don’t obsess about getting everything just right before deploying, because you know you can iterate—faster and at lower cost—to get it just right.

awslocal lambda create-function     --function-name PDFProcessor     --runtime python3.11     --role arn:aws:iam::3141592653589:role/LambdaS3ExecutionRole     --handler lambda_function.lambda_handler     --zip-file fileb://lambda_function.zip     --timeout 15     --memory-size 128
{
    "FunctionName": "PDFProcessor",
    "FunctionArn": "arn:aws:lambda:us-east-1:3141592653589:function:PDFProcessor",
    "Runtime": "python3.11",
    "Role": "arn:aws:iam::3141592653589:role/LambdaS3ExecutionRole",
    "Handler": "lambda_function.lambda_handler",
    "CodeSize": 1345,
    "Description": "",
    "Timeout": 15,
    "MemorySize": 128,
    "LastModified": "2024-12-10T22:52:24.217545+0000",
    "CodeSha256": "IeisxizNCjWYpBrGRQO4OyQpwKCeAbLvyhyWzmNMTZQ=",
    "Version": "$LATEST",
    "TracingConfig": {
        "Mode": "PassThrough"
    },
    "RevisionId": "eae6c278-9c37-4a95-bc2c-2307b1e0e993",
    "State": "Pending",
    "StateReason": "The function is being created.",
    "StateReasonCode": "Creating",
    "PackageType": "Zip",
    "Architectures": [
        "x86_64"
    ],
    "EphemeralStorage": {
        "Size": 512
    },
    "SnapStart": {
        "ApplyOn": "None",
        "OptimizationStatus": "Off"
    },
    "RuntimeVersionConfig": {
        "RuntimeVersionArn": "arn:aws:lambda:us-east-1::runtime:8eeff65f6809a3ce81507fe733fe09b835899b99481ba22fd75b5a7338290ec1"
    },
    "LoggingConfig": {
        "LogFormat": "Text",
        "LogGroup": "/aws/lambda/PDFProcessor"
    }
}

Testing and debugging Lambda functions … locally

Again, the output in curly braces looks good! You’re well ahead of schedule.

You start iteratively testing and debugging your function. Before long, it runs reliably in LocalStack Lambda and passes both the local smoke tests and basic integration tests you run against it.

By 15:00 you’re ready to push your function to your org’s Lambda CI alias for more testing.

You’ve just got time enough to cut out for your early-afternoon dodeca-shot macchiato run.

When you get back, you can return to the real top-priority task you’d been working on: figuring out why customer ZMitchell and their cats Suki and Callie keep receiving a pallet loaded with dozens of 'Purrsnickety Picks' packages, instead of their single 'Meowsterpiece Monthly' subscription box. This has been going on for seven months now, costing Fluffirmations almost $5,000.

Bringing it all back home

Whether it’s running, testing, and debugging functions in Lambda; creating new S3 buckets; spinning up AMIs; creating and validating Redshift data models; defining CloudFormation IaaC configurations; or performing countless other tasks, working with AWS would be so much easier if you could prototype and test locally before deploying. Thanks to LocalStack you can work with most AWS services locally.

Flox makes this even sweeter, enabling you to experiment with LocalStack without making destructive changes to your local system. Just install Flox and run:

flox activate -s -r flox/colima -- flox activate -s -r flox/localstack

Sound too good to be true? Why not download Flox and put it to the test? It’s free, easy to learn, and (best of all) free!