🤖 feat: replace WorkspaceProxy with CoderWorkspaceProxy (#61)

## Summary
Replace the unreleased `WorkspaceProxy` CRD/controller with
`CoderWorkspaceProxy` as the single workspace-proxy API in
`coder.com/v1alpha1`.

## Background
`WorkspaceProxy` was still under development and had not been released.
Keeping both Kinds introduced unnecessary API/controller duplication and
naming inconsistency with other `Coder*` resources.

## Implementation
- Added `CoderWorkspaceProxy` API roots and registration.
- Switched controller wiring to `CoderWorkspaceProxyReconciler` only.
- Renamed/generated CRD, sample, and API reference docs to
`CoderWorkspaceProxy`.
- Removed legacy `WorkspaceProxy` root kind/list, CRD, sample, docs,
controller, and controller tests.
- Updated RBAC and scheme tests to the new Kind.

## Validation
- `make verify-vendor`
- `make test`
- `make build`
- `make lint`
- `make docs-check` (run with generated docs staged)

## Risks
Low-to-moderate: this removes an unreleased API surface and consolidates
onto one Kind. Main regression risk is controller behavior drift during
the rename, mitigated by preserving reconciliation logic and running
full local validation.

---

<details>
<summary>📋 Implementation Plan</summary>

# Plan: Rename `WorkspaceProxy` → `CoderWorkspaceProxy`

## Context / Why
Today the operator exposes a namespaced CRD Kind `WorkspaceProxy` in
`coder.com/v1alpha1`, while most other public CRDs in this repo use a
`Coder*` prefix (e.g. `CoderControlPlane`, `CoderProvisioner`,
`CoderWorkspace`, `CoderTemplate`). This is inconsistent in docs and
creates Go naming collisions/confusion with upstream Coder concepts
(there is also a `codersdk.WorkspaceProxy`).

Goal: introduce a `CoderWorkspaceProxy` CRD and controller as the
long-term supported API, with a practical migration path from the
existing `WorkspaceProxy`.

## Evidence (repo facts)
- Go API type + kubebuilder markers live in
`api/v1alpha1/workspaceproxy_types.go` (`type WorkspaceProxy struct {
... }`, `+kubebuilder:resource:scope=Namespaced`).
- Controller lives in `internal/controller/workspaceproxy_controller.go`
and is wired in `internal/app/controllerapp/controllerapp.go`.
- Generated artifacts that will change:
  - CRD manifest: `config/crd/bases/coder.com_workspaceproxies.yaml`
  - Deepcopy: `api/v1alpha1/zz_generated.deepcopy.go`
  - API reference docs: `docs/reference/api/workspaceproxy.md`
  - Docs nav: `mkdocs.yml`
- Kubernetes **does not allow changing** a CRD’s `spec.names.kind` /
`plural` in-place (they are immutable). Therefore a pure “rename”
requires either:
  1) destructive delete/recreate of the existing CRD, or
  2) introducing a *new* CRD (new plural) and migrating users.

## Recommended approach (non-destructive): new CRD + migration, then
remove old

### Phase 1 (Release N): Add `CoderWorkspaceProxy` alongside
`WorkspaceProxy`

#### 1) Add new API types (new Kind + plural)
- **File(s):**
- Add `api/v1alpha1/coderworkspaceproxy_types.go` (or extend
`workspaceproxy_types.go` if preferred).
- **New root objects:**
  - `CoderWorkspaceProxy`
  - `CoderWorkspaceProxyList`
- **Reuse existing spec/status structs** (`WorkspaceProxySpec`,
`WorkspaceProxyStatus`, `ProxyBootstrapSpec`) to avoid duplicating
schema and docs.
- **kubebuilder markers:** ensure the new resource gets its own plural
(so it can coexist with the old CRD):

```go
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
// +kubebuilder:object:root=true
// +kubebuilder:resource:path=coderworkspaceproxies,scope=Namespaced
// +kubebuilder:subresource:status
//
// CoderWorkspaceProxy is the schema for Coder workspace proxy resources.
// (Replacement for WorkspaceProxy.)
type CoderWorkspaceProxy struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    Spec   WorkspaceProxySpec   `json:"spec,omitempty"`
    Status WorkspaceProxyStatus `json:"status,omitempty"`
}
```

- Register the new types with the scheme (either via a new `init()` or
existing one):
- `SchemeBuilder.Register(&CoderWorkspaceProxy{},
&CoderWorkspaceProxyList{})`

