Stage 1: TerdutServer full lifecycle (Deployment, Service, both database

paths, self-registration bootstrap)

Replaces the bring-your-own-only Stage 1 (commit 1be7cf2) wholesale, per
the redesign in the previous two commits: the operator creates every
server it manages, so self-registration (DESIGN.md §6) is the only
bootstrap path, and Deployment/Service/database management builds
together with it (ROADMAP.md Stage 1) rather than behind a separate
later stage.

Grounded in terdut-server's actual chart (charts/terdut-server/templates/
deployment.yaml, values.yaml), not reconstructed from DESIGN.md's
illustrative YAML alone -- env var names, the password-via-PGPASSWORD
convention, the Recreate deployment strategy, /healthz probes, and the
TERDUT_OPERATOR_MODE=true decision (always on here, unlike the chart's
default-off: every write this operator's own future controllers make
goes through a service account already) all match that source exactly.

- api/v1alpha1: full TerdutServerSpec (image, replicas, networking,
  database, sweeper, deadman, notify, oidc, passwordLogin, allowedTeams).
  spec.database is a oneOf (dsn xor postgresClusterRef) via CEL
  XValidation. No spec.credentialsSecretRef -- removed entirely in the
  prior redesign commit, not carried forward.
- internal/controller:
  - terdutserver_deployment.go: Deployment + Service via CreateOrUpdate,
    owned (OwnerReference), env built field-for-field against the chart.
  - terdutserver_database.go: both §8 paths. The Zalando path resolves
    the postgresql.acid.zalan.do CR by convention (database/role both
    "terdut", matching every DESIGN.md example) and only ever confirms
    its generated credentials Secret exists -- never reads the value,
    same "wire a secretKeyRef, don't read it" posture the DSN path takes.
    classifyClusterGetError is its own function specifically so the
    CRD-not-installed case (meta.IsNoMatchError) is unit-testable without
    a real client.
  - terdutserver_bootstrap.go: self-registration, checkpointed against
    both real crash windows (DESIGN.md §6 point 1) -- an admin-key
    checkpoint Secret, and adopt-via-GET+mint-new-key on a 409 from
    creating the service account. BootstrapStateLost is its own error
    type so Reconcile can route it to a condition instead of an infinite
    retry.
  - terdutserver_controller.go: ties it together -- finalizer add, DB
    resolution, Deployment/Service reconcile, wait for a ready replica,
    bootstrap, Ready/Bootstrapped/DatabaseReady conditions. Finalizer on
    delete only removes the generated Secrets: terdut-server's API can't
    delete a user or service account, only revoke keys, so there's
    nothing server-side to undo.
- internal/tdclient: added Bootstrap, CreateInstanceServiceAccount,
  GetServiceAccountByName, CreateServiceAccountKey, matching
  terdut-server's real handlers' request/response shapes (internal/api/
  users.go, service_accounts.go in that repo) field-for-field.
- Tests: envtest suite covering the full DSN-path lifecycle end to end
  (finalizer -> Deployment/Service -> simulated readiness -> real
  bootstrap against an httptest.Server fake), the adopt-on-409 recovery
  path, BootstrapStateLost, both Zalando outcomes (cluster not found;
  cluster + Secret found -> real DSN -> Ready), and deletion. A minimal
  test-only stub of the Zalando CRD (internal/controller/testdata) lets
  envtest create fixture objects without a real postgres-operator
  installed. 74.0%/44.7% coverage, 0 lint issues.
- Two things scoped down from §8's full ambition, called out in code and
  ROADMAP.md rather than silently dropped: no live watch on the
  Zalando-generated Secret for rotation (periodic resync notices
  eventually, not immediately), no Gateway API HTTPRoute creation from
  spec.networking (would add a new dependency; nothing about proving
  bootstrap works depends on external ingress existing). Both are
  near-term follow-ups.

Verified locally: make fmt lint test build all clean.

internal/controller/terdutserver_controller_test.go

@@ -2,43 +2,120 @@ package controller
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"net/http"
 	"net/http/httptest"
+	"sync"
 
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
+	appsv1 "k8s.io/api/apps/v1"
 	corev1 "k8s.io/api/core/v1"
-	apierrors "k8s.io/apimachinery/pkg/api/errors"
 	"k8s.io/apimachinery/pkg/api/meta"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
 	"k8s.io/apimachinery/pkg/types"
