From 79802e60c0b59dd6c153e1d48b7ba961beeec289 Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Tue, 3 Feb 2026 23:48:06 +0100 Subject: [PATCH 1/2] draft 1 of new k8 docs --- .../aws/enterprise/kubernetes/concepts.md | 100 ++++++ .../kubernetes/deploy-helm-chart.md | 245 +++++++++++++++ .../docs/aws/enterprise/kubernetes/faq.md | 285 ++++++++++++++++++ .../docs/aws/enterprise/kubernetes/index.md | 54 ++++ .../{ => kubernetes}/kubernetes-executor.md | 2 +- .../kubernetes/kubernetes-operator.md | 266 ++++++++++++++++ 6 files changed, 951 insertions(+), 1 deletion(-) create mode 100644 src/content/docs/aws/enterprise/kubernetes/concepts.md create mode 100644 src/content/docs/aws/enterprise/kubernetes/deploy-helm-chart.md create mode 100644 src/content/docs/aws/enterprise/kubernetes/faq.md create mode 100644 src/content/docs/aws/enterprise/kubernetes/index.md rename src/content/docs/aws/enterprise/{ => kubernetes}/kubernetes-executor.md (99%) create mode 100644 src/content/docs/aws/enterprise/kubernetes/kubernetes-operator.md diff --git a/src/content/docs/aws/enterprise/kubernetes/concepts.md b/src/content/docs/aws/enterprise/kubernetes/concepts.md new file mode 100644 index 00000000..669ab019 --- /dev/null +++ b/src/content/docs/aws/enterprise/kubernetes/concepts.md @@ -0,0 +1,100 @@ +--- +title: Concepts +description: Concepts & Architecture +template: doc +sidebar: + order: 2 +tags: ["Enterprise"] +--- + +## Concepts & Architecture + +This conceptual guide explains how LocalStack runs inside a Kubernetes cluster, how workloads are executed, and how networking and DNS behave in a Kubernetes-based deployment. + + +## How the LocalStack pod works + +The LocalStack pod runs the LocalStack runtime and acts as the central coordinator for all emulated AWS services within the cluster. + +Its primary responsibilities include: + +* Exposing the LocalStack edge endpoint and AWS service API ports +* Receiving and routing incoming AWS API requests +* Orchestrating services that require additional compute (for example Lambda, Glue, ECS, and EC2) +* Managing the lifecycle of compute workloads spawned on behalf of AWS services + +From a Kubernetes perspective, the LocalStack pod is a standard pod that fully participates in cluster networking. It is typically exposed through a Kubernetes `Service`, and all AWS API interactions—whether from inside or outside the cluster—are routed through this pod. + + +## Execution modes + +LocalStack supports two execution modes for running compute workloads: + +* Docker executor +* Kubernetes-native executor + +### Docker executor + +The Docker executor runs workloads as containers started via a Docker runtime that is accessible from the LocalStack pod. This provides a simple, self-contained execution model without Kubernetes-level scheduling. + +However, Kubernetes does not provide a Docker daemon inside pods by default. To use the Docker executor in Kubernetes, the LocalStack pod must be given access to a Docker-compatible runtime (commonly via a Docker-in-Docker sidecar), which adds complexity and security concerns. + +### Kubernetes-native executor + +The Kubernetes-native executor runs workloads as Kubernetes pods. In this mode, LocalStack communicates directly with the Kubernetes API to create, manage, and clean up pods on demand. + +This execution mode provides stronger isolation, better security, and full integration with Kubernetes scheduling, resource limits, and lifecycle management. + +The execution mode is configured using the `CONTAINER_RUNTIME` environment variable. + + +## Child pods + +For compute-oriented AWS services, LocalStack can execute workloads either within the LocalStack pod itself or as separate Kubernetes pods. + +When the Kubernetes-native executor is enabled, LocalStack launches compute workloads as dedicated Kubernetes pods (referred to here as *child pods*). These include: + +* Lambda function invocations +* Glue jobs +* ECS tasks and Batch jobs +* EC2 instances +* RDS databases +* Apache Airflow workflows +* Amazon Managed Service for Apache Flink +* Amazon DocumentDB databases +* Redis instances +* CodeBuild containers + +For example, each Glue job run or ECS task invocation results in a new pod created from the workload’s configured runtime image and resource requirements. + +These child pods execute independently of the LocalStack pod. Kubernetes is responsible for scheduling them, enforcing resource limits, and managing their lifecycle. Most child pods are short-lived and terminate once the workload completes, though some services (such as Lambda) may keep pods running for longer periods. + + +## Networking model + +LocalStack runs as a standard Kubernetes pod and is accessed through a Kubernetes `Service` that exposes the edge API endpoint and any additional service ports. + +Other pods within the cluster communicate with LocalStack through this Service using normal Kubernetes DNS resolution and cluster networking. + +When the Kubernetes-native executor is enabled, child pods communicate with LocalStack in the same way, by sending API requests over the cluster network to the LocalStack Service. + + +## DNS behavior + +LocalStack includes a DNS server capable of resolving AWS-style service endpoints. + +In a Kubernetes deployment: + +* The DNS server can be exposed through the same Kubernetes Service as the LocalStack API ports. +* This allows transparent resolution of AWS service hostnames and `localhost.localstack.cloud` to LocalStack endpoints from within the cluster. + +This enables applications running in Kubernetes to interact with LocalStack using standard AWS SDK endpoint resolution without additional configuration. + + +## When to choose the Kubernetes-native executor + +The Kubernetes-native executor should be used when LocalStack is deployed inside a Kubernetes cluster and workloads must run reliably and securely. + +It is the recommended execution mode for nearly all Kubernetes deployments, because Kubernetes does not include a Docker daemon inside pods and does not provide native Docker access. The Kubernetes-native executor aligns with Kubernetes’ workload model, enabling pod-level isolation, scheduling, and resource governance. + +The Docker executor should only be used in Kubernetes environments that have been explicitly modified to provide Docker runtime access to the LocalStack pod. Such configurations are uncommon, often restricted, and can introduce security risks. As a result, the Kubernetes-native executor is the operationally supported and recommended execution mode for Kubernetes-based deployments. diff --git a/src/content/docs/aws/enterprise/kubernetes/deploy-helm-chart.md b/src/content/docs/aws/enterprise/kubernetes/deploy-helm-chart.md new file mode 100644 index 00000000..df1d2ee3 --- /dev/null +++ b/src/content/docs/aws/enterprise/kubernetes/deploy-helm-chart.md @@ -0,0 +1,245 @@ +--- +title: Deploy with Helm +description: Install and run LocalStack on Kubernetes using the official Helm chart. +template: doc +sidebar: + order: 3 +tags: ["Enterprise"] +--- + +## Introduction + +A Helm chart is a package that bundles Kubernetes manifests into a reusable, configurable deployment unit. It makes applications easier to install, upgrade, and manage. + +Using the LocalStack Helm chart lets you deploy LocalStack to Kubernetes with set defaults while still customizing resources, persistence, networking, and environment variables through a single `values.yaml`. This approach is especially useful for teams running LocalStack in shared clusters or CI environments where repeatable, versioned deployments matter. + +## Getting Started + +This guide shows you how to install and run LocalStack on Kubernetes using the official Helm chart. It walks you through adding the Helm repository, installing and configuring LocalStack, and verifying that your deployment is running and accessible in your cluster. + +## Prerequisites + +* **Kubernetes** 1.19 or newer +* **Helm** 3.2.0 or newer +* A working Kubernetes cluster (self-hosted, managed, or local) +* `kubectl` installed and configured for your cluster +* Helm CLI installed and available in your shell `PATH` + +:::note +**Namespace note:** All commands in this guide assume installation into the **`default`** namespace. +If you’re using a different namespace: +* Add `--namespace ` (and `--create-namespace` on first install) to Helm commands +* Add `-n ` to `kubectl` commands +::: + +## Install + +### 1) Add Helm repo + +```bash +helm repo add localstack https://localstack.github.io/helm-charts +helm repo update +``` + +### 2) Install with default configuration + +```bash +helm install localstack localstack/localstack +``` + +This creates the LocalStack resources in your cluster using the chart defaults. + +:::note +### Install LocalStack Pro + +If you want to use the `localstack-pro` image, create a `values.yaml` file: + +```yaml +image: + repository: localstack/localstack-pro + +extraEnvVars: + - name: LOCALSTACK_AUTH_TOKEN + value: "" +``` + +Then install using your custom values: + +```bash +helm install localstack localstack/localstack -f values.yaml +``` + +::: + +#### Auth token from a Kubernetes Secret + +If your auth token is stored in a Kubernetes Secret, you can reference it using `valueFrom`: + +```yaml +extraEnvVars: + - name: LOCALSTACK_AUTH_TOKEN + valueFrom: + secretKeyRef: + name: + key: +``` + +## Configure + +The chart ships with sensible defaults, but most production-ish setups will want a small `values.yaml` to customize behavior. + +### View all default values + +```bash +helm show values localstack/localstack +``` + +### Override values with a custom `values.yaml` + +Create a `values.yaml` and apply it during install/upgrade: + +```bash +helm upgrade --install localstack localstack/localstack -f values.yaml +``` + +:::note +Keep the existing **parameters table** in this page (or embed it as a collapsible section). + +If you’re migrating from the existing Kubernetes docs page, preserve the parameter names and meaning so users can “diff” old vs new without re-learning. +::: + +## Verify + +### 1) Check the Pod status + +```bash +kubectl get pods +``` + +After a short time, you should see the LocalStack Pod in `Running` status: + +```text +NAME READY STATUS RESTARTS AGE +localstack-7f78c7d9cd-w4ncw 1/1 Running 0 1m9s +``` + +### 2) Optional: Port-forward to access LocalStack from localhost + +If you’re running a **local cluster** (for example, k3d) and LocalStack is not exposed externally, port-forward the service: + +```bash +kubectl port-forward svc/localstack 4566:4566 +``` + +Now verify connectivity with the AWS CLI: + +```bash +aws sts get-caller-identity --endpoint-url "http://0.0.0.0:4566" +``` + +Example response: + +```json +{ + "UserId": "AKIAIOSFODNN7EXAMPLE", + "Account": "000000000000", + "Arn": "arn:aws:iam::000000000000:root" +} +``` + +## Common customizations + +### Enable persistence + +If you want state to survive Pod restarts, enable PVC-backed persistence: + +* Set: `persistence.enabled = true` + +Example `values.yaml`: + +```yaml +persistence: + enabled: true +``` + +:::note +This is especially useful for workflows where you seed resources or rely on state across restarts. +::: + + +### Set Pod resource requests and limits + +Some environments (notably **EKS on Fargate**) may terminate Pods with low/default resource allocations. Consider setting explicit requests/limits: + +```yaml +resources: + requests: + cpu: 1 + memory: 1Gi + limits: + cpu: 2 + memory: 2Gi +``` + +### Add env vars and startup scripts + +You can inject environment variables or run a startup script to: + +* pre-configure LocalStack +* seed AWS resources +* tweak LocalStack behavior + +Use: + +* `extraEnvVars` for environment variables +* `startupScriptContent` for startup scripts + +Example pattern: + +```yaml +extraEnvVars: + - name: DEBUG + value: "1" + +startupScriptContent: | + echo "Starting up..." + # add your initialization logic here +``` + +### Install into a different namespace + +Use `--namespace` and create it on first install: + +```bash +helm install localstack localstack/localstack --namespace localstack --create-namespace +``` + +Then include the namespace on kubectl commands: + +```bash +kubectl get pods -n localstack +``` + +### Update installation + +```bash +helm repo update +helm upgrade localstack localstack/localstack +``` + +If you use a `values.yaml`: + +```bash +helm upgrade localstack localstack/localstack -f values.yaml +``` + + +### Helm chart options + +Run: + +```bash +helm show values localstack/localstack +``` + +Keep the parameter tables on this page for quick reference (especially for common settings like persistence, resources, env vars, and service exposure). \ No newline at end of file diff --git a/src/content/docs/aws/enterprise/kubernetes/faq.md b/src/content/docs/aws/enterprise/kubernetes/faq.md new file mode 100644 index 00000000..2566d87c --- /dev/null +++ b/src/content/docs/aws/enterprise/kubernetes/faq.md @@ -0,0 +1,285 @@ +--- +title: FAQ +description: FAQ +template: doc +sidebar: + order: 6 +tags: ["Enterprise"] +--- + +# Troubleshooting FAQ + +This section covers common issues when running LocalStack on Kubernetes and how to diagnose them. + + +## The LocalStack Pod won’t start + +### Potential issues + +* The auth token is invalid. If license activation fails, the Pod will terminate immediately. +* The container image cannot be pulled or takes a long time to pull. +* The Pod cannot be scheduled because no nodes have sufficient capacity or nodes are tainted. +* **When using the Operator:** the Operator cannot validate the LocalStack license and refuses to create the Pod. + +### Potential fixes + +1. Check the Pod status + + List all Pods in the cluster and locate the LocalStack Pod: + + ```bash + kubectl get pods -A + ``` + +2. Describe the Pod + + If the Pod exists, inspect it for scheduling or startup errors: + + ```bash + kubectl describe pod -n + ``` + + Errors are typically visible in the `Events:` section. + + Example: + + ```text + Back-off restarting failed container localstack in pod + ``` + + This indicates that the LocalStack container crashed after startup. + +3. Check Pod logs + + If the Pod started but then crashed: + + ```bash + kubectl logs -n + ``` + + Startup errors are usually found near the end of the log output. Debugging is similar to running LocalStack in Docker—there is nothing Kubernetes-specific about most startup failures. + +4. If the Pod was never created + + * **Helm:** check the output of `helm install` + * **Operator:** check the Operator logs: + + ```bash + kubectl logs -n localstack-operator-system deployments/localstack-operator-system + ``` + + +## Services are unavailable + +If an AWS service fails to start or respond: + +* Verify that your LocalStack license includes the service you are trying to use. +* Check the LocalStack Pod logs for license-related or service-specific errors. + +There are typically no additional Kubernetes-level actions required for this issue. + + +## DNS resolution failures + +### DNS timeouts + +If you see errors such as: + +```text +Unable to get DNS result from upstream server for domain . The DNS operation timed out. +``` + +* Check whether the upstream DNS server was detected correctly. + +* Look for a log line like: + + ```text + Determined fallback dns: + ``` + +* If the detected DNS server is not valid for your cluster, set it explicitly using the `DNS_SERVER` configuration option. + + +### `localhost.localstack.cloud` does not resolve + +* **Inside LocalStack-spawned compute Pods** + + * Ensure `DNS_ADDRESS` is **not** set to `0`. + +* **Inside other Pods in the cluster** + + * Configure the Pod DNS settings to use the LocalStack Service IP. + * Set `dnsPolicy: None` and define a custom DNS config and search domains. + * See: [https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-dns-config](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-dns-config) + +* **Alternative** + + * Configure your cluster DNS (for example CoreDNS) to forward requests ending in `localhost.localstack.cloud` to the LocalStack DNS server. + * This is done automatically when using the LocalStack Operator. + + +## Permission / RBAC issues + +### Docker permission errors + +```text +Creating Docker SDK client failed +``` + +This is expected in Kubernetes. LocalStack attempts to connect to a Docker socket, which is typically unavailable in Pods. Docker is **not required** for running LocalStack on Kubernetes. + + +### Filesystem permission errors + +```text +PermissionError: [Errno 13] Permission denied: '/etc/resolv.conf' +``` + +This is expected when running LocalStack as a non-root user. Transparent endpoint injection may not work for init scripts or extensions in this case. + + +### Kubernetes API permission errors + +```text +kubernetes.client.exceptions.ApiException: (403) Reason: Forbidden +``` + +This indicates missing or incorrect RBAC permissions for the LocalStack Pod’s ServiceAccount. + +* If using the official Helm chart or Operator, update to the latest version: + + * Helm: `helm repo update localstack` + * Operator: re-apply the latest controller manifest +* If deploying LocalStack manually (not recommended), ensure the ServiceAccount role includes the required permissions: + [https://github.com/localstack/helm-charts/blob/main/charts/localstack/templates/role.yaml](https://github.com/localstack/helm-charts/blob/main/charts/localstack/templates/role.yaml) + + +## Networking problems + +### LocalStack or spawned Pods cannot connect to other cluster resources + +* Ensure the LocalStack Pod uses: + + ```yaml + dnsPolicy: ClusterFirst + ``` + + +### LocalStack cannot connect to real AWS + +Common causes: + +* **Transparent Endpoint Injection** + + * Review: [https://docs.localstack.cloud/aws/capabilities/networking/transparent-endpoint-injection/](https://docs.localstack.cloud/aws/capabilities/networking/transparent-endpoint-injection/) +* **Egress restrictions** + + * Ensure cluster network policies allow outbound internet access. + + +### Spawned Pods cannot connect to LocalStack + +* Spawned compute workloads should connect to LocalStack using: + + ```text + localhost.localstack.cloud + ``` + +* Using the Kubernetes Service name is possible, but host-based access (for example S3 virtual-host addressing) will not work. + +* Verify that the LocalStack DNS server is running (see DNS resolution failures). + + +### Other Pods cannot connect to LocalStack + +* Use the Kubernetes Service name created by Helm or the Operator. +* Confirm the LocalStack Pod is running. + +:::note +API responses returned by LocalStack include the `localhost.localstack.cloud` domain. +You can override this by setting: + +```text +LOCALSTACK_HOST= +``` +::: + + +### Cannot connect from the host machine + +* For local clusters (k3d, kind): + + * Ensure ports are forwarded correctly. + * Port `4566` (and service ports `4510–4559`) must be exposed. + * See: + + * [https://k3d.io/v5.3.0/usage/exposing_services/](https://k3d.io/v5.3.0/usage/exposing_services/) + * [https://kind.sigs.k8s.io/docs/user/configuration/#extra-port-mappings](https://kind.sigs.k8s.io/docs/user/configuration/#extra-port-mappings) + +* Alternatively, use port-forwarding: + + ```bash + kubectl port-forward -n 4566 + ``` + + +## Child containers are not spawning + +### Docker runtime errors + +```text +DockerNotAvailable: Docker not available +``` + +* Ensure `CONTAINER_RUNTIME=kubernetes` is set. +* Verify your license includes Kubernetes support. +* When using Helm, ensure `lambda.executor: kubernetes` is not overriding the runtime unintentionally. + + +### Image pull failures + +```text +ErrImagePull +``` + +This usually means the cluster restricts which images can be pulled. + +* Allow the LocalStack images in your cluster +* If you must use a custom image name or pull-through cache, see: + [https://docs.localstack.cloud/aws/capabilities/config/configuration/](https://docs.localstack.cloud/aws/capabilities/config/configuration/) + + +### Admission or security policy failures + +Errors such as: + +```text +kubernetes.utils.create_from_yaml.FailToCreateError +``` + +* Ensure you are running the latest LocalStack and Helm chart / Operator version. +* Check for: + + * Validating admission webhooks + [https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook) + * Pod Security Admission restrictions + [https://kubernetes.io/docs/concepts/security/pod-security-admission/](https://kubernetes.io/docs/concepts/security/pod-security-admission/) + + +### Child Pod timeouts + +If a child Pod is created but times out: + +* This is commonly caused by slow or blocked image pulls. +* Inspect the child Pod status and events, similar to diagnosing a LocalStack Pod startup failure. + + +## Logs to check + +* Check LocalStack Pod logs as described in **The LocalStack Pod won’t start** +* If using the Operator, also check the Operator logs: + + ```bash + kubectl logs -n localstack-operator-system deployments/localstack-operator-system + ``` + diff --git a/src/content/docs/aws/enterprise/kubernetes/index.md b/src/content/docs/aws/enterprise/kubernetes/index.md new file mode 100644 index 00000000..c55dfde2 --- /dev/null +++ b/src/content/docs/aws/enterprise/kubernetes/index.md @@ -0,0 +1,54 @@ +--- +title: Overview +description: Kubernetes with LocalStack +template: doc +sidebar: + order: 1 +tags: ["Enterprise"] +--- + +## Overview + +LocalStack is a local AWS cloud environment that emulates core AWS services for development and testing. + +When deployed on Kubernetes, services that typically spawn Docker containers (such as Lambda, ECS, or RDS) instead spawn Kubernetes pods within the same cluster. Behavior is improved by allowing dynamic scaling, isolation, and native Kubernetes orchestration. + +Supported cases: + +- Local Development Environments: Provide isolated, consistent environments for individual developers or small teams. +- CI/CD Pipeline Testing: Run end-to-end integration tests in a reproducible, cloud-like environment during CI/CD workflows. + +## Requirements: + +- K8s Cluster (k3d, minikube) +- Kubectl +- Helm +- LS helm chart +- LS operator + + +## DIY vs Helm Chart vs Operator + +| Deployment approach | Pros | Cons | +|---------------------|------|------| +| **DIY (YAML manifests)** | · Full control over Kubernetes configuration and resources | · Time-consuming to set up and maintain
· Manual updates and lifecycle management | +| **Helm chart** | · Simplifies deployment using templates and `values.yaml`
· Supports versioning, upgrades, and rollbacks
· Supports both LocalStack Community and Pro images | · Customization is limited to chart values and overrides | +| **Operator** | · Declarative, self-managed control plane
· Built-in validation, defaulting, and reconciliation logic | · Limited to the LocalStack Pro image only
· Steeper learning curve compared to Helm | + + +## Licensing + +While the LocalStack Community image can be deployed in Kubernetes, it does not support containerized service functionality required for full cloud-like behavior. Services such as Lambda, which require spawning and managing compute containers at runtime, only support pod creation with the LocalStack Pro image. The Community edition lacks the runtime capabilities needed to dynamically instantiate and orchestrate workloads in Kubernetes. + +## Help & Support + +LocalStack Pro (with a valid license) is the only version that provides: + +- Official support and integration for Kubernetes environments. +- Dynamic pod creation by services like Lambda, ECS, RDS, etc. + +Community image users: + +- Can be deployed in Kubernetes cluster for basic service emulation (e.g., S3, SQS). +- Do not receive official Kubernetes support. +- Cannot use features like Lambda execution. \ No newline at end of file diff --git a/src/content/docs/aws/enterprise/kubernetes-executor.md b/src/content/docs/aws/enterprise/kubernetes/kubernetes-executor.md similarity index 99% rename from src/content/docs/aws/enterprise/kubernetes-executor.md rename to src/content/docs/aws/enterprise/kubernetes/kubernetes-executor.md index 49eae43f..a6987e4c 100644 --- a/src/content/docs/aws/enterprise/kubernetes-executor.md +++ b/src/content/docs/aws/enterprise/kubernetes/kubernetes-executor.md @@ -3,7 +3,7 @@ title: Kubernetes Executor description: Configuring Kubernetes Executor for compute services in LocalStack Enterprise. template: doc sidebar: - order: 4 + order: 5 tags: ["Enterprise"] --- diff --git a/src/content/docs/aws/enterprise/kubernetes/kubernetes-operator.md b/src/content/docs/aws/enterprise/kubernetes/kubernetes-operator.md new file mode 100644 index 00000000..4db44968 --- /dev/null +++ b/src/content/docs/aws/enterprise/kubernetes/kubernetes-operator.md @@ -0,0 +1,266 @@ +--- +title: Deploy LocalStack Operator +description: Deploy and manage LocalStack in a Kubernetes cluster using the LocalStack Operator. +template: doc +sidebar: + order: 4 +tags: ["Enterprise"] +--- + +## Introduction + +The LocalStack Operator provides a Kubernetes-native way to deploy and manage LocalStack instances. It abstracts Kubernetes-specific configuration and automates operational tasks, making LocalStack deployments more consistent and easier to maintain. + +The Operator manages the full lifecycle of LocalStack resources and enables advanced Kubernetes integrations that are difficult to configure manually. + +## Getting started + +This guide explains how to deploy and manage LocalStack in a Kubernetes cluster using the LocalStack Operator. + + +### Advanced features + +The Operator supports the following advanced capabilities: + +* Cluster DNS configuration to correctly resolve AWS-style subdomains +* Automatic loading of Cloud Pods on startup +* Support for initialization hooks +* Simplified logging configuration +* Automatic mounting of a PersistentVolumeClaim (PVC) for the LocalStack data directory, enabling artifact caching and persistence + +### Prerequisites + +Before installing the LocalStack Operator, ensure you have: + +* A running Kubernetes cluster +* A LocalStack license that includes Kubernetes features +* An authentication token for that license + +:::note +A separate auth token must be used for each LocalStack instance. +::: + +### Deploy Operator + +The easiest way to install the Operator controller is to apply the published manifests directly from GitHub. + +```bash +# Install the latest version +kubectl apply -f https://github.com/localstack/localstack-operator/releases/latest/download/controller.yaml +``` + +To install a specific version: + +```bash +# Example: install v0.4.0 +kubectl apply -f https://github.com/localstack/localstack-operator/releases/v0.4.0/download/controller.yaml +``` + +See the Operator releases page for all available versions. + + +### Deploy LocalStack instance + +Once the Operator is running, you can deploy a LocalStack instance by creating a `LocalStack` custom resource. + +A minimal example looks like this: + +```yaml +apiVersion: api.localstack.cloud/v1alpha1 +kind: LocalStack +metadata: + name: localstack + namespace: my-namespace +spec: + image: localstack/localstack-pro:latest + dnsProvider: coredns + dnsConfigName: coredns + dnsConfigNamespace: kube-system + envFrom: + - secretRef: + name: localstack-auth-token +``` + +In this example, the LocalStack auth token is read from a Kubernetes Secret named `localstack-auth-token`. + +You can create this Secret with: + +```bash +kubectl create secret generic localstack-auth-token \ + --from-literal=LOCALSTACK_AUTH_TOKEN="$LOCALSTACK_AUTH_TOKEN" +``` + +The auth token must be available in the `LOCALSTACK_AUTH_TOKEN` environment variable when creating the Secret. + +notes::: +More advanced examples are available in the LocalStack Operator GitHub repository. +::: + +## Accessing LocalStack + +By default, the Operator creates a `ClusterIP` Service named: + +```text +localstack- +``` + +For the example above (`name: localstack`), the Service name is: + +```text +localstack-localstack +``` + +This Service exposes: + +* The LocalStack gateway port (`4566`) +* AWS service ports +* Port `53` for DNS + +Using standard Kubernetes DNS resolution, the Service can be reached at: + +* `localstack-localstack` (same namespace) +* `localstack-localstack.my-namespace` +* `localstack-localstack.my-namespace.svc.cluster.local` + +When `dnsProvider: coredns` is configured, LocalStack can also be reached through **any subdomain** of these service names. + + +## CRDs + +The LocalStack Operator introduces a `LocalStack` Custom Resource Definition (CRD) that controls how LocalStack instances are deployed and configured. + +:::Note +CRD documentation is currently maintained manually. For a full reference of available fields, see: [https://github.com/localstack/localstack-operator/blob/v0.4.0/api-docs.md](https://github.com/localstack/localstack-operator/blob/v0.4.0/api-docs.md) +::: + + +## Permissions + +The Operator manifest creates all required `Roles`, `ClusterRoles`, and `bindings`. + + +| **Kind** | **Name** | **API Groups** | **Resources** | **Verbs** | +| --- | --- | --- | --- | --- | +| **Role** | `localstack-operator-leader-election-role` | | `configmaps` | get, list, watch, create, update, patch, delete | +| | | `coordination.k8s.io` | `leases` | get, list, watch, create, update, patch, delete | +| | | | `events` | create, patch | +| **ClusterRole** | `localstack-operator-manager-role` | | `configmaps` | delete, get, list, patch, update, watch | +| | | | `events` | create, patch | +| | | | `pods`, `pods/exec`, `pods/log` | create, delete, deletecollection, get, list, patch, update, watch | +| | | | `secrets` | get, list, watch | +| | | | `serviceaccounts` | create, delete, get, list, update, watch | +| | | | `services` | create, delete, get, list, patch, update, watch | +| | | `api.localstack.cloud` | `localstacks` | create, delete, get, list, patch, update, watch | +| | | `api.localstack.cloud` | `localstacks/finalizers` | update | +| | | `api.localstack.cloud` | `localstacks/status` | get, patch, update | +| | | `apps` | `deployments` | create, delete, get, list, patch, update, watch | +| | | `apps` | `deployments/scale` | create, delete, get, list, patch, update, watch | +| | | `rbac.authorization.k8s.io` | `rolebindings`, `roles` | create, delete, list, update, watch | +| **ClusterRole** | `localstack-operator-metrics-reader` | | (nonResourceURLs: `/metrics`) | get | +| **ClusterRole** | `localstack-operator-proxy-role` | `authentication.k8s.io` | `tokenreviews` | create | +| | | `authorization.k8s.io` | `subjectaccessreviews` | create | + + +### Manager ClusterRole + +This ClusterRole allows the Operator to manage LocalStack resources and related Kubernetes objects. + +Resources include: + +* Pods (including exec and logs) +* Services +* Secrets +* Deployments +* ServiceAccounts +* LocalStack CRDs (`localstacks`, `status`, `finalizers`) +* RBAC roles and role bindings + +Verbs include: + +```text +create, delete, get, list, watch, patch, update +``` + + +### Metrics and proxy ClusterRoles + +Additional ClusterRoles are created for: + +* Reading metrics (`/metrics`) +* Authentication and authorization reviews (`tokenreviews`, `subjectaccessreviews`) + + +## DNS handling + +The LocalStack Operator configures cluster DNS to forward AWS-style subdomain requests to the LocalStack DNS server. + +This enables features such as: + +* S3 virtual-host–style addressing +* API Gateway domain name resolution + +Example from another pod in the cluster: + +```bash +aws apigatewayv2 create-api \ + --name testGatewayProxy \ + --protocol-type HTTP \ + --target "https://httpbin.org" +``` + +Example response: + +```json +{ + "ApiEndpoint": "http://1d4b6907.execute-api.localstack-localstack.my-namespace:4566", + "ApiId": "1d4b6907" +} +``` + +Calling the API: + +```bash +curl http://1d4b6907.execute-api.localstack-localstack.my-namespace:4566/json +``` + +This works without additional DNS configuration in client applications. + + +## Update + +The Operator can be upgraded by applying a newer controller manifest. + +Example: + +```bash +# Install an older version +kubectl apply -f https://github.com/localstack/localstack-operator/releases/download/v0.3.3/controller.yaml + +# Upgrade to a newer version +kubectl apply -f https://github.com/localstack/localstack-operator/releases/download/v0.4.1/controller.yaml +``` + +Kubernetes will handle rolling updates of the Operator deployment. + + +## Verify + +To verify that the Operator and LocalStack instance are running: + +```bash +kubectl get pods -n my-namespace +kubectl get localstacks -n my-namespace +``` + +Ensure that: + +* The Operator controller pod is running +* The LocalStack resource reports a healthy status +* The LocalStack Service is created + +:::note +* The LocalStack Operator is available **only with licenses that include Kubernetes features** +* Each LocalStack instance requires its **own auth token** +* The Operator supports **LocalStack Pro images only** +* DNS integration and Cloud Pod automation are Operator-exclusive features +::: \ No newline at end of file From 631500363cba0dd5f53e10fb4b8942758eca780d Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Wed, 4 Feb 2026 00:04:43 +0100 Subject: [PATCH 2/2] updating astro config js file to fix updated left hand nav --- astro.config.mjs | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/astro.config.mjs b/astro.config.mjs index 1b38c0a6..b2d6c45e 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -440,12 +440,13 @@ export default defineConfig({ slug: 'aws/enterprise', }, { - label: 'Single Sign-On', - autogenerate: { directory: '/aws/enterprise/sso' }, + label: 'Kubernetes', + autogenerate: { directory: '/aws/enterprise/kubernetes' }, + collapsed: true, }, { - label: 'Kubernetes Executor', - slug: 'aws/enterprise/kubernetes-executor', + label: 'Single Sign-On', + autogenerate: { directory: '/aws/enterprise/sso' }, }, { label: 'Enterprise Image',