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 diff --git a/src/content/docs/aws/services/eks.mdx b/src/content/docs/aws/services/eks.mdx index 987e002f..171f5e14 100644 --- a/src/content/docs/aws/services/eks.mdx +++ b/src/content/docs/aws/services/eks.mdx @@ -686,6 +686,17 @@ The default version is `1.35`. Users can specify the desired version when creating an EKS cluster in LocalStack using the `EKS_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: + +```bash +EKS_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. + ## Resource Browser The LocalStack Web Application provides a Resource Browser for managing EKS clusters.