+	ctrl "sigs.k8s.io/controller-runtime"
 	"sigs.k8s.io/controller-runtime/pkg/reconcile"
 
 	terdutv1alpha1 "git.ryuvia.com/niklas/terdut-operator/api/v1alpha1"
+	"git.ryuvia.com/niklas/terdut-operator/internal/tdclient"
 )
 
-const (
-	// unusedEndpoint is a syntactically valid URL no test here ever expects
-	// to actually be dialed (the cases using it fail before reaching the
-	// server-reachability check).
-	unusedEndpoint = "http://unused.invalid"
-	// tokenKey is the data key every test's credentials Secret uses.
-	tokenKey = "token"
-)
+// fakeTerdutServer reproduces the exact stateful semantics of
+// /api/bootstrap, /api/service-accounts and /api/version that the
+// bootstrap flow depends on (DESIGN.md §6, §11: "terdut-server's REST API
+// is faked with a small httptest.Server per controller test ... matching
+// the real handlers' request/response shapes"), including the 403-after-
+// first-success and 409-on-name-conflict behavior the adopt-on-conflict
+// recovery path exists for.
+type fakeTerdutServer struct {
+	mu           sync.Mutex
+	bootstrapped bool
+	bootstrap403 bool // force every /api/bootstrap call to 403, even the first
+	nextID       int64
+	accounts     map[string]int64 // name -> id
+	keyMints     map[int64]int    // id -> number of keys minted so far
+}
 
