🤖 fix: remove aggregation CRD generation and guard demo conflicts

Stop generating aggregation.coder.com CRDs into config/crd/bases and delete
previously generated aggregation CRD manifests. This makes `kubectl apply -f
config/crd/bases/` safe for demo workflows while keeping docs approachable.

Also add a fail-fast guard in hack/kind-dev.sh that detects stale
APIService+aggregation-CRD conflicts and prints the exact cleanup command.

---

_Generated with `mux` • Model: `openai:gpt-5.3-codex` • Thinking: `xhigh` • Cost: `$0.00`_

<!-- mux-attribution: model=openai:gpt-5.3-codex thinking=xhigh costs=0.00 -->

Author: ThomasK33

config/crd/bases/aggregation.coder.com_codertemplates.yaml

@@ -40,6 +40,30 @@ kubectl apply -f config/crd/bases/
   kubectl get clusterrolebinding coder-k8s-controller
   ```
 
+## Aggregated `codertemplates` / `coderworkspaces` reads are empty or inconsistent
+
+If `kubectl get codertemplates.aggregation.coder.com` or `kubectl get coderworkspaces.aggregation.coder.com` returns empty data unexpectedly, check for CRD/APIService conflicts.
+
+When both of these exist at once:
+
+- `APIService` `v1alpha1.aggregation.coder.com`
+- CRDs `codertemplates.aggregation.coder.com` and/or `coderworkspaces.aggregation.coder.com`
+
+Kubernetes may not route reads the way you expect for demos.
+
+```bash
+kubectl get apiservice v1alpha1.aggregation.coder.com
+kubectl get crd codertemplates.aggregation.coder.com coderworkspaces.aggregation.coder.com
+```
+
+For APIService-based demos, remove the conflicting aggregation CRDs:
+
+```bash
+kubectl delete crd codertemplates.aggregation.coder.com coderworkspaces.aggregation.coder.com
+kubectl apply -f deploy/apiserver-apiservice.yaml
+kubectl wait --for=condition=Available apiservice/v1alpha1.aggregation.coder.com --timeout=120s
+```
+
 ## Aggregated APIService shows `False` / `Unavailable`
 
 - Ensure the deployment and service exist:

config/crd/bases/aggregation.coder.com_coderworkspaces.yaml

@@ -76,6 +76,29 @@ ensure_cluster_node_image_matches() {
 	exit 1
 }
 
+assert_no_aggregation_resource_conflict() {
+	local has_apiservice="false"
+	local has_template_crd="false"
+	local has_workspace_crd="false"
+
+	if kubectl_ctx get apiservice v1alpha1.aggregation.coder.com >/dev/null 2>&1; then
+		has_apiservice="true"
+	fi
+	if kubectl_ctx get crd codertemplates.aggregation.coder.com >/dev/null 2>&1; then
+		has_template_crd="true"
+	fi
+	if kubectl_ctx get crd coderworkspaces.aggregation.coder.com >/dev/null 2>&1; then
+		has_workspace_crd="true"
+	fi
+
+	if [[ "${has_apiservice}" == "true" && ( "${has_template_crd}" == "true" || "${has_workspace_crd}" == "true" ) ]]; then
+		echo "assertion failed: detected aggregation API conflict in ${KUBE_CONTEXT}: APIService v1alpha1.aggregation.coder.com and aggregation.coder.com CRDs are both installed." >&2
+		echo "Delete conflicting CRDs before aggregated API demos:" >&2
+		echo "  kubectl --context ${KUBE_CONTEXT} delete crd codertemplates.aggregation.coder.com coderworkspaces.aggregation.coder.com" >&2
+		exit 1
+	fi
+}
+
 build_binary() {
 	local resolved_goarch="${GOARCH}"
 	if [[ -z "${resolved_goarch}" ]]; then
@@ -115,8 +138,10 @@ cmd_up() {
 	kubectl config use-context "${KUBE_CONTEXT}" >/dev/null
 
 	kubectl_ctx wait --for=condition=Ready node --all --timeout="${NODE_READY_TIMEOUT}"
+	assert_no_aggregation_resource_conflict
 
 	kubectl_ctx apply -f config/e2e/namespace.yaml
+	# config/crd/bases intentionally contains only operator-owned coder.com CRDs.
 	kubectl_ctx apply -f config/crd/bases/
 	kubectl_ctx apply -f config/rbac/
 

docs/how-to/troubleshooting.md

@@ -14,9 +14,15 @@ if [[ ! -d "${SCRIPT_ROOT}/internal/controller" ]]; then
 fi
 
 cd "${SCRIPT_ROOT}"
+
+# Generate CRDs for operator-owned coder.com APIs only.
 GOFLAGS=-mod=vendor go run ./vendor/sigs.k8s.io/controller-tools/cmd/controller-gen \
 	crd:crdVersions=v1 \
+	paths=./api/v1alpha1 \
+	output:crd:artifacts:config=config/crd/bases
+
+# Generate RBAC across the repo.
+GOFLAGS=-mod=vendor go run ./vendor/sigs.k8s.io/controller-tools/cmd/controller-gen \
 	rbac:roleName=manager-role \
 	paths=./... \
-	output:crd:artifacts:config=config/crd/bases \
 	output:rbac:artifacts:config=config/rbac