From df6a33ad376425d66d3d0ae4c876fb5f57e476b4 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Mon, 24 Aug 2026 08:24:26 -0400 Subject: [PATCH] docs: fix broken extending-templates examples (dynamic-parameters, docker-in-workspaces) (#28100) ## Summary Fixes broken examples on the `extending-templates` pages surfaced by the DOCS-637 runtime drift sweep, and completes the dangling `external-auth` reference. Verified against `main` and the CLI source (`coder templates init --id`, `coder templates push`). ## Changes | Page | Fix | |------|-----| | `dynamic-parameters.md` | The **Dynamic Validation** snippet referenced an undefined `show_cpu_cores` through a stray `count = data.coder_parameter.show_cpu_cores.value ? 1 : 0` line copied from the earlier Hide/Show Options example. Standalone copy failed `terraform validate`. Removed the `count` line (and its misleading "Only show this parameter" comment) so the snippet is self-contained. The valid occurrence in the Hide/Show example (where `show_cpu_cores` is defined) is untouched. | | `docker-in-workspaces.md` | The rootless Podman step used `echo "kubernetes-with-podman" \| coder templates init`, but `kubernetes-with-podman` isn't a built-in starter id, so the command scaffolds nothing. Step 4 now starts from the built-in `kubernetes` starter (`coder templates init --id kubernetes`) and shows the minimal Podman delta inline: the maintained `codercom/example-podman:ubuntu` base image, the `container.apparmor.security.beta.kubernetes.io/dev = unconfined` pod annotation, and a `github.com/fuse` device limit. The starter already runs as UID/GID 1000 with `run_as_non_root`, which rootless Podman needs. Also switches the deprecated `coder templates create` to `coder templates push`. Follow-up from review: swapped `ghcr.io/coder/podman` for the maintained `codercom/example-podman:ubuntu` image and linked its source, added a note that the AppArmor annotation is deprecated on Kubernetes 1.30+ (`securityContext.appArmorProfile`), and added an EKS Auto Mode caveat to the Bottlerocket section. | | `external-auth.md` | The **External Auth Providers** sentence dead-ended at "...in the Coder Control Plane. See" with no link. Completed it with a link to the admin External Authentication page (`../../external-auth/index.md`), the target chosen in review. | ## Dependency The `docker-in-workspaces.md` example now references `codercom/example-podman:ubuntu`, published by coder/images#339. That PR is approved but should merge (and publish the image to Docker Hub) before this PR merges, so the docs don't point at an image that doesn't exist yet. Linear: https://linear.app/codercom/issue/DOCS-645 > This PR was created with AI assistance (Coder Agents). --------- Co-authored-by: Ben Potter Co-authored-by: Ben Potter --- .../docker-in-workspaces.md | 70 +++++++++++++++++-- .../extending-templates/dynamic-parameters.md | 3 - .../extending-templates/external-auth.md | 2 + 3 files changed, 66 insertions(+), 9 deletions(-) diff --git a/docs/admin/templates/extending-templates/docker-in-workspaces.md b/docs/admin/templates/extending-templates/docker-in-workspaces.md index 22f7ad709fc..f386ee60410 100644 --- a/docs/admin/templates/extending-templates/docker-in-workspaces.md +++ b/docs/admin/templates/extending-templates/docker-in-workspaces.md @@ -247,14 +247,66 @@ Before using Podman, please review the following documentation: 3. For systems running SELinux (typically Fedora-, CentOS-, and Red Hat-based systems), you might need to disable SELinux or set it to permissive mode. -4. Use this - [kubernetes-with-podman](https://github.com/coder/community-templates/tree/main/kubernetes-podman) - example template, or make your own. +4. Create a template from the built-in `kubernetes` starter, then adapt it for rootless Podman: ```sh - echo "kubernetes-with-podman" | coder templates init - cd ./kubernetes-with-podman - coder templates create + coder templates init --id kubernetes ./kubernetes-podman + cd ./kubernetes-podman + ``` + + The `kubernetes` starter already runs the workspace pod as a non-root user (`run_as_user = 1000`, `fs_group = 1000`, `run_as_non_root = true`), which rootless Podman requires. In the generated `main.tf`, apply the Podman changes to the `kubernetes_deployment_v1.main` pod template (marked `# Podman` in the following snippet): + + ```tf + spec { + template { + metadata { + # ... + # Podman: allow Podman to create nested containers. The annotation + # key must match the container name below (`dev`). + annotations = { + "container.apparmor.security.beta.kubernetes.io/dev" = "unconfined" + } + } + spec { + # The starter already sets these; rootless Podman requires them. + security_context { + run_as_user = 1000 + fs_group = 1000 + run_as_non_root = true + } + + container { + name = "dev" + # Podman: base image with Podman and fuse-overlayfs preinstalled. + image = "codercom/example-podman:ubuntu" + # ... + resources { + limits = { + # ... + # Podman: FUSE device exposed by smarter-device-manager (step 1). + "github.com/fuse" = "1" + } + } + } + } + } + } + ``` + + The `codercom/example-podman` image is built and maintained in + [`coder/images`](https://github.com/coder/images). + + > On Kubernetes 1.30+, the + > `container.apparmor.security.beta.kubernetes.io/` annotation is + > deprecated in favor of the `securityContext.appArmorProfile` field. The + > annotation still works and remains the most broadly compatible option, so + > switch to the field once your cluster and Terraform Kubernetes provider + > both support it. + + Push the template to your deployment: + + ```sh + coder templates push ``` > For more information around the requirements of rootless podman pods, see: @@ -299,6 +351,12 @@ spec: sysctl = { "user.max_user_namespaces" = "65536" } ``` +### Rootless Podman on EKS Auto Mode + +The `EC2NodeClass` above applies to self-managed Karpenter nodes. On EKS Auto Mode, the built-in `NodeClass` (`eks.amazonaws.com`) doesn't expose `userData` or kernel sysctls, so `user.max_user_namespaces` stays at `0` with no way to raise it on those nodes. Run Podman workspaces on a separate managed node group instead; the default AL2023 AMIs ship with user namespaces enabled. + +> On a brand-new Auto Mode cluster, install the `vpc-cni` and `kube-proxy` add-ons before your managed node group can reach `Ready`. + ## Privileged sidecar container A diff --git a/docs/admin/templates/extending-templates/dynamic-parameters.md b/docs/admin/templates/extending-templates/dynamic-parameters.md index 6d0e47ed999..5e415cec9b5 100644 --- a/docs/admin/templates/extending-templates/dynamic-parameters.md +++ b/docs/admin/templates/extending-templates/dynamic-parameters.md @@ -526,9 +526,6 @@ data "coder_parameter" "git_repo" { } data "coder_parameter" "cpu_cores" { - # Only show this parameter if the previous box is selected. - count = data.coder_parameter.show_cpu_cores.value ? 1 : 0 - name = "cpu_cores" display_name = "CPU Cores" type = "number" diff --git a/docs/admin/templates/extending-templates/external-auth.md b/docs/admin/templates/extending-templates/external-auth.md index 29190d4f52b..e2fc1be4435 100644 --- a/docs/admin/templates/extending-templates/external-auth.md +++ b/docs/admin/templates/extending-templates/external-auth.md @@ -9,6 +9,8 @@ service that requires authentication. External auth providers are configured using environment variables in the Coder Control Plane. See +[External Authentication](../../external-auth/index.md) for how to configure +them. ## Git Providers