Kubernetes Executor

LocalStack Enterprise provides a Kubernetes executor for various emulated services. It allows you to run these services as Kubernetes pods in your Kubernetes clusters. By default, LocalStack uses the docker backend for these services. You can use either service-specific configuration variables or the generic CONTAINER_RUNTIME variable set to kubernetes to enable the Kubernetes executor.

EC2 Kubernetes Executor

The LocalStack Enterprise image allows you to run EC2 instances on Kubernetes. You can do so by setting the EC2_VM_MANAGER environment variable to kubernetes in the LocalStack container. Each EC2 instance in the Kubernetes VM manager is backed by a Pod.

The following operations are supported:

Operation	Notes
DescribeInstances	Returns all EC2 instances
RunInstances	Defines and starts an EC2 instance
StartInstances	Starts an already defined EC2 instance
StopInstances	Stops a running EC2 instance
TerminateInstances	Stops and undefines a EC2 instance

The current implementation is in preview and does not support volumes, custom AMIs, or networking features available in other VM managers.

ECS Kubernetes Executor

The LocalStack Enterprise image allows you to run ECS tasks on Kubernetes. The tasks are added to ELB load balancer target groups. You can do so by setting the ECS_TASK_EXECUTOR environment variable to kubernetes in the LocalStack container.

Container health checks

LocalStack maps a container definition’s healthCheck to a Kubernetes readiness probe. It does not create a liveness probe, so a failed health check does not restart the container. Task readiness also does not block the task from reaching the RUNNING state.

The executor maps health check commands and settings as follows:

• CMD-SHELL commands run as sh -c <command>, while CMD commands run directly.
• interval, timeout, and retries become periodSeconds, timeoutSeconds, and failureThreshold.
• Omitted settings use the ECS defaults: 30 seconds for interval, 5 seconds for timeout, 3 retries, and no startPeriod.
• Health checks start immediately during startPeriod. A successful check during this period makes the container healthy immediately, after which subsequent failures can make it unhealthy.

Commands that do not start with CMD or CMD-SHELL are ignored with a warning.

The DescribeTasks response derives container and task healthStatus values from readiness:

• A container without a health check in its task definition reports UNKNOWN.
• A ready container reports HEALTHY.
• A container that becomes not ready after previously being ready reports UNHEALTHY.
• A container that has never been ready reports UNKNOWN until enough probe cycles have elapsed, then reports UNHEALTHY.

Note

Kubernetes exposes container readiness, but not individual probe results. A container that never becomes ready can therefore remain UNKNOWN longer than it does on ECS. With the default health check settings, LocalStack can take up to 140 seconds to report it as UNHEALTHY.

Container user and resource limits

The user field supports numeric uid and uid:gid values. LocalStack maps them to securityContext.runAsUser and securityContext.runAsGroup. These values override the corresponding settings from K8S_CONTAINER_SECURITY_CONTEXT, while preserving its other fields. User or group names are ignored with a warning; when a value contains both a name and a numeric ID, LocalStack applies only the numeric part.

Kubernetes does not support the ECS ulimits configuration. LocalStack ignores ulimits in task definitions and logs a warning.

Lambda Kubernetes Executor

The LocalStack Enterprise image allows you to execute Lambda functions as Kubernetes pods. You can do so by setting LAMBDA_RUNTIME_EXECUTOR ( or lambda.executor when using the Helm configuration) to kubernetes. For more information, see the Helm Chart configuration.

• Kubernetes Lambda Executor in LocalStack scales Lambda execution by spawning new environments (running in pods) during concurrent invocations. Inactive environments shut down after 10 minutes (configurable via LAMBDA_KEEPALIVE_MS).
• Executor schedules multiple Lambda functions according to Kubernetes cluster defaults without specifying node affinity. Users can assign labels to lambda pods using the K8S_LABELS variable (e.g., K8S_LABELS=key=value,key2=value2).
• Timeout configurations similar to AWS are enforced using the Timeout function parameter. No intrinsic limits on the number of Lambdas; default limit on concurrent executions is 1000 (LAMBDA_LIMITS_CONCURRENT_EXECUTIONS).
• Custom DNS configuration for Lambda on Kubernetes can be set through the LAMBDA_DOCKER_DNS configuration variable.
• Users can customize Lambda runtime behavior by building custom images, pushing them to their registry, and specifying these images using the LAMBDA_RUNTIME_IMAGE_MAPPING configuration variable.
• Lambda on Kubernetes supports Warm Start and Persistence. Persistence must be configured for the LocalStack pod. The /var/lib/localstack directory should be persisted over LocalStack runs, typically in a volume.

Lambda hot reloading & remote debugging are not supported in the Kubernetes executor as the bind mounting into pods cannot be done at runtime.

S3 Files volumes

Lambda functions, ECS tasks, and Batch jobs running on the Kubernetes executor can mount S3 Files file systems. This requires an NFS client on the cluster nodes and additional RBAC permissions for LocalStack’s ServiceAccount. See Mounting a file system on Kubernetes for the details.

Other services

You can run the following services on Kubernetes clusters using the LocalStack Enterprise image:

• DocumentDB
• MWAA
• Glue
• RDS (MySQL & MSSQL)

To use Kubernetes as the runtime backend, set the CONTAINER_RUNTIME configuration variable to kubernetes. Note that there are no service-specific configuration variables for these services.