From 5f77685f161a338a75ba1acda74726233485a65f Mon Sep 17 00:00:00 2001 From: Alexander Rashed Date: Tue, 30 Jun 2026 12:57:29 +0200 Subject: [PATCH 1/3] Rename Kubernetes/EKS config variables to cloud-agnostic names The Kubernetes runtime configuration variables were renamed to cloud-agnostic names (K8S_*, K3S_*, K3D_*) in localstack-pro#7642, since they are shared across all services that run workloads on Kubernetes (EKS, Lambda, ECS, ...). Update the config reference and Kubernetes guides to the new names, note the deprecated aliases, and document the CLI v1 LOCALSTACK_-prefix behaviour. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../aws/configuration/config/configuration.md | 18 +++++++++++------ .../enterprise/kubernetes/configuration.md | 20 +++++++++---------- .../kubernetes/kubernetes-executor.md | 2 +- .../kubernetes/pod-configuration.md | 14 ++++++------- src/content/docs/aws/services/eks.mdx | 12 +++++------ 5 files changed, 36 insertions(+), 30 deletions(-) diff --git a/src/content/docs/aws/configuration/config/configuration.md b/src/content/docs/aws/configuration/config/configuration.md index 9ad76f33..f9ee8897 100644 --- a/src/content/docs/aws/configuration/config/configuration.md +++ b/src/content/docs/aws/configuration/config/configuration.md @@ -197,14 +197,20 @@ This section covers configuration options that are specific to certain AWS servi | Variable | Example Values | Description | | - | - | - | -| `EKS_K3S_FLAGS` | | Customize the `k3s` cluster created by LocalStack to emulate EKS clusters. | +| `K3S_FLAGS` | | Customize the `k3s` cluster created by LocalStack to emulate EKS clusters. (formerly `EKS_K3S_FLAGS`, still accepted as a deprecated alias) | | `EKS_LOADBALANCER_PORT` | `8081` (default) | Local port on which the Kubernetes load balancer is exposed on the host. | -| `EKS_K3S_IMAGE_TAG` | `v1.31.5-k3s1` (default) | Custom tag of the `rancher/k3s` image used to spin up Kubernetes clusters locally. | -| `EKS_K8S_PROVIDER` | `k3s` (default)\|`local` | The k8s provider which should be used to start the k8s cluster backing EKS. For more information on the providers, please see [Elastic Kubernetes Service (EKS)](/aws/services/eks) | -| `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. | +| `K3S_IMAGE_TAG` | `v1.31.5-k3s1` (default) | Custom tag of the `rancher/k3s` image used to spin up Kubernetes clusters locally. (formerly `EKS_K3S_IMAGE_TAG`, still accepted as a deprecated alias) | +| `K8S_PROVIDER` | `k3s` (default)\|`local` | The k8s provider which should be used to start the k8s cluster backing EKS. For more information on the providers, please see [Elastic Kubernetes Service (EKS)](/aws/services/eks) (formerly `EKS_K8S_PROVIDER`, still accepted as a deprecated alias) | +| `K3S_IMAGE_REPOSITORY` | `rancher/k3s` (default) | Custom repository of the `rancher/k3s` image used to spin up Kubernetes clusters locally. (formerly `EKS_K3S_IMAGE_REPOSITORY`, still accepted as a deprecated alias) | +| `K3D_START_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. (formerly `EKS_START_K3D_LB_INGRESS`, still accepted as a deprecated alias) | | `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. Can be overridden via the `EKS_K3D_CLUSTER_TOKEN` environment variable. | +| `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. (formerly `EKS_K3D_CLUSTER_TOKEN`, still accepted as a deprecated alias) | + +:::note +The Kubernetes runtime configuration variables were renamed to cloud-agnostic names (`K8S_*`, `K3S_*`, `K3D_*`) since they are shared across all services that run workloads on Kubernetes (EKS, Lambda, ECS, …). The previous `EKS_*`, `LOCALSTACK_K8S_*`, and `LAMBDA_K8S_*` names still work as deprecated aliases and will be removed in a future release. + +If you configure these options through the LocalStack CLI **v1**, keep the `LOCALSTACK_` prefix on the new names (e.g. `LOCALSTACK_K8S_PROVIDER`). The CLI v1 only forwards host environment variables prefixed with `LOCALSTACK_` into the container, where the prefix is stripped to yield the in-container variable (`K8S_PROVIDER`). +::: ### ElastiCache diff --git a/src/content/docs/aws/enterprise/kubernetes/configuration.md b/src/content/docs/aws/enterprise/kubernetes/configuration.md index df509e80..962783e6 100644 --- a/src/content/docs/aws/enterprise/kubernetes/configuration.md +++ b/src/content/docs/aws/enterprise/kubernetes/configuration.md @@ -11,9 +11,9 @@ When LocalStack runs on Kubernetes with the Kubernetes executor enabled, a set o ### Namespace -By default, LocalStack creates child pods in the `default` namespace. Use `LOCALSTACK_K8S_NAMESPACE` to deploy them into a different namespace. +By default, LocalStack creates child pods in the `default` namespace. Use `K8S_NAMESPACE` to deploy them into a different namespace. ```bash -LOCALSTACK_K8S_NAMESPACE=localstack-workloads +K8S_NAMESPACE=localstack-workloads ``` The namespace must already exist in your cluster before starting LocalStack. @@ -24,18 +24,18 @@ You can attach custom Kubernetes labels and annotations to all child pods create 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 +K8S_LABELS=env=dev,team=platform +K8S_ANNOTATIONS=prometheus.io/scrape=true,prometheus.io/port=8080 ``` ### Pod configuration -`LOCALSTACK_K8S_POD_CONFIG` configures Kubernetes metadata, scheduling, and resource settings for child pods created by supported services such as Lambda and ECS. +`K8S_POD_CONFIG` configures Kubernetes metadata, scheduling, and resource settings for child pods created by supported services such as Lambda and ECS. Use it to define reusable pod profiles with fields such as `nodeSelector`, `tolerations`, `affinity`, `resources`, `labels`, and `annotations`. The value must be valid JSON. ```bash -LOCALSTACK_K8S_POD_CONFIG='{"profiles":{"default":{"nodeSelector":{"pool":"general"}}}}' +K8S_POD_CONFIG='{"profiles":{"default":{"nodeSelector":{"pool":"general"}}}}' ``` For the full JSON schema, profile resolution order, and examples, see [Pod Configuration](/aws/enterprise/kubernetes/pod-configuration/). @@ -88,10 +88,10 @@ Increase these values if your cluster is under heavy load or if image pulls are | 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 | -| `LOCALSTACK_K8S_POD_CONFIG` | JSON pod configuration for supported child pods. See [Pod Configuration](/aws/enterprise/kubernetes/pod-configuration/) | +| `K8S_NAMESPACE` | Kubernetes namespace for child pods | +| `K8S_LABELS` | Comma-separated `key=value` labels applied to child pods | +| `K8S_ANNOTATIONS` | Comma-separated `key=value` annotations applied to child pods | +| `K8S_POD_CONFIG` | JSON pod configuration for supported child pods. See [Pod Configuration](/aws/enterprise/kubernetes/pod-configuration/) | | `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 | diff --git a/src/content/docs/aws/enterprise/kubernetes/kubernetes-executor.md b/src/content/docs/aws/enterprise/kubernetes/kubernetes-executor.md index 8716c4e2..422408ee 100644 --- a/src/content/docs/aws/enterprise/kubernetes/kubernetes-executor.md +++ b/src/content/docs/aws/enterprise/kubernetes/kubernetes-executor.md @@ -45,7 +45,7 @@ For more information, see the [Helm Chart configuration](https://github.com/loca - 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 `LAMBDA_K8S_LABELS` variable (e.g., `LAMBDA_K8S_LABELS=key=value,key2=value2`). + 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. diff --git a/src/content/docs/aws/enterprise/kubernetes/pod-configuration.md b/src/content/docs/aws/enterprise/kubernetes/pod-configuration.md index 7f32bf12..b2c05c51 100644 --- a/src/content/docs/aws/enterprise/kubernetes/pod-configuration.md +++ b/src/content/docs/aws/enterprise/kubernetes/pod-configuration.md @@ -12,7 +12,7 @@ tags: ["Enterprise"] When LocalStack runs inside Kubernetes with the Kubernetes executor enabled, some services create child pods for workloads such as Lambda invocations and ECS tasks. In heterogeneous clusters, these child pods may need additional Kubernetes configuration so they are scheduled onto the right node pools, carry the right resource requests, or integrate with cluster policies. -Use the `LOCALSTACK_K8S_POD_CONFIG` environment variable to configure Kubernetes metadata, scheduling, and resource settings for LocalStack-spawned pods. +Use the `K8S_POD_CONFIG` environment variable to configure Kubernetes metadata, scheduling, and resource settings for LocalStack-spawned pods. The variable accepts a JSON object with reusable `profiles` and optional per-service mappings. The value must be valid JSON. LocalStack validates this configuration at startup and refuses to start if the value is not valid JSON or contains unknown fields, so misconfigurations surface before any child pods are created. @@ -77,7 +77,7 @@ To use this with the Helm chart, pass the JSON as an environment variable in you ```yaml extraEnvVars: - - name: LOCALSTACK_K8S_POD_CONFIG + - name: K8S_POD_CONFIG value: | { "profiles": { @@ -190,15 +190,15 @@ Use them only for global defaults. Architecture values are normalized before lookup. For example, `ARM64` is treated as `arm64`, and `x86_64` or `X86_64` are treated as `amd64`. -The keys in `LOCALSTACK_K8S_POD_CONFIG` should still be `arm64` and `amd64`. +The keys in `K8S_POD_CONFIG` should still be `arm64` and `amd64`. If a service references a profile that does not exist, LocalStack logs a warning and applies no pod configuration for that request. It does not silently fall back to `default`. ## Labels and annotations -`labels` and `annotations` in `LOCALSTACK_K8S_POD_CONFIG` are merged into the metadata of the generated child pod. -Profile labels override labels set through `LOCALSTACK_K8S_LABELS`, and profile annotations override annotations set through `LOCALSTACK_K8S_ANNOTATIONS`. +`labels` and `annotations` in `K8S_POD_CONFIG` are merged into the metadata of the generated child pod. +Profile labels override labels set through `K8S_LABELS`, and profile annotations override annotations set through `K8S_ANNOTATIONS`. LocalStack also injects the following system labels: @@ -257,8 +257,8 @@ The following example schedules Lambda pods on dedicated nodes, adds tolerations ## Related configuration -- Use `LOCALSTACK_K8S_NAMESPACE` to choose the namespace for child pods. -- Use `LOCALSTACK_K8S_LABELS` and `LOCALSTACK_K8S_ANNOTATIONS` for simple labels and annotations that apply to all child pods. +- Use `K8S_NAMESPACE` to choose the namespace for child pods. +- Use `K8S_LABELS` and `K8S_ANNOTATIONS` for simple labels and annotations that apply to all child pods. - Use `K8S_CONTAINER_SECURITY_CONTEXT` to configure the security context for child pod containers. For the complete list of Kubernetes executor configuration variables, see the [Kubernetes configuration reference](/aws/enterprise/kubernetes/configuration/). diff --git a/src/content/docs/aws/services/eks.mdx b/src/content/docs/aws/services/eks.mdx index 661d2730..5d752aa7 100644 --- a/src/content/docs/aws/services/eks.mdx +++ b/src/content/docs/aws/services/eks.mdx @@ -98,7 +98,7 @@ The Traefik ingress controller and the default k3d load balancer containers are To restore the previous behavior, set the following configuration variable: ```bash -EKS_START_K3D_LB_INGRESS=1 +K3D_START_LB_INGRESS=1 ``` ::: @@ -464,7 +464,7 @@ Two AMI families are supported: LocalStack reads the same set of fields from both formats and propagates them to the registered node, including node labels, taints, topology metadata (region, zone, instance type), and the provider ID. This matches what real EKS nodes look like from the cluster's perspective. :::note -Self-managed nodes use the embedded k3d-backed provider (`EKS_K8S_PROVIDER=k3s`), which is the default. +Self-managed nodes use the embedded k3d-backed provider (`K8S_PROVIDER=k3s`), which is the default. The walkthrough below runs entirely between Docker containers, so it also works on macOS where direct host-to-instance networking is not available. ::: @@ -640,7 +640,7 @@ To try this out, follow the upstream [Getting started with Karpenter](https://ka ## Use an existing Kubernetes installation You can also access the EKS API using your existing local Kubernetes installation. -This can be achieved by setting the configuration variable `EKS_K8S_PROVIDER=local` and mounting the `$HOME/.kube/config` file into the LocalStack container. +This can be achieved by setting the configuration variable `K8S_PROVIDER=local` and mounting the `$HOME/.kube/config` file into the LocalStack container. When using a `docker-compose.yml` file, you need to add a bind mount like this: ```yaml @@ -875,15 +875,15 @@ The default version is `1.35`. | 1.31 | v1.31.14-k3s1 | eks.60 | | 1.30 | v1.30.14-k3s2 | eks.68 | -Users can specify the desired version when creating an EKS cluster in LocalStack using the `EKS_K3S_IMAGE_TAG` configuration variable when starting LocalStack. +Users can specify the desired version when creating an EKS cluster in LocalStack using the `K3S_IMAGE_TAG` configuration variable when starting LocalStack. ## Configuring the k3d Cluster Token When LocalStack creates a k3d-backed EKS cluster, it starts the k3s server with an explicit cluster token. This token is used to authenticate agent nodes joining the cluster, enabling dynamic node registration. -By default, LocalStack uses `localstack-k3d-cluster-token` as the cluster token. You can override this value using the `EKS_K3D_CLUSTER_TOKEN` configuration variable: +By default, LocalStack uses `localstack-k3d-cluster-token` as the cluster token. You can override this value using the `K3D_CLUSTER_TOKEN` configuration variable: ```bash -EKS_K3D_CLUSTER_TOKEN=my-custom-token localstack start +K3D_CLUSTER_TOKEN=my-custom-token localstack start ``` Any agent nodes added to the cluster — whether via k3d node create or k3s agent — will use the same token to authenticate with the k3s server. From 83f978ead79933245f1beab4f6e4318ba873fc29 Mon Sep 17 00:00:00 2001 From: Alex Rashed <2796604+alexrashed@users.noreply.github.com> Date: Wed, 1 Jul 2026 11:41:12 +0200 Subject: [PATCH 2/3] Update EKS configuration variable note for clarity --- src/content/docs/aws/configuration/config/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/aws/configuration/config/configuration.md b/src/content/docs/aws/configuration/config/configuration.md index f9ee8897..cf8ef907 100644 --- a/src/content/docs/aws/configuration/config/configuration.md +++ b/src/content/docs/aws/configuration/config/configuration.md @@ -207,7 +207,7 @@ This section covers configuration options that are specific to certain AWS servi | `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. (formerly `EKS_K3D_CLUSTER_TOKEN`, still accepted as a deprecated alias) | :::note -The Kubernetes runtime configuration variables were renamed to cloud-agnostic names (`K8S_*`, `K3S_*`, `K3D_*`) since they are shared across all services that run workloads on Kubernetes (EKS, Lambda, ECS, …). The previous `EKS_*`, `LOCALSTACK_K8S_*`, and `LAMBDA_K8S_*` names still work as deprecated aliases and will be removed in a future release. +The EKS configuration variables were renamed to cloud-agnostic names since they're shared across cloud emulators (AWS EKS / Azure AKS). The previous `EKS_*`, `LOCALSTACK_K8S_*`, and `LAMBDA_K8S_*` names still work as deprecated aliases and will be removed in a future release. If you configure these options through the LocalStack CLI **v1**, keep the `LOCALSTACK_` prefix on the new names (e.g. `LOCALSTACK_K8S_PROVIDER`). The CLI v1 only forwards host environment variables prefixed with `LOCALSTACK_` into the container, where the prefix is stripped to yield the in-container variable (`K8S_PROVIDER`). ::: From 0643035e81adfe28780598e3885f9488600d0158 Mon Sep 17 00:00:00 2001 From: Alexander Rashed Date: Wed, 1 Jul 2026 14:14:49 +0200 Subject: [PATCH 3/3] Rename K8S_PROVIDER to MANAGED_K8S_PROVIDER Co-Authored-By: Claude Opus 4.8 (1M context) --- src/content/docs/aws/configuration/config/configuration.md | 4 ++-- src/content/docs/aws/services/eks.mdx | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/aws/configuration/config/configuration.md b/src/content/docs/aws/configuration/config/configuration.md index cf8ef907..4e0de16b 100644 --- a/src/content/docs/aws/configuration/config/configuration.md +++ b/src/content/docs/aws/configuration/config/configuration.md @@ -200,7 +200,7 @@ This section covers configuration options that are specific to certain AWS servi | `K3S_FLAGS` | | Customize the `k3s` cluster created by LocalStack to emulate EKS clusters. (formerly `EKS_K3S_FLAGS`, still accepted as a deprecated alias) | | `EKS_LOADBALANCER_PORT` | `8081` (default) | Local port on which the Kubernetes load balancer is exposed on the host. | | `K3S_IMAGE_TAG` | `v1.31.5-k3s1` (default) | Custom tag of the `rancher/k3s` image used to spin up Kubernetes clusters locally. (formerly `EKS_K3S_IMAGE_TAG`, still accepted as a deprecated alias) | -| `K8S_PROVIDER` | `k3s` (default)\|`local` | The k8s provider which should be used to start the k8s cluster backing EKS. For more information on the providers, please see [Elastic Kubernetes Service (EKS)](/aws/services/eks) (formerly `EKS_K8S_PROVIDER`, still accepted as a deprecated alias) | +| `MANAGED_K8S_PROVIDER` | `k3s` (default)\|`local` | The k8s provider which should be used to start the k8s cluster backing EKS. For more information on the providers, please see [Elastic Kubernetes Service (EKS)](/aws/services/eks) (formerly `EKS_K8S_PROVIDER`, still accepted as a deprecated alias) | | `K3S_IMAGE_REPOSITORY` | `rancher/k3s` (default) | Custom repository of the `rancher/k3s` image used to spin up Kubernetes clusters locally. (formerly `EKS_K3S_IMAGE_REPOSITORY`, still accepted as a deprecated alias) | | `K3D_START_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. (formerly `EKS_START_K3D_LB_INGRESS`, still accepted as a deprecated alias) | | `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. | @@ -209,7 +209,7 @@ This section covers configuration options that are specific to certain AWS servi :::note The EKS configuration variables were renamed to cloud-agnostic names since they're shared across cloud emulators (AWS EKS / Azure AKS). The previous `EKS_*`, `LOCALSTACK_K8S_*`, and `LAMBDA_K8S_*` names still work as deprecated aliases and will be removed in a future release. -If you configure these options through the LocalStack CLI **v1**, keep the `LOCALSTACK_` prefix on the new names (e.g. `LOCALSTACK_K8S_PROVIDER`). The CLI v1 only forwards host environment variables prefixed with `LOCALSTACK_` into the container, where the prefix is stripped to yield the in-container variable (`K8S_PROVIDER`). +If you configure these options through the LocalStack CLI **v1**, keep the `LOCALSTACK_` prefix on the new names (e.g. `LOCALSTACK_MANAGED_K8S_PROVIDER`). The CLI v1 only forwards host environment variables prefixed with `LOCALSTACK_` into the container, where the prefix is stripped to yield the in-container variable (`MANAGED_K8S_PROVIDER`). ::: ### ElastiCache diff --git a/src/content/docs/aws/services/eks.mdx b/src/content/docs/aws/services/eks.mdx index 5d752aa7..ab316f0d 100644 --- a/src/content/docs/aws/services/eks.mdx +++ b/src/content/docs/aws/services/eks.mdx @@ -464,7 +464,7 @@ Two AMI families are supported: LocalStack reads the same set of fields from both formats and propagates them to the registered node, including node labels, taints, topology metadata (region, zone, instance type), and the provider ID. This matches what real EKS nodes look like from the cluster's perspective. :::note -Self-managed nodes use the embedded k3d-backed provider (`K8S_PROVIDER=k3s`), which is the default. +Self-managed nodes use the embedded k3d-backed provider (`MANAGED_K8S_PROVIDER=k3s`), which is the default. The walkthrough below runs entirely between Docker containers, so it also works on macOS where direct host-to-instance networking is not available. ::: @@ -640,7 +640,7 @@ To try this out, follow the upstream [Getting started with Karpenter](https://ka ## Use an existing Kubernetes installation You can also access the EKS API using your existing local Kubernetes installation. -This can be achieved by setting the configuration variable `K8S_PROVIDER=local` and mounting the `$HOME/.kube/config` file into the LocalStack container. +This can be achieved by setting the configuration variable `MANAGED_K8S_PROVIDER=local` and mounting the `$HOME/.kube/config` file into the LocalStack container. When using a `docker-compose.yml` file, you need to add a bind mount like this: ```yaml