fix(namespace): converge bookie affinity group instead of blind-writing

[david-streamlio]

Fixes #420.

spec.bookieAffinityGroup already existed on PulsarNamespace and was already reconciled, so this is not a new feature — it is a fix to the reconcile path, plus the validation and docs the field was missing. Rationale for the reframing is in this issue comment.

The bug

Every PulsarNamespace that did not declare bookieAffinityGroup issued an unconditional DELETE .../persistence/bookieAffinity on each reconcile, with no IsNotFound tolerance — unlike the neighbouring RemoveTopicAutoCreation and RemoveInactiveTopicPolicies branches in the same function:

} else {
    err = p.adminClient.Namespaces().DeleteBookieAffinityGroup(completeNSName)
    if err != nil {
        return err
    }
}

Pulsar implements that delete as a set of a null group (NamespacesBase#internalDeleteBookieAffinityGroupAsync → internalSetBookieAffinityGroupAsync(null)), and both the setter and the getter call validateSuperUserAccessAsync(). Consequences:

1. A tenant-admin connection cannot reconcile any namespace. It gets 401/403 on that DELETE, ApplyNamespace fails, and the namespace never reaches Ready — for users who never touched bookie affinity at all.
2. Spurious metadata writes. setLocalPoliciesWithCreate creates the local-policies znode with default bundle data even when there was nothing to delete.
3. No read of current state, so "removing the setting removes the policy" was assumed rather than verified.

The fix

applyBookieAffinityGroup reads the current group first and writes only on an actual diff. An unset-to-unset transition now touches Pulsar not at all, which removes the superuser dependency for namespaces that don't use the feature. Both of Pulsar's "no group" answers are normalized to nil: a 404 "Namespace local-policies does not exist" when the namespace has no local policies, and a 200 carrying an empty group when they were cleared.

A non-404 read failure propagates rather than being mistaken for "unset" — otherwise a 403 would silently skip a required write.

Also in this PR

• Corrected the BookieAffinityGroup godoc. It read "is the name of the namespace isolation policy to apply to the namespace", which describes PulsarNSIsolationPolicy — a different feature. That wording is why Expose bookie affinity groups (namespace-level bookie isolation) as a managed resource #420 was filed as "not exposed through any CRD".
• MinLength=1 on both group names. An empty primary passed CRD validation and was pushed to Pulsar, where BookieRackAffinityMapping cannot place ledgers. Only "" becomes invalid, so no working configuration is rejected.
• Documented the end-to-end carve-out — new "Broker and Bookie Isolation" section in docs/pulsar_namespace.md pairing PulsarNSIsolationPolicy (brokers) with bookieAffinityGroup (bookies), including the rack-metadata prerequisite and the superuser requirement. Cross-linked from docs/pulsar_ns_isolation_policy.md.

Tests

• pkg/admin/bookie_affinity_group_test.go — 7 table cases over an httptest server in the style of namespace_backlog_quota_test.go: unset stays unset without writing, cleared group is not deleted again, removal deletes, set when absent, matching group left alone, changed group rewritten, dropped secondary rewritten. Plus read-failure propagation.
• tests/operator/resources_test.go — a PulsarNamespace Bookie Affinity Group context covering create → update → empty-primary rejection → field removal, mirroring the offload-policies coverage from feat(namespace): add offload policies support #413.

Verified: go build ./..., go test ./pkg/... ./api/... (including the existing applyNamespacePolicies backlog-quota tests, which now traverse the new read path), make fmt vet, make license-check (479 files, 0 invalid). E2E not executed — needs a live cluster via ADMIN_SERVICE_URL.

Note for reviewers

The CRD schema was updated by hand, deliberately. make manifests pulls controller-gen v0.17.0 (pinned at Makefile:201) but the committed CRDs were generated with v0.15.0. Running it rewrites all 19 CRDs — ~1300 lines of unrelated churn — and strips the Apache license header from every YAML. Only the bookieAffinityGroup block was applied here, byte-matching the generator's output. The Makefile/CRD version skew is pre-existing and wants its own PR.

The sn-operator half of #420 (declarative bookie-to-isolation-group membership on BookKeeperCluster) is a genuinely separate gap and belongs on that repo — nothing here can express it.

🤖 Generated with Claude Code

[github-actions]

@david-streamlio:Thanks for your contribution. For this PR, do we need to update docs?
(The PR template contains info about doc, which helps others know more about the changes. Can you provide doc-related info in this and future PR descriptions? Thanks)