#### 2) Generate new CRD + deepcopy
- Run generators:
  - `make codegen`
  - `make manifests`
- Expected outputs:
- New CRD file: `config/crd/bases/coder.com_coderworkspaceproxies.yaml`
  - Existing CRD file remains for `workspaceproxies.coder.com`.

#### 3) Add a new controller for `CoderWorkspaceProxy`
- **File:** `internal/controller/coderworkspaceproxy_controller.go`
- **Type:** `CoderWorkspaceProxyReconciler`
- Implementation choices:
- Prefer factoring shared logic out of the current
`WorkspaceProxyReconciler` into helper functions (naming/labels, secret
reads, deployment/service reconcile) so the behavior stays identical and
future fixes apply to both during the transition.
- **RBAC markers:** add rules for `coderworkspaceproxies` (+
status/finalizers).

#### 4) Handle adoption of existing child resources (important for
smooth migration)
Existing `WorkspaceProxy` instances may already own a
Deployment/Service/Secret via a controller ownerRef. When a user creates
a new `CoderWorkspaceProxy` with the same name, the new controller
should “adopt” those children instead of failing on
`SetControllerReference`.

- Add a small “adopt if owned-by WorkspaceProxy” helper used by all
child reconcile paths:

```go
func adoptIfOwnedByWorkspaceProxy(obj metav1.Object, legacy *coderv1alpha1.WorkspaceProxy) bool {
    // Pseudocode:
    // - Inspect obj.GetOwnerReferences() for controller=true entry.
    // - If controllerRef is WorkspaceProxy and matches legacy name/uid: replace it with ownerRef to new CoderWorkspaceProxy.
    // - Return true if adoption happened.
    // - If controllerRef exists but is NOT legacy WorkspaceProxy: return false and let caller error (defensive).
}
```

- Defensive programming expectations:
- If the existing controllerRef is *not* the legacy `WorkspaceProxy`,
fail fast (this prevents accidental adoption of unrelated resources).

#### 5) Wire controller + keep legacy behavior clear
- Update `internal/app/controllerapp/controllerapp.go` to set up the new
reconciler.
- Decide legacy reconciliation policy:
- **Recommended:** stop running the old `WorkspaceProxyReconciler` in
the manager (so we don’t have two controllers fighting over the same
child resources), but keep the CRD/types temporarily so users can still
read/export their legacy objects.
- Optionally add a minimal “legacy warning” reconciler that only sets a
`Deprecated` Condition on `WorkspaceProxy` objects (no child management)
to guide users.

#### 6) Update/extend tests
- Update controller tests to cover the new Kind:
- Either parameterize the existing tests in
`internal/controller/workspaceproxy_controller_test.go`, or add a
parallel file (e.g.
`internal/controller/coderworkspaceproxy_controller_test.go`).
- Add a focused adoption test to prevent regressions:
1. Create a legacy `WorkspaceProxy` and reconcile once to create
children.
  2. Create a `CoderWorkspaceProxy` with the same name/namespace.
3. Reconcile the new controller and assert child resources’ controller
ownerRef was moved from `WorkspaceProxy` → `CoderWorkspaceProxy`.

### Phase 2 (same release N): Update samples + docs to prefer
`CoderWorkspaceProxy`

#### 7) Samples / manifests
- Add a new sample:
- `config/samples/coder_v1alpha1_coderworkspaceproxy.yaml` (Kind
`CoderWorkspaceProxy`).
- Keep the old sample for one release, but mark it deprecated in
comments.

#### 8) Docs + docs nav
- Update:
- `README.md`: replace `WorkspaceProxy` mentions with
`CoderWorkspaceProxy`.
- `mkdocs.yml`: generated API nav entry should become
`CoderWorkspaceProxy: reference/api/coderworkspaceproxy.md`.
- Regenerate API reference docs:
  - `make docs-reference`
  - (and confirm `make docs-check` passes)

### Phase 3 (Release N+1): Remove legacy `WorkspaceProxy`

#### 9) Remove legacy API + CRD
- Delete/stop generating the legacy `WorkspaceProxy` root types and its
CRD.
- Remove legacy controller code and any remaining references.
- Regenerate:
  - `make codegen`
  - `make manifests`
  - `make docs-reference`

