docs: new k8 docs + new Operator doc #420
Conversation
quetzalliwrites
requested review from
HarshCasper and
remotesynth
as code owners
quetzalliwrites
added
the
documentation
Deploying localstack-docs with
|
| Latest commit: |
98a7e0f
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://f3b8b5bc.localstack-docs.pages.dev |
| Branch Preview URL: | https://docs-new-k8-section.localstack-docs.pages.dev |
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: cc @HarshCasper |
simonrw
left a comment
simonrw
left a comment
There was a problem hiding this comment.
In general a great restructuring of the Kubernetes section, thank you! However I have a few comments
src/content/docs/aws/enterprise/kubernetes/deploy-helm-chart.md
Outdated
Show resolved
Hide resolved
| tags: ["Enterprise"] | ||
| --- | ||
|
|
||
| ## Overview |
There was a problem hiding this comment.
nit: having the first heading of the Overview section called Overview is a little repetitive. What about skipping this heading?
src/content/docs/aws/enterprise/kubernetes/deploy-helm-chart.md
Outdated
Show resolved
Hide resolved
src/content/docs/aws/enterprise/kubernetes/deploy-helm-chart.md
Outdated
Show resolved
Hide resolved
src/content/docs/aws/enterprise/kubernetes/deploy-helm-chart.md
Outdated
Show resolved
Hide resolved
src/content/docs/aws/enterprise/kubernetes/deploy-helm-chart.md
Outdated
Show resolved
Hide resolved
mmaureenliu
left a comment
mmaureenliu
left a comment
There was a problem hiding this comment.
I really LOVE this new doc!
Made some comments and suggestions and pointed a few questions to @simonrw . All in all this is great work. Thanks everybody involved! Look forward to seeing the final publication. We'll make further improvements based on user feedback but this is an amazing start.
|
|
||
| ## 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. |
There was a problem hiding this comment.
Not for current iteration, but we'll think about how to generalise the wording for all emulators we offer. I may create a placeholder Linear ticket for this.
There was a problem hiding this comment.
@mmaureenliu are you saying this in reference of the phrase "emulated AWS services"?
Currently, my understanding is that we use the following terms for our emulators:
- LocalStack for AWS
- LocalStack for Azure
- LocalStack for Snowflake
|
|
||
| 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. |
There was a problem hiding this comment.
Probably more a question for @simonrw:
Better mention what's default - I assume it defaults to (or will default to from a certain version onwards) kubernetes mode?
And can refer to the when to use what mode section below.
There was a problem hiding this comment.
Yes it defaults to docker so the user has to opt in to using the k8s executor. However only the operator sets this by default. The user has to configure the helm chart to pass it in as an envar, and of course when deploying manually this must be set.
The challenge is: the helm chart is open source so any user could deploy using it, but the executor is part of a specific tier that the user may not have subscribed to. If we set the default in the helm chart, it might send mixed confusing messages where they cannot use the executor because of a licensing mismatch. At least with the docker executor they could investigate alternative methods.
We don't really have a good story about this right now, so inputs are welcomed cc @localstack/unicorn
| |---------------------|------|------| | ||
| | **DIY (YAML manifests)** | · Full control over Kubernetes configuration and resources | · Time-consuming to set up and maintain<br> · Manual updates and lifecycle management | | ||
| | **Helm chart** | · Simplifies deployment using templates and `values.yaml`<br> · Supports versioning, upgrades, and rollbacks<br> · Supports both LocalStack Community and Pro images | · Customization is limited to chart values and overrides | | ||
| | **Operator** | · Declarative, self-managed control plane<br> · Built-in validation, defaulting, and reconciliation logic | · Limited to the LocalStack Pro image only<br> · Steeper learning curve compared to Helm | |
There was a problem hiding this comment.
Is "steeper learning curve" strictly necessary? Is it always true when using an operator? The point of using the operator is simplicity and a steeper learning curve seems to defeat that purpose.
There was a problem hiding this comment.
Both technologies require creating a YAML manifest with some domain specific settings (i.e. the settings vary from project to project, e.g. LocalStack compared to installing the postgres operator). However the operator requires installing into the cluster, whereas helm operates from outside.
Perhaps this would be a better wording?
| | **Operator** | · Declarative, self-managed control plane<br> · Built-in validation, defaulting, and reconciliation logic | · Limited to the LocalStack Pro image only<br> · Steeper learning curve compared to Helm | | |
| | **Operator** | · Declarative, self-managed control plane<br> · Built-in validation, defaulting, and reconciliation logic | · Limited to the LocalStack Pro image only<br> · Requires in-cluster component (controller) | |
or something?
|
|
||
| ## Help & Support | ||
|
|
||
| LocalStack Pro (with a valid license) is the only version that provides: |
There was a problem hiding this comment.
It reads to me like all pro image license give k8s support, but it could just be me.
There was a problem hiding this comment.
Got it, what is the correct way to write this then? should it say "enterprise"?
src/content/docs/aws/enterprise/kubernetes/kubernetes-operator.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Simon Walker <simon.walker@localstack.cloud>
src/content/docs/aws/enterprise/kubernetes/deploy-helm-chart.md
Outdated
Show resolved
Hide resolved
src/content/docs/aws/enterprise/kubernetes/kubernetes-operator.md
Outdated
Show resolved
Hide resolved
src/content/docs/aws/enterprise/kubernetes/deploy-helm-chart.md
Outdated
Show resolved
Hide resolved
src/content/docs/aws/enterprise/kubernetes/kubernetes-operator.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Simon Walker <simon.walker@localstack.cloud>
src/content/docs/aws/enterprise/kubernetes/deploy-helm-chart.md
Outdated
Show resolved
Hide resolved
Updated installation instructions for LocalStack Pro and added note about customizing the chart with a values.yaml file.
Added a section on certificate issues when spawning child pods, including error details and a solution for configuring NO_PROXY.
Co-authored-by: Simon Walker <simon.walker@localstack.cloud>
quetzalliwrites
left a comment
quetzalliwrites
left a comment
There was a problem hiding this comment.
Ok, ready for your review again @mmaureenliu @simonrw @nik-localstack @localstack/unicorn
quetzalliwrites
requested review from
mmaureenliu,
nik-localstack and
simonrw
4 participants
Preview URL w/ new k8 docs:
https://6852d11b.localstack-docs.pages.dev/aws/enterprise/kubernetes/
Resolves: