Add namespaced isolation mode for cluster-scoped objects

[xrstf]

Summary

This PR implements two new scoping methods for cluster-scoped objects:

• none doesn't change anything about the name of a consumer-side object when it's synced to the provider. This comes with all the obvious pitfalls.
• namespaced transforms a cluster-scoped object into a namespaced one, putting it into the cluster namespace (kube-bind-abc123).

However to accomplish this, I had to refactor the entire approach to how object scoping is handled in the spec/status controllers.

Originally, kube-bind was written for only namespaced objects and everything was easy. Then we added basic support for cluster-scoped objects by prepending them with a prefix. This change however was yanked into the controllers with a crowbar. For example, the function to create the copy of an object on the provider cluster (createProviderObject) suddenly was transforming the given object into something else, then applies it, then un-transforms it again before returning it. From what I can see in the codebase, there is never even a reason to undo any transformations being done. Once createProviderObject is called, we're done processing the object. Why have all the code for reverting changes? Likewise, injecting and changing namespaces was also done in the small functional wrappers (like createProviderObject, updateProviderObject) which were never meant to contain business logic, but exist (as far as I can tell) to ease unit testing and to make the reconcilers "more functional" (i.e. instead of giving them loads of small details, just give them the few pieces of behaviour they rely on). createProviderObject should IMHO not have anything to do with how the objects are changed during transit.

Now that new isolation modes have been added, the old approach would not have scaled anyway and so I introduced the concept of "isolation strategies". At first I had three (prefixed (the old), namespaced, none), but then when I looked through the spec/status controllers event handlers, a lot of them also contained magic to undo/unmap cluster-scoped objects. So that logic was also moved into the isolation strategies.

However this was ugly with code basically being

if namespaced {
   lots of code
   yadda yadda
   APIServiceNamespace handling
   requeueing...
} else {
   isolationStrategy.DoStuff(obj)
}

Since the entire APIServiceNamespace handling is exclusive to how namespaced objects are handled, I was trying to avoid having it remain in the controllers and so I decided that a fourth isolation strategy makes the most sense:

• ServiceNamespaced is the strategy for natively namespaced (on both sides) objects.
• Prefixed is the old cluster-scoped behaviour.
• Namespaced is one of the new cluster-scoped behaviours.
• None is one of the new cluster-scoped behaviours.

In the CRD however we only expose the latter three, since we always use the ServiceNamespaced strategy for namespaced objects [at the moment...].

The only thing that remained as part of the controller logic was applying the ClusterNamespaceAnnotation, since it applies to every object no matter what strategy and can easily be done transparently to the isolation strategies. And since this annotation is always present, I awarded it its own dedicated types package in the konnector to make it independent of the controllers/ packages.

Warning: Due to the nature of this feature, the namespaced isolation requires a namespaced CRD on the provider side. (and a cluster-scoped CRD on the consumer side). Since the backend currently only has 1 global CLI flag to control isolation and can otherwise just look at the existing CRDs on the provider cluster, the backend cannot distinguish between namespaced CRDs that are meant to stay namespaced, and those that are meant to be translated into cluster-scoped CRDs.

This means that if you run your backend with --cluster-scoped-isolation=namespaced, ALL NAMESPACED CRDs ON THE PROVIDER CLUSTER WILL BECOME CLUSTER-SCOPED CRDs. Currently you would need to run two separate backends if you want to offer Services that make use of this translation, and those where you want to have natively namespaced CRDs on both sides (consumer and provider).

This limitation only affects this new isolation mode, since it's the only one that has differnt scoping on different clusters.

What Type of PR Is This?

/kind feature

Related Issue(s)

Fixes #307

Release Notes

Implement support for `Namespaced` and `None` cluster isolation strategies when dealing with cluster-scoped objects.

[xrstf]

@coderabbitai

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@xrstf: Hello! How can I assist you with this pull request?

---

🧠 Learnings used

Learnt from: mjudeikis
Repo: kube-bind/kube-bind PR: 351
File: contrib/kcp/test/e2e/binding.go:49-56
Timestamp: 2025-11-04T11:51:36.024Z
Learning: In kube-bind e2e tests (contrib/kcp/test/e2e/), workspace-level isolation prevents conflicts between test runs, making it safe to use hardcoded resource names like "test-binding" without risk of concurrent test collisions.

[xrstf]

@coderabbitai review this please

[coderabbitai]

@xrstf: I will review the changes in this pull request.

---

🧠 Learnings used

Learnt from: mjudeikis
Repo: kube-bind/kube-bind PR: 351
File: contrib/kcp/test/e2e/binding.go:49-56
Timestamp: 2025-11-04T11:51:36.024Z
Learning: In kube-bind e2e tests (contrib/kcp/test/e2e/), workspace-level isolation prevents conflicts between test runs, making it safe to use hardcoded resource names like "test-binding" without risk of concurrent test collisions.

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[xrstf]

@coderabbitai review!

[coderabbitai]

@xrstf: I will review the changes in this pull request.

---

🧠 Learnings used

Learnt from: mjudeikis
Repo: kube-bind/kube-bind PR: 351
File: contrib/kcp/test/e2e/binding.go:49-56
Timestamp: 2025-11-04T11:51:36.024Z
Learning: In kube-bind e2e tests (contrib/kcp/test/e2e/), workspace-level isolation prevents conflicts between test runs, making it safe to use hardcoded resource names like "test-binding" without risk of concurrent test collisions.

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[ntnn]

@coderabbitai full-review

[coderabbitai]

@ntnn: I will perform a full review of all the changes in this pull request.

---

🧠 Learnings used

Learnt from: mjudeikis
Repo: kube-bind/kube-bind PR: 351
File: contrib/kcp/test/e2e/binding.go:49-56
Timestamp: 2025-11-04T11:51:36.024Z
Learning: In kube-bind e2e tests (contrib/kcp/test/e2e/), workspace-level isolation prevents conflicts between test runs, making it safe to use hardcoded resource names like "test-binding" without risk of concurrent test collisions.

✅ Actions performed

Full review triggered.

[xrstf]

@coderabbitai It's okay, you don't like me, I don't like you either.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@xrstf: I'm here to assist with code reviews and any questions you have about this pull request. If there's something specific you'd like me to address or if you have concerns about the review process, please let me know.

---

🧠 Learnings used

Learnt from: mjudeikis
Repo: kube-bind/kube-bind PR: 351
File: contrib/kcp/test/e2e/binding.go:49-56
Timestamp: 2025-11-04T11:51:36.024Z
Learning: In kube-bind e2e tests (contrib/kcp/test/e2e/), workspace-level isolation prevents conflicts between test runs, making it safe to use hardcoded resource names like "test-binding" without risk of concurrent test collisions.

[mjudeikis]

Few nits, but not worth cmmenting as nothing core chaning :)
very nicelly done :) thanks!

[cnvergence]

Looks good, thanks for providing the doc and explaining everything in detail
🍿