## Migration guide (for Release N)
1. Upgrade the operator (now serving both CRDs).
2. For each legacy `WorkspaceProxy` named `X`:
- Create a `CoderWorkspaceProxy` with the **same name/namespace** and
the same spec.
- Verify the new controller has adopted the existing
Deployment/Service/Secret and the status becomes Ready.
- Delete the legacy `WorkspaceProxy` once stable **after** adoption
completes (otherwise Kubernetes GC may delete the child
Deployment/Service/Secret).

<details>
<summary>Alternative (development-only): destructive rename</summary>

Because CRD Kind/Plural are immutable, the only way to keep the *same*
REST resource `workspaceproxies.coder.com` while changing the Kind to
`CoderWorkspaceProxy` is:
1) export all existing `WorkspaceProxy` objects,
2) delete the CRD (which deletes all CRs),
3) recreate the CRD with the new Kind, and
4) re-apply the exported objects (updated Kind).

This is not recommended for production clusters.

</details>

## Validation (what to run when implementing)
- `make test`
- `make test-integration` (if controller behavior changes materially)
- `make lint`
- `make build`
- `make verify-vendor` (should be a no-op unless deps changed)
- `make manifests && git diff --exit-code config/` (confirm generated
output is committed)
- `make docs-reference && make docs-check`

</details>

---