-// fakeTerdutServer is an httptest.Server standing in for terdut-server's
-// GET /api/version, per DESIGN.md §11 ("terdut-server's REST API is faked
-// with a small httptest.Server per controller test ... no real Postgres or
-// real terdut-server binary needed for controller unit tests").
-func fakeTerdutServer(version string) *httptest.Server {
-	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/api/version" {
-			w.WriteHeader(http.StatusNotFound)
+func newFakeTerdutServer() (*fakeTerdutServer, *httptest.Server) {
+	f := &fakeTerdutServer{accounts: map[string]int64{}, keyMints: map[int64]int{}}
+	return f, httptest.NewServer(f)
+}
+
+func (f *fakeTerdutServer) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+
+	switch {
+	case r.URL.Path == "/api/version":
+		writeJSON(w, http.StatusOK, map[string]string{"version": "test"})
+
+	case r.URL.Path == "/api/bootstrap" && r.Method == http.MethodPost:
+		if f.bootstrapped || f.bootstrap403 {
+			writeJSON(w, http.StatusForbidden, map[string]string{"error": "bootstrap already completed"})
 			return
 		}
-		fmt.Fprintf(w, `{"version":%q}`, version) //nolint:errcheck
-	}))
+		f.bootstrapped = true
+		writeJSON(w, http.StatusCreated, tdclient.BootstrapResult{
+			APIKey: tdclient.APIKey{ID: 1, Name: "bootstrap", Key: "admin-key-raw"},
+		})
+
+	case r.URL.Path == "/api/service-accounts" && r.Method == http.MethodPost:
+		var req struct {
+			Name  string `json:"name"`
+			Scope string `json:"scope"`
+		}
+		_ = json.NewDecoder(r.Body).Decode(&req)
+		if _, exists := f.accounts[req.Name]; exists {
+			writeJSON(w, http.StatusConflict, map[string]string{"error": "a service account with that name already exists"})
+			return
+		}
+		f.nextID++
+		id := f.nextID
+		f.accounts[req.Name] = id
+		f.keyMints[id] = 1
+		writeJSON(w, http.StatusCreated, tdclient.CreateServiceAccountResult{
+			ServiceAccount: tdclient.ServiceAccount{ID: id, Name: req.Name, Scope: req.Scope},
+			Key:            tdclient.APIKey{ID: 1, Name: "initial", Key: fmt.Sprintf("instance-key-%d-initial", id)},
+		})
+
+	case r.URL.Path == "/api/service-accounts" && r.Method == http.MethodGet:
+		name := r.URL.Query().Get("name")
+		id, exists := f.accounts[name]
+		if !exists {
+			writeJSON(w, http.StatusOK, []tdclient.ServiceAccount{})
+			return
+		}
+		writeJSON(w, http.StatusOK, []tdclient.ServiceAccount{{ID: id, Name: name, Scope: "instance"}})
+
+	default:
+		if id, name, ok := parseKeysPath(r.URL.Path); ok && r.Method == http.MethodPost {
+			f.keyMints[id]++
+			writeJSON(w, http.StatusCreated, tdclient.APIKey{
+				ID: int64(f.keyMints[id]), Name: name,
+				Key: fmt.Sprintf("instance-key-%d-mint%d", id, f.keyMints[id]),
+			})
+			return
+		}
+		w.WriteHeader(http.StatusNotFound)
+	}
+}
+
+func parseKeysPath(path string) (id int64, mintName string, ok bool) {
+	var parsedID int64
+	n, err := fmt.Sscanf(path, "/api/service-accounts/%d/keys", &parsedID)
+	if err != nil || n != 1 {
+		return 0, "", false
+	}
+	return parsedID, "minted", true
+}
+
+func writeJSON(w http.ResponseWriter, status int, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(v)
 }
 
 var _ = Describe("TerdutServer Controller", func() {
@@ -63,10 +140,23 @@ var _ = Describe("TerdutServer Controller", func() {
 	AfterEach(func(ctx SpecContext) {
 		srv := &terdutv1alpha1.TerdutServer{}
 		if err := k8sClient.Get(ctx, objKey, srv); err == nil {
-			Expect(k8sClient.Delete(ctx, srv)).To(Succeed())
+			srv.Finalizers = nil
+			_ = k8sClient.Update(ctx, srv)
+			_ = k8sClient.Delete(ctx, srv)
+		}
+		for _, n := range []string{checkpointSecretNameFor(name), credentialsSecretNameFor(name)} {
+			_ = k8sClient.Delete(ctx, &corev1.Secret{ObjectMeta: metav1.ObjectMeta{Name: n, Namespace: operatorNamespace}})
 		}
 	})
 
+	dsnSpec := func() terdutv1alpha1.TerdutServerSpec {
+		return terdutv1alpha1.TerdutServerSpec{
+			Image:      terdutv1alpha1.ImageSpec{Repository: "example.invalid/terdut-server", Tag: "test"},
+			Networking: terdutv1alpha1.NetworkingSpec{Hostname: "terdut.example.invalid", ServicePort: 8080},
+			Database:   terdutv1alpha1.DatabaseSpec{DSN: "postgres://terdut@test-postgres:5432/terdut?sslmode=require"},
+		}
+	}
+
 	createServer := func(ctx context.Context, spec terdutv1alpha1.TerdutServerSpec) {
 		srv := &terdutv1alpha1.TerdutServer{
 			ObjectMeta: metav1.ObjectMeta{Name: name, Namespace: operatorNamespace},
@@ -75,123 +165,235 @@ var _ = Describe("TerdutServer Controller", func() {
 		Expect(k8sClient.Create(ctx, srv)).To(Succeed())
 	}
 
-	reconcileOnce := func(ctx context.Context) {
-		_, err := reconciler.Reconcile(ctx, reconcile.Request{NamespacedName: objKey})
+	reconcileOnce := func(ctx context.Context) ctrl.Result {
+		res, err := reconciler.Reconcile(ctx, reconcile.Request{NamespacedName: objKey})
 		Expect(err).NotTo(HaveOccurred())
+		return res
+	}
+
+	markDeploymentReady := func(ctx context.Context) {
+		var deploy appsv1.Deployment
+		Expect(k8sClient.Get(ctx, objKey, &deploy)).To(Succeed())
+		deploy.Status.ReadyReplicas = 1
+		deploy.Status.Replicas = 1
+		Expect(k8sClient.Status().Update(ctx, &deploy)).To(Succeed())
 	}
 
 	readyCondition := func(ctx context.Context) metav1.Condition {
 		srv := &terdutv1alpha1.TerdutServer{}
 		Expect(k8sClient.Get(ctx, objKey, srv)).To(Succeed())
 		c := meta.FindStatusCondition(srv.Status.Conditions, terdutv1alpha1.ConditionReady)
-		Expect(c).NotTo(BeNil(), "Ready condition should always be set after a reconcile")
+		Expect(c).NotTo(BeNil(), "Ready condition should always be set after a reconcile past the finalizer-add pass")
 		return *c
 	}
 
-	When("spec.credentialsSecretRef is unset", func() {
-		It("reports Ready: False, reason CredentialsSecretRefRequired, and makes no API call", func(ctx SpecContext) {
-			createServer(ctx, terdutv1alpha1.TerdutServerSpec{Endpoint: unusedEndpoint})
+	Describe("bring-your-own DSN path", func() {
+		It("reaches Ready through the full lifecycle: finalizer, Deployment/Service, wait, bootstrap", func(ctx SpecContext) {
+			fake, fakeSrv := newFakeTerdutServer()
+			DeferCleanup(fakeSrv.Close)
+			reconciler.NewClient = func(string) *tdclient.Client { return tdclient.New(fakeSrv.URL) }
+
+			createServer(ctx, dsnSpec())
+
+			// Pass 1: adds the finalizer and returns early.
 			reconcileOnce(ctx)
+			srv := &terdutv1alpha1.TerdutServer{}
+			Expect(k8sClient.Get(ctx, objKey, srv)).To(Succeed())
+			Expect(srv.Finalizers).To(ContainElement(finalizerName))
 
-			cond := readyCondition(ctx)
-			Expect(cond.Status).To(Equal(metav1.ConditionFalse))
-			Expect(cond.Reason).To(Equal(terdutv1alpha1.ReasonCredentialsSecretRefRequired))
-		})
-	})
-
-	When("the referenced Secret does not exist", func() {
-		It("reports Ready: False, reason CredentialsSecretNotFound", func(ctx SpecContext) {
-			createServer(ctx, terdutv1alpha1.TerdutServerSpec{
-				Endpoint:             unusedEndpoint,
-				CredentialsSecretRef: &terdutv1alpha1.SecretKeyRef{Name: "does-not-exist", Key: tokenKey},
-			})
+			// Pass 2: creates Deployment + Service, waits for readiness.
 			reconcileOnce(ctx)
+			Expect(readyCondition(ctx).Reason).To(Equal(terdutv1alpha1.ReasonWaitingForDeployment))
 
-			cond := readyCondition(ctx)
-			Expect(cond.Status).To(Equal(metav1.ConditionFalse))
-			Expect(cond.Reason).To(Equal(terdutv1alpha1.ReasonCredentialsSecretNotFound))
-		})
-	})
-
-	When("the referenced Secret exists but has no data under the given key", func() {
-		It("reports Ready: False, reason CredentialsSecretInvalid", func(ctx SpecContext) {
-			secret := &corev1.Secret{
-				ObjectMeta: metav1.ObjectMeta{Name: name + "-creds", Namespace: operatorNamespace},
-				Data:       map[string][]byte{"wrong-key": []byte("tdsa_something")},
+			var deploy appsv1.Deployment
+			Expect(k8sClient.Get(ctx, objKey, &deploy)).To(Succeed())
+			Expect(deploy.Spec.Template.Spec.Containers[0].Image).To(Equal("example.invalid/terdut-server:test"))
+			envNames := map[string]string{}
+			for _, e := range deploy.Spec.Template.Spec.Containers[0].Env {
+				envNames[e.Name] = e.Value
 			}
-			Expect(k8sClient.Create(ctx, secret)).To(Succeed())
-			defer func() { _ = k8sClient.Delete(ctx, secret) }()
+			Expect(envNames).To(HaveKeyWithValue("TERDUT_DB_DSN", "postgres://terdut@test-postgres:5432/terdut?sslmode=require"))
+			Expect(envNames).To(HaveKeyWithValue("TERDUT_OPERATOR_MODE", "true"))
 
-			createServer(ctx, terdutv1alpha1.TerdutServerSpec{
-				Endpoint:             unusedEndpoint,
-				CredentialsSecretRef: &terdutv1alpha1.SecretKeyRef{Name: secret.Name, Key: tokenKey},
-			})
+			var svc corev1.Service
+			Expect(k8sClient.Get(ctx, objKey, &svc)).To(Succeed())
+			Expect(svc.Spec.Ports[0].Port).To(Equal(int32(8080)))
+
+			// Simulate the Deployment becoming ready (envtest has no
+			// kubelet/deployment-controller to do this for real).
+			markDeploymentReady(ctx)
+
+			// Pass 3: bootstraps for real against the fake server.
 			reconcileOnce(ctx)
 
-			cond := readyCondition(ctx)
-			Expect(cond.Status).To(Equal(metav1.ConditionFalse))
-			Expect(cond.Reason).To(Equal(terdutv1alpha1.ReasonCredentialsSecretInvalid))
+			Expect(fake.bootstrapped).To(BeTrue())
+
+			Expect(k8sClient.Get(ctx, objKey, srv)).To(Succeed())
+			ready := meta.FindStatusCondition(srv.Status.Conditions, terdutv1alpha1.ConditionReady)
+			Expect(ready.Status).To(Equal(metav1.ConditionTrue))
+			Expect(ready.Reason).To(Equal(terdutv1alpha1.ReasonAdopted))
+			Expect(srv.Status.CredentialsSecretRef).NotTo(BeNil())
+			Expect(srv.Status.CredentialsSecretRef.Key).To(Equal(credentialsSecretDataKey))
+
+			var credsSecret corev1.Secret
+			Expect(k8sClient.Get(ctx, types.NamespacedName{
+				Name: srv.Status.CredentialsSecretRef.Name, Namespace: operatorNamespace,
+			}, &credsSecret)).To(Succeed())
+			Expect(string(credsSecret.Data[credentialsSecretDataKey])).To(Equal("instance-key-1-initial"))
+
+			// The checkpoint is cleaned up once the lasting credential is
+			// written (DESIGN.md §6 point 2).
+			var checkpoint corev1.Secret
+			err := k8sClient.Get(ctx, types.NamespacedName{Name: checkpointSecretName(srv), Namespace: operatorNamespace}, &checkpoint)
+			Expect(err).To(HaveOccurred())
 		})
 	})
 
-	When("the Secret is valid but the server is unreachable", func() {
-		It("reports Ready: False, reason ServerUnreachable", func(ctx SpecContext) {
-			secret := &corev1.Secret{
-				ObjectMeta: metav1.ObjectMeta{Name: name + "-creds", Namespace: operatorNamespace},
-				Data:       map[string][]byte{tokenKey: []byte("tdsa_something")},
-			}
-			Expect(k8sClient.Create(ctx, secret)).To(Succeed())
-			defer func() { _ = k8sClient.Delete(ctx, secret) }()
+	Describe("the adopt-on-409 recovery path", func() {
+		It("mints a fresh key instead of erroring when the service account already exists", func(ctx SpecContext) {
+			fake, fakeSrv := newFakeTerdutServer()
+			DeferCleanup(fakeSrv.Close)
+			fake.bootstrapped = true // an earlier attempt already bootstrapped...
+			fake.nextID = 1
+			fake.accounts[serviceAccountName] = 1 // ...and already created the service account.
+			fake.keyMints[1] = 1
+			reconciler.NewClient = func(string) *tdclient.Client { return tdclient.New(fakeSrv.URL) }
 
-			createServer(ctx, terdutv1alpha1.TerdutServerSpec{
-				// Port 1 is never listening (closed cleanly and immediately,
-				// unlike an unroutable address which would hang on a
-				// connect timeout) -- keeps the test fast.
-				Endpoint:             "http://127.0.0.1:1",
-				CredentialsSecretRef: &terdutv1alpha1.SecretKeyRef{Name: secret.Name, Key: tokenKey},
-			})
-			reconcileOnce(ctx)
+			createServer(ctx, dsnSpec())
+			reconcileOnce(ctx) // finalizer
+			reconcileOnce(ctx) // Deployment/Service, WaitingForDeployment
+			markDeploymentReady(ctx)
 
-			cond := readyCondition(ctx)
-			Expect(cond.Status).To(Equal(metav1.ConditionFalse))
-			Expect(cond.Reason).To(Equal(terdutv1alpha1.ReasonServerUnreachable))
-		})
-	})
+			// The earlier attempt's checkpoint survived (that's how this
+			// reconcile can authenticate at all to recover).
+			Expect(reconciler.writeSecret(ctx, checkpointSecretName(&terdutv1alpha1.TerdutServer{
+				ObjectMeta: metav1.ObjectMeta{Name: name, Namespace: operatorNamespace},
+			}), "admin-key-raw")).To(Succeed())
 
-	When("the Secret is valid and the server answers /api/version", func() {
-		It("reports Ready: True, Bootstrapped: True, and mirrors credentialsSecretRef into status", func(ctx SpecContext) {
-			fake := fakeTerdutServer("v0.20.0")
-			DeferCleanup(fake.Close)
-
-			secret := &corev1.Secret{
-				ObjectMeta: metav1.ObjectMeta{Name: name + "-creds", Namespace: operatorNamespace},
-				Data:       map[string][]byte{tokenKey: []byte("tdsa_something")},
-			}
-			Expect(k8sClient.Create(ctx, secret)).To(Succeed())
-			defer func() { _ = k8sClient.Delete(ctx, secret) }()
-
-			createServer(ctx, terdutv1alpha1.TerdutServerSpec{
-				Endpoint:             fake.URL,
-				CredentialsSecretRef: &terdutv1alpha1.SecretKeyRef{Name: secret.Name, Key: tokenKey},
-			})
 			reconcileOnce(ctx)
 
 			srv := &terdutv1alpha1.TerdutServer{}
 			Expect(k8sClient.Get(ctx, objKey, srv)).To(Succeed())
+			Expect(meta.FindStatusCondition(srv.Status.Conditions, terdutv1alpha1.ConditionReady).Status).To(Equal(metav1.ConditionTrue))
 
-			ready := meta.FindStatusCondition(srv.Status.Conditions, terdutv1alpha1.ConditionReady)
-			Expect(ready).NotTo(BeNil())
-			Expect(ready.Status).To(Equal(metav1.ConditionTrue))
-			Expect(ready.Reason).To(Equal(terdutv1alpha1.ReasonAdopted))
+			var credsSecret corev1.Secret
+			Expect(k8sClient.Get(ctx, types.NamespacedName{
+				Name: srv.Status.CredentialsSecretRef.Name, Namespace: operatorNamespace,
+			}, &credsSecret)).To(Succeed())
+			// Minted fresh, not the (never-seen-by-this-reconcile) "initial"
+			// key from the account's original creation.
+			Expect(string(credsSecret.Data[credentialsSecretDataKey])).To(Equal("instance-key-1-mint2"))
+		})
+	})
 
-			bootstrapped := meta.FindStatusCondition(srv.Status.Conditions, terdutv1alpha1.ConditionBootstrapped)
-			Expect(bootstrapped).NotTo(BeNil())
-			Expect(bootstrapped.Status).To(Equal(metav1.ConditionTrue))
+	Describe("the BootstrapStateLost path", func() {
+		It("fails closed when the server reports already-bootstrapped with no checkpoint to recover from", func(ctx SpecContext) {
+			fake, fakeSrv := newFakeTerdutServer()
+			_ = fake
+			DeferCleanup(fakeSrv.Close)
+			fake.bootstrap403 = true
+			reconciler.NewClient = func(string) *tdclient.Client { return tdclient.New(fakeSrv.URL) }
 
-			Expect(srv.Status.CredentialsSecretRef).NotTo(BeNil())
-			Expect(srv.Status.CredentialsSecretRef.Name).To(Equal(secret.Name))
-			Expect(srv.Status.CredentialsSecretRef.Key).To(Equal(tokenKey))
-			Expect(srv.Status.ObservedGeneration).To(Equal(srv.Generation))
+			createServer(ctx, dsnSpec())
+			reconcileOnce(ctx) // finalizer
+			reconcileOnce(ctx) // Deployment/Service
+			markDeploymentReady(ctx)
+
+			reconcileOnce(ctx)
+
+			cond := readyCondition(ctx)
+			Expect(cond.Status).To(Equal(metav1.ConditionFalse))
+			Expect(cond.Reason).To(Equal(terdutv1alpha1.ReasonBootstrapStateLost))
+		})
+	})
+
+	Describe("the Zalando postgresClusterRef path", func() {
+		zalandoSpec := func(clusterName string) terdutv1alpha1.TerdutServerSpec {
+			s := dsnSpec()
+			s.Database = terdutv1alpha1.DatabaseSpec{
+				PostgresClusterRef: &terdutv1alpha1.PostgresClusterRef{Name: clusterName},
+			}
+			return s
+		}
+
+		It("waits with reason PostgresClusterNotFound when the postgresql CR doesn't exist yet", func(ctx SpecContext) {
+			createServer(ctx, zalandoSpec("missing-cluster"))
+			reconcileOnce(ctx) // finalizer
+			reconcileOnce(ctx)
+
+			Expect(readyCondition(ctx).Reason).To(Equal(terdutv1alpha1.ReasonPostgresClusterNotFound))
+		})
+
+		It("resolves a real DSN and reaches Ready once the CR and its generated Secret both exist", func(ctx SpecContext) {
+			clusterName := "pg-" + name
+			cluster := &unstructured.Unstructured{}
+			cluster.SetGroupVersionKind(postgresqlGVK)
+			cluster.SetName(clusterName)
+			cluster.SetNamespace(operatorNamespace)
+			Expect(unstructured.SetNestedField(cluster.Object, map[string]any{}, "spec")).To(Succeed())
+			Expect(k8sClient.Create(ctx, cluster)).To(Succeed())
+			DeferCleanup(func() { _ = k8sClient.Delete(ctx, cluster) })
+
+			credsSecretName := fmt.Sprintf("terdut.%s.credentials.postgresql.acid.zalan.do", clusterName)
+			zalandoSecret := &corev1.Secret{
+				ObjectMeta: metav1.ObjectMeta{Name: credsSecretName, Namespace: operatorNamespace},
+				Data:       map[string][]byte{"password": []byte("whatever")},
+			}
+			Expect(k8sClient.Create(ctx, zalandoSecret)).To(Succeed())
+			DeferCleanup(func() { _ = k8sClient.Delete(ctx, zalandoSecret) })
+
+			fake, fakeSrv := newFakeTerdutServer()
+			_ = fake
+			DeferCleanup(fakeSrv.Close)
+			reconciler.NewClient = func(string) *tdclient.Client { return tdclient.New(fakeSrv.URL) }
+
+			createServer(ctx, zalandoSpec(clusterName))
+			reconcileOnce(ctx) // finalizer
+			reconcileOnce(ctx) // Deployment/Service created with resolved DB env
+
+			var deploy appsv1.Deployment
+			Expect(k8sClient.Get(ctx, objKey, &deploy)).To(Succeed())
+			var dsn string
+			for _, e := range deploy.Spec.Template.Spec.Containers[0].Env {
+				if e.Name == "TERDUT_DB_DSN" {
+					dsn = e.Value
+				}
+			}
+			Expect(dsn).To(Equal(fmt.Sprintf("postgres://terdut@%s.%s.svc:5432/terdut?sslmode=require", clusterName, operatorNamespace)))
+
+			markDeploymentReady(ctx)
+			reconcileOnce(ctx)
+
+			Expect(readyCondition(ctx).Status).To(Equal(metav1.ConditionTrue))
+		})
+	})
+
+	Describe("deletion", func() {
+		It("removes the credentials and checkpoint Secrets and the finalizer", func(ctx SpecContext) {
+			fake, fakeSrv := newFakeTerdutServer()
+			_ = fake
+			DeferCleanup(fakeSrv.Close)
+			reconciler.NewClient = func(string) *tdclient.Client { return tdclient.New(fakeSrv.URL) }
+
+			createServer(ctx, dsnSpec())
+			reconcileOnce(ctx)
+			reconcileOnce(ctx)
+			markDeploymentReady(ctx)
+			reconcileOnce(ctx)
+
+			srv := &terdutv1alpha1.TerdutServer{}
+			Expect(k8sClient.Get(ctx, objKey, srv)).To(Succeed())
+			credsName := srv.Status.CredentialsSecretRef.Name
+
+			Expect(k8sClient.Delete(ctx, srv)).To(Succeed())
+			reconcileOnce(ctx) // runs the finalizer
+
+			err := k8sClient.Get(ctx, objKey, srv)
+			Expect(err).To(HaveOccurred(), "the TerdutServer itself should be gone once the finalizer clears")
+
+			var leftover corev1.Secret
+			err = k8sClient.Get(ctx, types.NamespacedName{Name: credsName, Namespace: operatorNamespace}, &leftover)
+			Expect(err).To(HaveOccurred(), "the credentials Secret should have been cleaned up by the finalizer")
 		})
 	})
 
@@ -205,12 +407,12 @@ var _ = Describe("TerdutServer Controller", func() {
 	})
 })
 
-var _ = Describe("TerdutServerReconciler sanity", func() {
-	It("treats a real apierrors.IsNotFound the same as any other caller would", func() {
-		// Guards against a refactor accidentally swapping in a different
-		// not-found check that stops matching what client.Client actually
-		// returns.
-		Expect(apierrors.IsNotFound(apierrors.NewNotFound(
-			terdutv1alpha1.GroupVersion.WithResource("terdutservers").GroupResource(), "x"))).To(BeTrue())
-	})
-})
+// checkpointSecretNameFor/credentialsSecretNameFor let AfterEach clean up
+// without needing a live TerdutServer object (it may already be gone by
+// then in the deletion test).
+func checkpointSecretNameFor(name string) string {
+	return fmt.Sprintf("default.%s-bootstrap-admin", name)
+}
+func credentialsSecretNameFor(name string) string {
+	return fmt.Sprintf("default.%s-instance-credentials", name)
+}