Quickstart: LocalStack on Kubernetes

Introduction

This quickstart gets LocalStack running in a local Kubernetes cluster in about 5 minutes. You will deploy a sample application consisting of a Lambda function that queries an RDS MySQL database, with both services running as pods in your cluster managed by LocalStack’s Kubernetes executor.

LocalStack’s Kubernetes integration is available as part of the Enterprise plan.

Prerequisites

Before starting, make sure you have the following:

• A LocalStack Auth Token exported as LOCALSTACK_AUTH_TOKEN
• Docker
• kind
• Terraform (v1.11.1 or later) with the tflocal wrapper
• AWS CLI with the awslocal wrapper
• kubectl
• jq
• k9s (optional, for visual cluster monitoring)

Step by Step

Step 1: Clone the sample repository

git clone https://github.com/localstack-samples/localstack-k8s-demo.git
cd localstack-k8s-demo

The repository contains:

• main.tf: Terraform configuration that provisions an RDS MySQL database and a Lambda function on LocalStack
• lambda-src/: Python Lambda function source code with pymysql as a dependency
• localstack-instance.yml: Custom resource definition for the LocalStack deployment
• scripts/: Helper scripts for managing the auth token secret and port forwarding
• Makefile: Convenience targets for the full workflow

Step 2: Create the Kubernetes cluster

If you want to monitor the cluster visually, open a separate terminal and run k9s. The interface starts empty but populates as pods come up.

Create a local Kubernetes cluster using kind:

kind create cluster --name ls-k8s-demo

Verify the cluster is running:

kubectl cluster-info

Step 3: Deploy the LocalStack Operator

The LocalStack Operator manages the LocalStack deployment and configures cluster DNS so that AWS-style hostnames resolve correctly inside the cluster.

kubectl apply -f https://github.com/localstack/localstack-operator/releases/latest/download/controller.yaml

Wait for the operator pod to reach a Running state:

kubectl get pods -n localstack-operator-system

NAME                                                      READY   STATUS    RESTARTS   AGE
localstack-operator-controller-manager-78dcf78855-xxxxx   1/1     Running   0          30s

Step 4: Deploy LocalStack into the cluster

Create a namespace and a secret containing your Auth Token:

kubectl create namespace workspace

kubectl create secret -n workspace generic localstack-auth-token \
    --from-literal=LOCALSTACK_AUTH_TOKEN=$LOCALSTACK_AUTH_TOKEN

Deploy the LocalStack instance:

kubectl apply --server-side -f ./localstack-instance.yml

Wait for the LocalStack pod to be ready (this may take a minute or two while the image is pulled):

kubectl get pods -n workspace -w

Proceed once the pod shows 1/1 Running.

Step 5: Set up port forwarding

Forward port 4566 so you can run AWS commands against LocalStack from your local machine:

kubectl port-forward -n workspace svc/localstack-env-1 4566

This runs in the foreground. Open a new terminal for the remaining steps. Verify LocalStack is accessible:

awslocal sts get-caller-identity

Step 6: Deploy the sample application with Terraform

The Terraform configuration provisions the following resources on LocalStack:

• A VPC
• An RDS MySQL database (k8sdb)
• A Lambda function (myfunction) that connects to and queries the database

Both the database and Lambda function run as separate pods in the cluster, managed by LocalStack’s Kubernetes executor.

tflocal init -upgrade
tflocal apply -auto-approve

The deployment takes a few minutes as the MySQL pod needs to start up. Monitor progress with k9s or:

kubectl get pods -A -w

Note

The Lambda module is configured for ARM64 by default. If you are on an Intel/AMD machine, update main.tf to remove the docker_additional_options block and change architectures to ["x86_64"].

Step 7: Invoke the Lambda function

awslocal lambda invoke \
    --function-name myfunction \
    --payload '{}' /dev/stdout | jq .

The first invocation takes about 30 seconds as the Lambda pod starts up. You should see output like:

{
  "results": [
    [1, "test"],
    [2, "another"]
  ]
}

Validation

Confirm that all three pods are running in the workspace namespace:

kubectl get pods -n workspace

NAME                          READY   STATUS    AGE
lambda-myfunction-xxxxx       1/1     Running   36s
localstack-env-1-xxxxx        1/1     Running   11m
ls-mysql-xxxxx                1/1     Running   4m

You should see the LocalStack pod (localstack-*), the MySQL database pod (ls-mysql-*), and the Lambda function pod (lambda-myfunction-*) all running.

Cleanup

To tear down all resources:

tflocal apply -destroy -auto-approve
kubectl delete -f ./localstack-instance.yml
kubectl delete secret -n workspace localstack-auth-token

Troubleshooting

LocalStack pod is stuck in Pending or ImagePullBackOff Verify that your Auth Token secret was created correctly and that your cluster nodes can pull from the LocalStack registry. Check pod events with kubectl describe pod -n workspace <pod-name>.

awslocal sts get-caller-identity times out Confirm that port forwarding is still running in a separate terminal. If it dropped, restart it with kubectl port-forward -n workspace svc/localstack-env-1 4566.

Lambda invocation returns an error after the first call The first invocation takes up to 30 seconds for the Lambda pod to start. Wait and retry.

Terraform apply fails with a connection error Ensure port forwarding is active before running tflocal apply. LocalStack must be accessible on localhost:4566.

MySQL pod does not start Check cluster resource availability. The MySQL pod requires sufficient CPU and memory. Run kubectl describe pod -n workspace <ls-mysql-pod-name> to inspect scheduling events.

Next Steps

This quickstart covers a minimal deployment. For production-ready configuration options (including persistent storage, advanced networking, scaling, and monitoring), see the full Kubernetes Enterprise guide.