Skip to content

DOC-328: Rename K8s/EKS config variables to cloud-agnostic names #745

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
alexrashed wants to merge 2 commits into
base: aws-docs-release-july
Choose a base branch
from
+36 −30
Open

DOC-328: Rename K8s/EKS config variables to cloud-agnostic names #745

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5f77685
Rename Kubernetes/EKS config variables to cloud-agnostic names
alexrashed Jun 30, 2026
83f978e
Update EKS configuration variable note for clarity
alexrashed Jul 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 12 additions & 6 deletions src/content/docs/aws/configuration/config/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) |

@nik-localstack nik-localstack Jul 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something I just noticed is that this env var is no longer prefixed with EKS and it may be mixed with the rest of the K8S_* env vars which are related to the kubernetes executor. Sorry for the late observation but would it make sense to bring the EKS prefix back ? Or rename it to something different ?

@alexrashed alexrashed Jul 1, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one is not EKS specific, it is also used by AKS for example. So I actually feel like this is the right name for the variable? Otherwise it would be great if you could propose an explicit alternative name which is in line with the generic usage of the variable across cloud emulators now...

@nik-localstack nik-localstack Jul 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well naming is hard, but I would prefer to avoid the K8S_* prefix for consistency.
wdyt about MANAGED_K8S_PROVIDER ?

btw the same stands for K8S_STARTUP_TIMEOUT. It's related to EKS/AKS but from the prefix it reads like it's something related to the Kubernetes executor / runtime.

Not a blocker though, I just raised it because it seems confusing to me.

@quetzalliwrites quetzalliwrites Jul 1, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

since this point is not a merging blocker and Alex has addressed your other feedback, would be ready to approve this PR? 😸 @nik-localstack

@nik-localstack nik-localstack Jul 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@quetzalliwrites I would prefer to have a discussion first tbh.
Are we in a rush to close this for some reason ?

@quetzalliwrites quetzalliwrites Jul 1, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the traditional pace for closing PR's, we follow up quickly and confirm whether or not they are ready to merge ;)

FYI: If this is going to require an offline discussion first, I may move this to draft mode. This keeps the docs queue clean while providing you folks the time you want to figure it out.

| `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 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`).
:::

### ElastiCache

Expand Down
20 changes: 10 additions & 10 deletions src/content/docs/aws/enterprise/kubernetes/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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/).
Expand Down Expand Up @@ -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 |
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/aws/enterprise/kubernetes/kubernetes-executor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
14 changes: 7 additions & 7 deletions src/content/docs/aws/enterprise/kubernetes/pod-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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/).
12 changes: 6 additions & 6 deletions src/content/docs/aws/services/eks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
:::

Expand Down Expand Up @@ -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.
:::

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down