From bab0800163192af997d88b946e9040ac952af86a Mon Sep 17 00:00:00 2001 From: blkgrlcto Date: Mon, 6 Apr 2026 18:01:25 -0400 Subject: [PATCH 1/3] Create configuration.md created page to document k8s config settings --- .../enterprise/kubernetes/configuration.md | 90 +++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 src/content/docs/aws/enterprise/kubernetes/configuration.md diff --git a/src/content/docs/aws/enterprise/kubernetes/configuration.md b/src/content/docs/aws/enterprise/kubernetes/configuration.md new file mode 100644 index 00000000..e65e2a2d --- /dev/null +++ b/src/content/docs/aws/enterprise/kubernetes/configuration.md @@ -0,0 +1,90 @@ +--- +title: Configuration +description: Kubernetes configuration reference for LocalStack running on Kubernetes +template: doc +sidebar: + order: 6 +tags: ["Enterprise"] +--- + +When LocalStack runs on Kubernetes with the Kubernetes executor enabled, a set of configuration variables controls how child pods are created and managed. These variables apply to pods spawned by services such as Lambda, ECS, and RDS. + +### Namespace + +By default, LocalStack creates child pods in the `default` namespace. Use `LOCALSTACK_K8S_NAMESPACE` to deploy them into a different namespace. +```bash +LOCALSTACK_K8S_NAMESPACE=localstack-workloads +``` + +The namespace must already exist in your cluster before starting LocalStack. + +### Labels and annotations + +You can attach custom Kubernetes labels and annotations to all child pods created by LocalStack. This is useful for integrating with cluster tooling such as monitoring agents, network policies, or admission controllers. + +Both variables accept a comma-separated list of `key=value` pairs: +```bash +LOCALSTACK_K8S_LABELS=env=dev,team=platform +LOCALSTACK_K8S_ANNOTATIONS=prometheus.io/scrape=true,prometheus.io/port=8080 +``` + +### Container security context + +`K8S_CONTAINER_SECURITY_CONTEXT` sets the [container security context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) applied to child pods created by LocalStack. The value should be a JSON object matching the Kubernetes `SecurityContext` spec. + +This is useful when your cluster enforces pod security policies or security admission controls that require specific security context fields to be set. +```bash +K8S_CONTAINER_SECURITY_CONTEXT='{"runAsNonRoot": true, "runAsUser": 1000, "allowPrivilegeEscalation": false}' +``` + + + +### Init images + +LocalStack uses init containers in some child pods to perform setup tasks before the main container starts. The following variables let you override the default images used for these init containers: + +- `K8S_CURL_INIT_IMAGE` — the image used for the curl-based init container, typically responsible for waiting on network dependencies. +- `LAMBDA_K8S_INIT_IMAGE` — the image used for the init container in Lambda pods specifically. + +You may need to override these if your cluster cannot pull from the default registry, for example when working in an air-gapped environment or when images must be sourced from a private registry. +```bash +K8S_CURL_INIT_IMAGE=my-registry.example.com/curl-init:latest +LAMBDA_K8S_INIT_IMAGE=my-registry.example.com/lambda-init:latest +``` + +### Lambda image prefix + +`LAMBDA_K8S_IMAGE_PREFIX` sets a prefix applied to all Lambda runtime image names when pulling them in the Kubernetes executor. Use this to redirect image pulls to a private registry or mirror. +```bash +LAMBDA_K8S_IMAGE_PREFIX=my-registry.example.com/lambda-images/ +``` + +### Readiness timeouts + +LocalStack waits for child pods, deployments, and services to become ready before considering them available. The following variables control how long LocalStack waits before timing out: + +- `K8S_WAIT_FOR_POD_READY_TIMEOUT` — maximum time to wait for a pod to reach the `Ready` state +- `K8S_WAIT_FOR_DEPLOYMENT_READY_TIMEOUT` — maximum time to wait for a deployment to become available +- `K8S_WAIT_FOR_SERVICE_READY_TIMEOUT` — maximum time to wait for a service endpoint to be ready +```bash +K8S_WAIT_FOR_POD_READY_TIMEOUT=120 +K8S_WAIT_FOR_DEPLOYMENT_READY_TIMEOUT=180 +K8S_WAIT_FOR_SERVICE_READY_TIMEOUT=60 +``` + +Increase these values if your cluster is under heavy load or if image pulls are slow. + +### Configuration reference + +| Variable | Description | +|---|---| +| `LOCALSTACK_K8S_NAMESPACE` | Kubernetes namespace for child pods | +| `LOCALSTACK_K8S_LABELS` | Comma-separated `key=value` labels applied to child pods | +| `LOCALSTACK_K8S_ANNOTATIONS` | Comma-separated `key=value` annotations applied to child pods | +| `K8S_CONTAINER_SECURITY_CONTEXT` | JSON security context applied to child pod containers | +| `K8S_CURL_INIT_IMAGE` | Init container image used for network readiness checks | +| `LAMBDA_K8S_INIT_IMAGE` | Init container image used in Lambda pods | +| `LAMBDA_K8S_IMAGE_PREFIX` | Image name prefix for Lambda runtime images | +| `K8S_WAIT_FOR_POD_READY_TIMEOUT` | Timeout waiting for pod readiness | +| `K8S_WAIT_FOR_DEPLOYMENT_READY_TIMEOUT` | Timeout waiting for deployment readiness | +| `K8S_WAIT_FOR_SERVICE_READY_TIMEOUT` | Timeout waiting for service readiness | \ No newline at end of file From cf9019fde69d348b0cff392047fcede7f5f798ef Mon Sep 17 00:00:00 2001 From: blkgrlcto Date: Tue, 14 Apr 2026 22:52:32 -0400 Subject: [PATCH 2/3] Update configuration.md --- src/content/docs/aws/capabilities/config/configuration.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/content/docs/aws/capabilities/config/configuration.md b/src/content/docs/aws/capabilities/config/configuration.md index 83ca1f3b..78a1fbf0 100644 --- a/src/content/docs/aws/capabilities/config/configuration.md +++ b/src/content/docs/aws/capabilities/config/configuration.md @@ -203,6 +203,7 @@ This section covers configuration options that are specific to certain AWS servi | `EKS_K3S_IMAGE_REPOSITORY` | `rancher/k3s` (default) | Custom repository of the `rancher/k3s` image used to spin up Kubernetes clusters locally. | | `EKS_START_K3D_LB_INGRESS` | `0` (default) | Whether to start the k3d load balancer and Traefik ingress controller automatically when creating an EKS cluster. Set to `1` to enable. | | `EKS_PERSIST_CLUSTER_CONTENTS` | `0` (default) | When Persistence is enabled or when saving/loading Cloud Pods, this flag can be used to control whether the content deployed to EKS clusters will be persisted. Set to `1` to enable. | +| `EKS_K3D_CLUSTER_TOKEN` | `localstack-k3d-cluster-token` (default) | Token used to authenticate agent nodes joining a k3d-backed EKS cluster. Setting an explicit token ensures consistent node authentication across k3d versions, which is required for dynamic agent assignment (e.g., Karpenter support). Can be overridden via the `EKS_K3D_CLUSTER_TOKEN` environment variable. | ### ElastiCache From 14cd0dc51341a825b67c2f5c05397e101321dd80 Mon Sep 17 00:00:00 2001 From: blkgrlcto Date: Tue, 14 Apr 2026 23:02:54 -0400 Subject: [PATCH 3/3] removed cluster token config as it was added as a part of a different ticket removed todo --- src/content/docs/aws/capabilities/config/configuration.md | 1 - src/content/docs/aws/enterprise/kubernetes/configuration.md | 2 -- 2 files changed, 3 deletions(-) diff --git a/src/content/docs/aws/capabilities/config/configuration.md b/src/content/docs/aws/capabilities/config/configuration.md index 78a1fbf0..83ca1f3b 100644 --- a/src/content/docs/aws/capabilities/config/configuration.md +++ b/src/content/docs/aws/capabilities/config/configuration.md @@ -203,7 +203,6 @@ This section covers configuration options that are specific to certain AWS servi | `EKS_K3S_IMAGE_REPOSITORY` | `rancher/k3s` (default) | Custom repository of the `rancher/k3s` image used to spin up Kubernetes clusters locally. | | `EKS_START_K3D_LB_INGRESS` | `0` (default) | Whether to start the k3d load balancer and Traefik ingress controller automatically when creating an EKS cluster. Set to `1` to enable. | | `EKS_PERSIST_CLUSTER_CONTENTS` | `0` (default) | When Persistence is enabled or when saving/loading Cloud Pods, this flag can be used to control whether the content deployed to EKS clusters will be persisted. Set to `1` to enable. | -| `EKS_K3D_CLUSTER_TOKEN` | `localstack-k3d-cluster-token` (default) | Token used to authenticate agent nodes joining a k3d-backed EKS cluster. Setting an explicit token ensures consistent node authentication across k3d versions, which is required for dynamic agent assignment (e.g., Karpenter support). Can be overridden via the `EKS_K3D_CLUSTER_TOKEN` environment variable. | ### ElastiCache diff --git a/src/content/docs/aws/enterprise/kubernetes/configuration.md b/src/content/docs/aws/enterprise/kubernetes/configuration.md index e65e2a2d..8ff330e0 100644 --- a/src/content/docs/aws/enterprise/kubernetes/configuration.md +++ b/src/content/docs/aws/enterprise/kubernetes/configuration.md @@ -37,8 +37,6 @@ This is useful when your cluster enforces pod security policies or security admi K8S_CONTAINER_SECURITY_CONTEXT='{"runAsNonRoot": true, "runAsUser": 1000, "allowPrivilegeEscalation": false}' ``` - - ### Init images LocalStack uses init containers in some child pods to perform setup tasks before the main container starts. The following variables let you override the default images used for these init containers: