docs: new k8 docs + new Operator doc by quetzalliwrites · Pull Request #420 · localstack/localstack-docs

quetzalliwrites · 2026-02-03T22:55:04Z

Preview URL w/ new k8 docs:
https://6852d11b.localstack-docs.pages.dev/aws/enterprise/kubernetes/

Resolves:

quetzalliwrites · 2026-02-03T22:55:40Z

src/content/docs/aws/enterprise/kubernetes/kubernetes-operator.md

+
+The Operator manifest creates all required `Roles`, `ClusterRoles`, and `bindings`.
+
+


@HarshCasper wondering about maintaining this table, I think we should automate this. I was thinking to make a sub issue for that task, may I assign it to you for next week?

I have a POC in #378 that could be adapted probably

cloudflare-workers-and-pages · 2026-02-03T23:06:11Z

Deploying localstack-docs with Cloudflare Pages

Latest commit:	`6315003`
Status:	✅ Deploy successful!
Preview URL:	https://6852d11b.localstack-docs.pages.dev
Branch Preview URL:	https://docs-new-k8-section.localstack-docs.pages.dev

View logs

quetzalliwrites · 2026-02-03T23:11:34Z

fyi @simonrw @mmaureenliu keep in mind the current manual markup table we added is not responsive (normal behavior for table markup): https://6852d11b.localstack-docs.pages.dev/aws/enterprise/kubernetes/kubernetes-operator/#permissions

We need to incorporate the same table component we're using in aws API Coverage tables, such as this one:
https://docs.localstack.cloud/aws/services/account/#api-coverage

cc @HarshCasper

nik-localstack · 2026-02-04T08:11:49Z

src/content/docs/aws/enterprise/kubernetes/concepts.md

@@ -0,0 +1,100 @@
+---
+title: Concepts 
+description: Concepts & Architecture


Should we add a diagram here similar to the one we have in Notion ?

Yes, we can add the one in Notion. I'll add a commit in a bit.

simonrw

In general a great restructuring of the Kubernetes section, thank you! However I have a few comments

simonrw · 2026-02-06T14:07:59Z

src/content/docs/aws/enterprise/kubernetes/deploy-helm-chart.md

+description: Install and run LocalStack on Kubernetes using the official Helm chart.
+template: doc
+sidebar:
+    order: 3


Could we make the helm chart 4 and the operator 3 to emphasise the operator more?

simonrw · 2026-02-06T14:14:43Z

src/content/docs/aws/enterprise/kubernetes/index.md

+tags: ["Enterprise"]
+---
+
+## Overview


nit: having the first heading of the Overview section called Overview is a little repetitive. What about skipping this heading?

simonrw · 2026-02-06T14:16:18Z

src/content/docs/aws/enterprise/kubernetes/index.md

+
+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.


When deployed on Kubernetes

Technically it still requires for the user to opt in to this situation by setting CONTAINER_RUNTIME=kubernetes. The Operator does this by default, but it's not guaranteed that the user will do this.

Suggested change

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.

When LocalStack is deployed on Kubernetes and Kubernetes support is enabled, 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.

I'm not a huge fan of this suggestion though.

simonrw · 2026-02-06T14:17:27Z

src/content/docs/aws/enterprise/kubernetes/index.md

+
+Supported cases:
+
+- Local Development Environments: Provide isolated, consistent environments for individual developers or small teams.


I think we are missing a common use case here

Suggested change

- Local Development Environments: Provide isolated, consistent environments for individual developers or small teams.

- Local Development Environments: Provide isolated, consistent environments for individual developers or small teams.

- Hosted Development Environments: Provide scalable and isolated development environments for teams.

simonrw · 2026-02-06T14:18:12Z

src/content/docs/aws/enterprise/kubernetes/index.md

+
+## Requirements:
+
+- K8s Cluster (k3d, minikube)


Suggested change

- K8s Cluster (k3d, minikube)

- K8s Cluster (such as k3d, minikube, EKS)

simonrw · 2026-02-06T14:43:34Z

src/content/docs/aws/enterprise/kubernetes/deploy-helm-chart.md

