DOC-132 Flink containers not created when running in Kubernetes with Docker executor

[blkgrlcto]

• Add Deployment Considerations section explaining that the Docker executor is not supported when LocalStack runs as a Kubernetes pod, even with the host Docker socket mounted
• Document that CONTAINER_RUNTIME=kubernetes (Enterprise only) is required for MSF on Kubernetes, with a link to the Kubernetes executor docs
• Add MAIN_DOCKER_NETWORK to prerequisites for non-default Docker network setups
• Add Troubleshooting section covering the silent STARTING state, the internal cluster error log, and impact on IaC state waiters (Terraform, Crossplane)
• Add two Limitations bullets for the STARTING→FAILED gap and the Kubernetes/Docker executor constraint
  This PR fixes DOC-132

[cloudflare-workers-and-pages]

Deploying localstack-docs with    Cloudflare Pages

Latest commit:	8452252
Status:	✅  Deploy successful!
Preview URL:	https://bba1e39f.localstack-docs.pages.dev
Branch Preview URL:	https://doc-132-flink-containers-not.localstack-docs.pages.dev

View logs

[quetzalliwrites]

@tiurin @viren-nadkarni hey folks, just a tap on the shoulder, Kiah needs an ENG review for this PR :)

[viren-nadkarni]

Who did this investigation and identified the resolution? Makes sense to have them review this too.

I'm not particularly knowledgeable about the K8S executor, but looks sound to me.

[quetzalliwrites]

hola @komarkovich, does Support have an opinion for this PR perhaps? I don't know who reported this first, we made this ticket from Linear and the slack url doesn't seem to open anymore:

https://linear.app/localstack/issue/DOC-132/flink-containers-not-created-when-running-in-kubernetes-with-docker

[komarkovich]

hola @komarkovich, does Support have an opinion for this PR perhaps? I don't know who reported this first, we made this ticket from Linear and the slack url doesn't seem to open anymore:

https://linear.app/localstack/issue/DOC-132/flink-containers-not-created-when-running-in-kubernetes-with-docker

This was worked on by @EddEcho so maybe let's aski him to review.

[EddEcho]

Hey @viren-nadkarni , adding some context from the support side on this one.

This matches ticket #410154216640 (customer: Paul Stagner), which was closed due to customer inactivity — we never received the diagnose file or pod logs needed to confirm the exact failure path.

I ran an internal repro using a Kind + Helm setup with the Docker socket mounted and MAIN_DOCKER_NETWORK=kind. I was able to partially reproduce the issue: the application gets stuck in STARTING indefinitely, and internally LocalStack logs Error submitting job: Flink cluster is not running after the CLUSTER_READY_WAIT_TIMEOUT. This matches Vortexa's report.

However, since we didn't have the customer's diagnose file, I couldn't confirm whether they were using the Docker executor or the Kubernetes executor path or if we were hitting the exact same error — so the case was not escalated to L3.

One thing worth flagging: my repro ran with CONTAINER_RUNTIME=kubernetes and still hit issues (the taskmanager pod was created in K8s but never passed the readiness check). So I'd be cautious about documenting that flag as a confirmed fix without an end-to-end verification. Happy to share the repro script if it's useful for that or re-open again the investigation/ticket.

[viren-nadkarni]

Thanks @EddEcho

So I'd be cautious about documenting that flag as a confirmed fix without an end-to-end verification.

I concur. Best to reach out to whoever owns K8S Executor now to verify this. I'm not sure which team owns it - internal platform, or external platform, or devx