_Generated with [`mux`](https://github.com/coder/mux) • Model:
`openai:gpt-5.3-codex` • Thinking: `xhigh` • Cost: `$0.62`_

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

Author: ThomasK33

.cspell.json

@@ -19,6 +19,8 @@
     "codertemplates",
     "coderworkspace",
     "coderworkspaces",
+    "coderworkspaceproxy",
+    "coderworkspaceproxies",
     "coderprovisioner",
     "coderprovisioners",
     "controllerapp",

README.md

@@ -10,7 +10,7 @@
 `coder-k8s` is a Go-based Kubernetes control-plane project with two app modes:
 
 - A `controller-runtime` operator for managing `CoderControlPlane` and
-  `WorkspaceProxy` resources (`coder.com/v1alpha1`).
+  `CoderWorkspaceProxy` resources (`coder.com/v1alpha1`).
 - An aggregated API server for `CoderWorkspace` and `CoderTemplate` resources
   (`aggregation.coder.com/v1alpha1`).
 

api/v1alpha1/workspaceproxy_types.go api/v1alpha1/coderworkspaceproxy_types.goapi/v1alpha1/workspaceproxy_types.go renamed to api/v1alpha1/coderworkspaceproxy_types.go

@@ -71,11 +71,11 @@ type WorkspaceProxyStatus struct {
 
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 // +kubebuilder:object:root=true
-// +kubebuilder:resource:scope=Namespaced
+// +kubebuilder:resource:path=coderworkspaceproxies,scope=Namespaced
 // +kubebuilder:subresource:status
 
-// WorkspaceProxy is the schema for Coder workspace proxy resources.
-type WorkspaceProxy struct {
+// CoderWorkspaceProxy is the schema for Coder workspace proxy resources.
+type CoderWorkspaceProxy struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
@@ -86,13 +86,13 @@ type WorkspaceProxy struct {
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 // +kubebuilder:object:root=true
 
-// WorkspaceProxyList contains a list of WorkspaceProxy objects.
-type WorkspaceProxyList struct {
+// CoderWorkspaceProxyList contains a list of CoderWorkspaceProxy objects.
+type CoderWorkspaceProxyList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`
-	Items           []WorkspaceProxy `json:"items"`
+	Items           []CoderWorkspaceProxy `json:"items"`
 }
 
 func init() {
-	SchemeBuilder.Register(&WorkspaceProxy{}, &WorkspaceProxyList{})
+	SchemeBuilder.Register(&CoderWorkspaceProxy{}, &CoderWorkspaceProxyList{})
 }

api/v1alpha1/zz_generated.deepcopy.go

@@ -4,20 +4,20 @@ kind: CustomResourceDefinition
 metadata:
   annotations:
     controller-gen.kubebuilder.io/version: v0.20.0
-  name: workspaceproxies.coder.com
+  name: coderworkspaceproxies.coder.com
 spec:
   group: coder.com
   names:
-    kind: WorkspaceProxy
-    listKind: WorkspaceProxyList
-    plural: workspaceproxies
-    singular: workspaceproxy
+    kind: CoderWorkspaceProxy
+    listKind: CoderWorkspaceProxyList
+    plural: coderworkspaceproxies
+    singular: coderworkspaceproxy
   scope: Namespaced
   versions:
   - name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: WorkspaceProxy is the schema for Coder workspace proxy resources.
+        description: CoderWorkspaceProxy is the schema for Coder workspace proxy resources.
         properties:
           apiVersion:
             description: |-

…rd/bases/coder.com_workspaceproxies.yaml …ses/coder.com_coderworkspaceproxies.yamlconfig/crd/bases/coder.com_workspaceproxies.yaml renamed to config/crd/bases/coder.com_coderworkspaceproxies.yaml config/crd/bases/coder.com_workspaceproxies.yaml renamed to config/crd/bases/coder.com_coderworkspaceproxies.yaml

@@ -71,7 +71,7 @@ rules:
   resources:
   - codercontrolplanes
   - coderprovisioners
-  - workspaceproxies
+  - coderworkspaceproxies
   verbs:
   - create
   - delete
@@ -85,15 +85,15 @@ rules:
   resources:
   - codercontrolplanes/finalizers
   - coderprovisioners/finalizers
-  - workspaceproxies/finalizers
+  - coderworkspaceproxies/finalizers
   verbs:
   - update
 - apiGroups:
   - coder.com
   resources:
   - codercontrolplanes/status
   - coderprovisioners/status
-  - workspaceproxies/status
+  - coderworkspaceproxies/status
   verbs:
   - get
   - patch

config/rbac/role.yaml

@@ -1,11 +1,11 @@
 apiVersion: coder.com/v1alpha1
-kind: WorkspaceProxy
+kind: CoderWorkspaceProxy
 metadata:
-  name: workspaceproxy-sample
+  name: coderworkspaceproxy-sample
   namespace: default
 spec:
   image: "ghcr.io/coder/coder:latest"
   primaryAccessURL: "https://coder.example.com"
   proxySessionTokenSecretRef:
-    name: workspaceproxy-token
+    name: coderworkspaceproxy-token
     key: token

…mples/coder_v1alpha1_workspaceproxy.yaml …/coder_v1alpha1_coderworkspaceproxy.yamlconfig/samples/coder_v1alpha1_workspaceproxy.yaml renamed to config/samples/coder_v1alpha1_coderworkspaceproxy.yaml config/samples/coder_v1alpha1_workspaceproxy.yaml renamed to config/samples/coder_v1alpha1_coderworkspaceproxy.yaml

@@ -1,12 +1,12 @@
 <!-- Code generated by hack/update-reference-docs.sh using github.com/elastic/crd-ref-docs. DO NOT EDIT. -->
 
-# `WorkspaceProxy`
+# `CoderWorkspaceProxy`
 
 ## API identity
 
 - Group/version: `coder.com/v1alpha1`
-- Kind: `WorkspaceProxy`
-- Resource: `workspaceproxies`
+- Kind: `CoderWorkspaceProxy`
+- Resource: `coderworkspaceproxies`
 - Scope: namespaced
 
 ## Spec
@@ -53,5 +53,5 @@
 
 ## Source
 
-- Go type: `api/v1alpha1/workspaceproxy_types.go`
-- Generated CRD: `config/crd/bases/coder.com_workspaceproxies.yaml`
+- Go type: `api/v1alpha1/coderworkspaceproxy_types.go`
+- Generated CRD: `config/crd/bases/coder.com_coderworkspaceproxies.yaml`

docs/reference/api/workspaceproxy.md docs/reference/api/coderworkspaceproxy.mddocs/reference/api/workspaceproxy.md renamed to docs/reference/api/coderworkspaceproxy.md

@@ -95,13 +95,13 @@ func SetupControllers(mgr manager.Manager) error {
 		return fmt.Errorf("unable to create controller: %w", err)
 	}
 
-	workspaceProxyReconciler := &controller.WorkspaceProxyReconciler{
+	coderWorkspaceProxyReconciler := &controller.CoderWorkspaceProxyReconciler{
 		Client:          client,
 		Scheme:          managerScheme,
 		BootstrapClient: coderbootstrap.NewSDKClient(),
 	}
-	if err := workspaceProxyReconciler.SetupWithManager(mgr); err != nil {
-		return fmt.Errorf("unable to create workspace proxy controller: %w", err)
+	if err := coderWorkspaceProxyReconciler.SetupWithManager(mgr); err != nil {
+		return fmt.Errorf("unable to create coder workspace proxy controller: %w", err)
 	}
 
 	provisionerReconciler := &controller.CoderProvisionerReconciler{