+:::
+
+#### 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: <name of the secret>
+        key: <name of the key in the secret containing the API key>
+```


I think we need to include this section in the callout as it refers to the values.yml file. If a user skips the callout then they skip straight to "you can reference it from... without telling them where to put it.

Suggested change

:::

#### 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: <name of the secret>

key: <name of the key in the secret containing the API key>

```

#### 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: <name of the secret>

key: <name of the key in the secret containing the API key>

:::

simonrw · 2026-02-06T14:44:26Z

src/content/docs/aws/enterprise/kubernetes/deploy-helm-chart.md

+```
+
+:::note
+Keep the existing **parameters table** in this page (or embed it as a collapsible section).


Is this line an internal note, or are we keeping it in the docs? If so I don't understand what it means

simonrw · 2026-02-06T14:45:46Z

src/content/docs/aws/enterprise/kubernetes/deploy-helm-chart.md

+
+### 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:


Suggested change

Some environments (notably **EKS on Fargate**) may terminate Pods with low/default resource allocations. Consider setting explicit requests/limits:

Some environments (notably **EKS on Fargate**) may terminate the LocalStack pod if not configured with reasonable requests/limits:

simonrw · 2026-02-06T14:45:58Z

src/content/docs/aws/enterprise/kubernetes/deploy-helm-chart.md

+    memory: 2Gi
+```
+
+### Add env vars and startup scripts


Suggested change

### Add env vars and startup scripts

### Add environment variables and startup scripts

simonrw · 2026-02-06T14:53:14Z

src/content/docs/aws/enterprise/kubernetes/faq.md

+  ```bash
+  kubectl port-forward -n <namespace> <pod-name> 4566
+  ```
+


Maybe can we add a section like this on proxy networking?

Certificate issues when spawning child pods

If you are experiencing an error similar to

localstack.services.lambda_.invocation.assignment.AssignmentException: Could not start new environment: MaxRetryError:MyHTTPSConnectionPool(host='192.168.0.1', port=443): Max retries exceeded with url: /api/v1/namespaces/ns-perf-a39e28bf-c600-498d-9ecc-41419eca1007/pods/lambda-pod-52c280f8dd194dc72bced60e190db6ef/log (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1032)')))

when creating child pods (a Lambda pod in the example above) then your proxy settings may be being applied to cluster internal communication.

If you are using HTTP_PROXY or HTTPS_PROXY environment variables to configure a TLS terminating proxy server (for example in corporate environments), then you may need to add the Kubernetes API server IP address to the NO_PROXY environment variable. With the example above, add NO_PROXY=192.168.0.1 to your pod environment variables.

draft 1 of new k8 docs

79802e6

quetzalliwrites requested review from a team and mmaureenliu February 3, 2026 22:55

quetzalliwrites self-assigned this Feb 3, 2026

quetzalliwrites requested review from HarshCasper and remotesynth as code owners February 3, 2026 22:55

quetzalliwrites added the documentation Improvements or additions to documentation label Feb 3, 2026

quetzalliwrites commented Feb 3, 2026

View reviewed changes

updating astro config js file to fix updated left hand nav

6315003

nik-localstack reviewed Feb 4, 2026

View reviewed changes

simonrw requested review from cloutierMat, dfangl, pinzon and simonrw February 6, 2026 10:03

simonrw requested changes Feb 6, 2026

View reviewed changes


		The Operator manifest creates all required `Roles`, `ClusterRoles`, and `bindings`.


		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.

	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.
	When LocalStack is deployed on Kubernetes and Kubernetes support is enabled, 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.

	- Local Development Environments: Provide isolated, consistent environments for individual developers or small teams.
	- Local Development Environments: Provide isolated, consistent environments for individual developers or small teams.
	- Hosted Development Environments: Provide scalable and isolated development environments for teams.

	- K8s Cluster (k3d, minikube)
	- K8s Cluster (such as k3d, minikube, EKS)


		### 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:

	### Add env vars and startup scripts
	### Add environment variables and startup scripts

Conversation

quetzalliwrites commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

quetzalliwrites Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cloudflare-workers-and-pages bot commented Feb 3, 2026

Deploying localstack-docs with Cloudflare Pages

Uh oh!

quetzalliwrites commented Feb 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

simonrw left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Certificate issues when spawning child pods

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

quetzalliwrites commented Feb 3, 2026 •

edited

Loading

quetzalliwrites Feb 3, 2026 •

edited

Loading