From 89ac7a51b107da46c97b6539ebb91aa18703cdf7 Mon Sep 17 00:00:00 2001 From: Kiah Imani Date: Fri, 3 Jul 2026 11:09:29 -0400 Subject: [PATCH] Create k8s-quickstart.md add Kubernetes quickstart guide --- .../aws/getting-started/k8s-quickstart.md | 209 ++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 src/content/docs/aws/getting-started/k8s-quickstart.md diff --git a/src/content/docs/aws/getting-started/k8s-quickstart.md b/src/content/docs/aws/getting-started/k8s-quickstart.md new file mode 100644 index 00000000..cafc4e49 --- /dev/null +++ b/src/content/docs/aws/getting-started/k8s-quickstart.md @@ -0,0 +1,209 @@ +--- +title: "Quickstart: LocalStack on Kubernetes" +description: Deploy LocalStack into a Kubernetes cluster and run a sample Lambda + RDS application in under 5 minutes. +template: doc +sidebar: + order: 6 +--- + +## 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](https://localstack.cloud/pricing). + +## Prerequisites + +Before starting, make sure you have the following: + +- A [LocalStack Auth Token](https://docs.localstack.cloud/getting-started/auth-token/) exported as `LOCALSTACK_AUTH_TOKEN` +- [Docker](https://docs.docker.com/get-docker/) +- [`kind`](https://kind.sigs.k8s.io/) +- [Terraform](https://www.terraform.io/downloads) (v1.11.1 or later) with the [`tflocal`](https://docs.localstack.cloud/user-guide/integrations/terraform/) wrapper +- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) with the [`awslocal`](https://docs.localstack.cloud/user-guide/integrations/aws-cli/#localstack-aws-cli-awslocal) wrapper +- [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) +- [`jq`](https://jqlang.github.io/jq/download/) +- [`k9s`](https://k9scli.io/) (optional, for visual cluster monitoring) + +## Step by Step + +### Step 1: Clone the sample repository + +```bash +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`: + +```bash +kind create cluster --name ls-k8s-demo +``` + +Verify the cluster is running: + +```bash +kubectl cluster-info +``` + +### Step 3: Deploy the LocalStack Operator + +The [LocalStack Operator](https://github.com/localstack/localstack-operator) manages the LocalStack deployment and configures cluster DNS so that AWS-style hostnames resolve correctly inside the cluster. + +```bash +kubectl apply -f https://github.com/localstack/localstack-operator/releases/latest/download/controller.yaml +``` + +Wait for the operator pod to reach a `Running` state: + +```bash +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: + +```bash +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: + +```bash +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): + +```bash +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: + +```bash +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: + +```bash +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. + +```bash +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: + +```bash +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 + +```bash +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: + +```json +{ + "results": [ + [1, "test"], + [2, "another"] + ] +} +``` + +## Validation + +Confirm that all three pods are running in the `workspace` namespace: + +```bash +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: + +```bash +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 `. + +**`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 ` 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](https://docs.localstack.cloud/aws/enterprise/kubernetes/). \ No newline at end of file