Merge pull request #3506 from embik/writing-controllers

Add some basic documentation for writing kcp-aware controllers

Author: kcp-ci-bot

docs/content/developers/.pages

@@ -1,3 +1,4 @@
 nav:
   - index.md
+  - controllers
   - ...

docs/content/developers/controllers/.pages

@@ -0,0 +1,3 @@
+nav:
+ - writing-kcp-aware-controllers.md
+ - client-go.md

docs/content/developers/controllers/client-go.md

@@ -0,0 +1,3 @@
+# client-go
+
+kcp maintains its own `client-go` implementation at [github.com/kcp-dev/client-go](https://github.com/kcp-dev/client-go) for multi-cluster-aware Kubernetes clients, listers and informers.

docs/content/developers/controllers/writing-kcp-aware-controllers.md

@@ -7,23 +7,34 @@ description: >
 
 # Writing kcp-aware Controllers
 
-## Keys for Objects in Listers/Indexers
+While kcp follows the Kubernetes Resource Model (KRM) closely, its multi-tenancy capabilities via workspaces / logical clusters
+make normal Kubernetes controllers somewhat limited in usefulness, since they generally expect a single Kubernetes API endpoint
+(which would correspond to a single logical cluster). While kcp exposes something called [virtual workspaces](../../concepts/workspaces/virtual-workspaces.md),
+their API semantics are also different from standard Kubernetes API endpoints and thus, controllers written for Kubernetes
+cannot be used against them.
 
-When you need to get an object from a kcp-aware lister or an indexer, you can't just pass the object's name to the
-`Get()` function, like you do with a typical controller targeting Kubernetes. Projects using kcp's copy of client-go
-are using a modified key function.
+!!! info
+    kcp has previously maintained a [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime) fork under [kcp-dev/controller-runtime](https://github.com/kcp-dev/controller-runtime).
+    While it likely still works, we recommend migration to multicluster-runtime (see below).
 
-Here are what keys look like for an object `foo` for both cluster-scoped and namespace-scoped varieties:
+## multicluster-runtime
 
-|Organization|Workspace|Logical Cluster|Namespace|Key|
-|-|-|-|-|-|
-|-|-|root|-|root|foo|
-|-|-|root|default|default/root|foo|
-|root|my-org|root:my-org|-|root:my-org|foo|
-|root|my-org|root:my-org|default|default/root:my-org|foo|
-|my-org|my-workspace|my-org:my-workspace|-|my-org:my-workspace|foo|
-|my-org|my-workspace|my-org:my-workspace|default|default/my-org:my-workspace|foo|
+[multicluster-runtime](https://github.com/kubernetes-sigs/multicluster-runtime) is an effort initiated by kcp developers in the upstream
+community to provide a framework for building multi-cluster controllers. multicluster-runtime is **not** a fork of controller-runtime,
+instead it is a sort of "addon" built on top of controller-runtime's excellent Go generic support. While the project is relatively young
+and deemed experimental, we are confident in its ability to provide a great controller development experience for kcp.
 
-## Encoding/Decoding Keys
+The runtime itself is generic and needs a so-called provider that provides it with information about the fleet of clusters
+it is supposed to reconcile over. A small ecosystem of providers exists already. The relevant provider for writing kcp-aware
+controllers is described below.
 
-Use the `github.com/kcp-dev/apimachinery/pkg/cache` package to encode and decode keys.
+For more information, also feel free to check out the [talk introducing multicluster-runtime at KubeCon + CloudNativeCon EU in London, 2025](https://www.youtube.com/watch?v=Tz8IcMSY7jw).
+
+### Providers for kcp
+
+kcp hosts a repository for kcp-specific provider implementations at [kcp-dev/multicluster-provider](https://github.com/kcp-dev/multicluster-provider).
+
+Which provider to choose depends on the controller that is to be written, but there is a good chance you want to write a controller for resources
+distributed via an [APIExport](../../concepts/apis/exporting-apis.md). In that case, you should choose the `apiexport` provider from the repository.
+
+The provider repository also includes examples, including [one for the `apiexport` provider](https://github.com/kcp-dev/multicluster-provider/tree/main/examples/apiexport).

docs/content/developers/investigations/logical-clusters.md

@@ -3,7 +3,7 @@ description: >
   Investigation on logical clusters
 ---
 
-# Logical clusters
+# Logical Clusters
 
 Kubernetes evolved from and was influenced by earlier systems that had weaker internal tenancy than a general-purpose compute platform requires. The namespace, quota, admission, and RBAC concepts were all envisioned quite early in the project, but evolved with Kubernetes and not all impacts to future evolution were completely anticipated. Tenancy within clusters is handled at the resource and namespace level, and within a namespace there are a limited number of boundaries. Most organizations use either namespace or cluster separation as their primary unit of self service, with variations leveraging a rich ecosystem of tools.
 

docs/content/developers/investigations/self-service-policy.md

@@ -3,7 +3,7 @@ description: >
   Improve consistency and reusability of self-service and policy enforcement across multiple Kubernetes clusters.
 ---
 
-# Self-service policy
+# Self-service Policy
 
 ## Goal
 

docs/content/developers/investigations/transparent-multi-cluster.md

@@ -3,9 +3,11 @@ description: >
   Investigation of transparent multi-cluster
 ---
 
-# Transparent multi-cluster
+# Transparent Multi-Cluster
 
-## NOTE: This was a prototype that was not continued. The ideas here are still valid and could be picked up by a future project. 
+
+!!! warning
+    This was a prototype that was not continued. The ideas here are still valid and could be picked up by a future project. 
 
 A key tenet of Kubernetes is that workload placement is node-agnostic until the user needs it to be - Kube offers a homogeneous compute surface that admins or app devs can "break-glass" and set constraints all the way down to writing software that deeply integrates with nodes. But for the majority of workloads a cluster is no more important than a node - it's a detail determined by some human or automated process.
 

docs/content/developers/storage-to-rest-patterns.md

@@ -1,12 +1,14 @@
-### workspaces
+# Storage to REST Patterns
 
-kcp promises to support 1 mln of workspaces. 
-A workspace is like a Kubernetes endpoint, i.e. an endpoint usual Kubernetes client tooling (client-go, controller-runtime and others) 
+## Logical Clusters
+
+kcp promises to support 1 million logical clusters. 
+A logical cluster is like a Kubernetes endpoint, i.e. an endpoint usual Kubernetes client tooling (client-go, controller-runtime and others) 
 and user interfaces (kubectl, helm, web console, ...) can talk to, just like to a Kubernetes cluster.
-Thus creating a workspace must be efficient, both in terms of storage and compute.
+Thus creating a logical cluster must be efficient, both in terms of storage and compute.
 It also must provide isolation, just like regular clusters.
 
-### etcd
+## etcd
 
 etcd is the primary datastore used by kcp. 
 It stores data in a key-value store. 
@@ -52,7 +54,7 @@ Creating a workspace on the storage layer is very efficient because it boils dow
 It also provides isolation on the lowest possible level.
 Data is filtered by the database engine.
 
-### the generic registry
+## Generic Registry
 
 kcp is based on the generic apiserver library provided by Kubernetes. 
 The central type provided by the library that interacts with a storage layer is called the generic registry.