docs: add coder-logstream-kube docs and update k8s example template (#8675)

* docs: add kubestream docs and update example template

* make fmt

* add to template's README

* add the seperate page

* make fmt

* make fmt

* add namespace to deployment resource

* fmt

* add screenshots

* link docs in template

* Add remaining examples

* enable deployments requirement

* Update deployment-logs.md

* rewording

* fix spelling

* how?

* cleanup

* Update docs/platforms/kubernetes/deployment-logs.md

Co-authored-by: Ben Potter <ben@coder.com>

* suggestions

* use online link

* refine

---------

Co-authored-by: Eric <ericpaulsen@coder.com>
Co-authored-by: Ben Potter <ben@coder.com>

docs/platforms/kubernetes/deployment-logs.md

@@ -0,0 +1,59 @@
+# Kubernetes event logs
+
+To stream Kubernetes events into your workspace startup logs, you can use Coder's [`coder-logstream-kube`](https://github.com/coder/coder-logstream-kube) tool. `coder-logstream-kube` provides useful information about the workspace pod or deployment, such as:
+
+- Causes of pod provisioning failures, or why a pod is stuck in a pending state.
+- Visibility into when pods are OOMKilled, or when they are evicted.
+
+## Prerequisites
+
+`coder-logstream-kube` works best with the [`kubernetes_deployment`](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/deployment) Terraform resource, which requires the `coder` service account to have permission to create deployments. For example, if you use [Helm](https://coder.com/docs/v2/latest/install/kubernetes#install-coder-with-helm) to install Coder, you should set `coder.serviceAccount.enableDeployments=true` in your `values.yaml`
+
+```diff
+coder:
+serviceAccount:
+    workspacePerms: true
+-   enableDeployments: false
++   enableDeployments: true
+    annotations: {}
+    name: coder
+```
+
+> Note: This is only required for Coder versions < 0.28.0, as this will be the default value for Coder versions >= 0.28.0
+
+## Installation
+
+Install the `coder-kubestream-logs` helm chart on the cluster where the deployment is running.
+
+```shell
+helm repo add coder-logstream-kube https://helm.coder.com/logstream-kube
+helm install coder-logstream-kube coder-logstream-kube/coder-logstream-kube \
+    --namespace coder \
+    --set url=<your-coder-url-including-http-or-https>
+```
+
+## Example logs
+
+Here is an example of the logs you can expect to see in the workspace startup logs:
+
+### Normal pod deployment
+
+![normal pod deployment](./coder-logstream-kube-logs-normal.png)
+
+### Wrong image
+
+![Wrong image name](./coder-logstream-kube-logs-wrong-image.png)
+
+### Kubernetes quota exceeded
+
+![Kubernetes quota exceeded](./coder-logstream-kube-logs-quota-exceeded.png)
+
+### Pod crash loop
+
+![Pod crash loop](./coder-logstream-kube-logs-pod-crashed.png)
+
+## How it works
+
+Kubernetes provides an [informers](https://pkg.go.dev/k8s.io/client-go/informers) API that streams pod and event data from the API server.
+
+coder-logstream-kube listens for pod creation events with containers that have the CODER_AGENT_TOKEN environment variable set. All pod events are streamed as logs to the Coder API using the agent token for authentication. For more details, see the [coder-logstream-kube](https://github.com/coder/coder-logstream-kube) repository.

docs/platforms/kubernetes/index.md

@@ -18,7 +18,7 @@ From the dashboard, import the Kubernetes starter template:
 
 In the next screen, set the following template variables:
 
-- use_kubeconfig: `false` (The ServiceAccount will authorize Coder to create pods on your cluster)
+- `use_kubeconfig`: `false` (The ServiceAccount will authorize Coder to create pods on your cluster)
 - `namespace`: `coder` (or whatever namespace you deployed Coder on)
 
 ![Variables for Kubernetes template](../../images/platforms/kubernetes/template-variables.png)