🤖 fix: stop generating aggregation CRDs in manifests (#68)

## Summary
Stop generating `aggregation.coder.com` CRDs into `config/crd/bases`,
delete the previously generated aggregation CRD manifests, and keep demo
flows fail-fast when stale APIService/CRD conflicts exist.

## Background
For APIService-backed aggregated resources (`codertemplates`,
`coderworkspaces`), same-group CRDs in `config/crd/bases` caused
unreliable read/discovery behavior in demos when both mechanisms were
present. We want `kubectl apply -f config/crd/bases/` to remain simple
and safe.

## Implementation
- Updated `hack/update-manifests.sh`:
- CRD generation now runs only against `./api/v1alpha1` (operator-owned
`coder.com/*` APIs)
  - RBAC generation remains repo-wide (`./...`)
- Removed generated aggregation CRDs:
  - `config/crd/bases/aggregation.coder.com_codertemplates.yaml`
  - `config/crd/bases/aggregation.coder.com_coderworkspaces.yaml`
- Kept a defensive guard in `hack/kind-dev.sh`:
- Detects `APIService v1alpha1.aggregation.coder.com` + aggregation CRD
coexistence
  - Fails with explicit cleanup command
- Simplified docs back to approachable CRD command usage (`kubectl apply
-f config/crd/bases/`) while keeping a focused troubleshooting note for
stale conflict cleanup.

## Validation
- `make verify-vendor`
- `make test`
- `make build`
- `make lint`
- `make docs-check`
- `make manifests`
- `bash -n ./hack/kind-dev.sh`
- `CLUSTER_NAME=coder-k8s-smoke-20260212 ./hack/kind-dev.sh up`

## Risks
Low-to-moderate:
- Behavior of generated CRDs intentionally narrows to controller-owned
APIs only.
- Any external workflow that relied on generated aggregation CRD files
in `config/crd/bases` will need to use the APIService path instead
(which is the intended model).

---

_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