Update docs for v0.5

Signed-off-by: Mangirdas Judeikis <mangirdas@judeikis.lt>
On-behalf-of: @SAP mangirdas.judeikis@sap.com

Author: mjudeikis

Makefile

@@ -77,7 +77,7 @@ CODE_GENERATOR_BIN := code-generator
 CODE_GENERATOR := $(TOOLS_GOBIN_DIR)/$(CODE_GENERATOR_BIN)-$(CODE_GENERATOR_VER)
 export CODE_GENERATOR # so hack scripts can use it
 
-KCP_VER := v0.28.1
+KCP_VER := v0.28.0
 KCP_BIN := kcp
 KCP := $(TOOLS_GOBIN_DIR)/$(KCP_BIN)-$(KCP_VER)
 KCP_CMD ?= $(KCP)

README.md

@@ -62,23 +62,28 @@ All the actions shown between the clusters are done by the konnector, except: th
 
 To get familiar with setting up the environment, please check out docs at [kube-bind.io](https://docs.kube-bind.io/main/setup).
 
-## API Changes in coming v0.5.0 release
+## API Changes in v0.5.0 release
 
 Version v0.5.0 includes significant architectural improvements to the API structure:
 
 ### Major Changes
 
-- **API Version Upgrade**: Introduced `v1alpha2` API version with improved stability and features
-- **Service Exposure Refactoring**: Completely refactored the service exposure mechanism to use:
-  - `APIResourceSchema`: Define the schema of exported CRDs, allowing one APIServiceExport to reference multiple CRDs.
-  - `BoundAPIResourceSchema`: Represent bound schemas in consumer clusters and underlying status of synced resources.
+- **API Version Upgrade**: Introduced `v1alpha2` API version alongside existing `v1alpha1`
+- **Service Exposure Refactoring**: Refactored the service exposure mechanism from embedded CRD specifications to a resource-based model:
+  - `APIServiceExportSpec` now uses `Resources []APIServiceExportResource` instead of embedded CRD specs
+  - `BoundSchema`: New resource type in `v1alpha2` that represents bound schemas in consumer clusters and tracks the status of synced resources
+  - This allows one APIServiceExport to reference multiple CRDs more efficiently
+
+### Backend Architecture Improvements
+
+- **MultiCluster Runtime Integration**: The backend now leverages `sigs.k8s.io/multicluster-runtime` for enhanced cluster management capabilities
+- **Provider Support**: Built-in support for multiple backend providers including KCP through `github.com/kcp-dev/multicluster-provider`
+- **Enhanced Cluster Operations**: Improved cluster-aware resource management with dedicated manager architecture for handling multi-cluster scenarios
 
 ### Limitations
 
 These limitations are part of the roadmap and will be addressed in the future.
 
-* Currently we don't support related resources, like ConfigMaps, Secrets
-* Currently CRD resources MUST be installed in the provider cluster, even when APIResourceSchema is used.
-  This is to allow the konnector to sync instances of the CRD to the consumer cluster.
-  This should be removed once we introduce sync policies and object wrappers.
-* Currently we dont support granular permissions, like only allow to read/write certain named resources.
+* Currently we don't support related resources, like ConfigMaps, Secrets.
+* We don't support lifecycle of `BoundSchema` resources, like schema changes.
+* Currently multicluster-runtime dependency is pointing to a fork, we will work on getting the changes merged upstream. See [PR](https://github.com/kubernetes-sigs/multicluster-runtime/pull/62) for details.

backend/config.go

@@ -35,18 +35,18 @@ import (
 	ctrlconfig "sigs.k8s.io/controller-runtime/pkg/config"
 	metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"
 	mcmanager "sigs.k8s.io/multicluster-runtime/pkg/manager"
-	"sigs.k8s.io/multicluster-runtime/pkg/multicluster"
 
 	kuberesources "github.com/kube-bind/kube-bind/backend/kubernetes/resources"
 	"github.com/kube-bind/kube-bind/backend/options"
+	"github.com/kube-bind/kube-bind/backend/provider"
 	kubebindv1alpha1 "github.com/kube-bind/kube-bind/sdk/apis/kubebind/v1alpha1"
 	kubebindv1alpha2 "github.com/kube-bind/kube-bind/sdk/apis/kubebind/v1alpha2"
 )
 
 type Config struct {
 	Options *options.CompletedOptions
 
-	Provider                 multicluster.Provider
+	Provider                 provider.MultiClusterProvider
 	ExternalAddressGenerator kuberesources.ExternalAddreesGeneratorFunc
 	Manager                  mcmanager.Manager
 	Scheme                   *runtime.Scheme

backend/provider/provider.go

@@ -0,0 +1,25 @@
+/*
+Copyright 2025 The Kube Bind Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package provider
+
+import "sigs.k8s.io/multicluster-runtime/pkg/multicluster"
+
+// MultiClusterProvider is an interface that combines multicluster.Provider and multicluster.ProviderRunnable.
+type MultiClusterProvider interface {
+	multicluster.Provider
+	multicluster.ProviderRunnable
+}

contrib/kcp/deploy/resources/apiexport-kube-bind.io.yaml

@@ -74,7 +74,7 @@ spec:
       crd: {}
   - group: kube-bind.io
     name: clusterbindings
-    schema: v250809-5ed76a1.clusterbindings.kube-bind.io
+    schema: v250925-56669b8.clusterbindings.kube-bind.io
     storage:
       crd: {}
 status: {}

contrib/kcp/deploy/resources/apiresourceschema-clusterbindings.kube-bind.io.yaml

@@ -2,7 +2,7 @@ apiVersion: apis.kcp.io/v1alpha1
 kind: APIResourceSchema
 metadata:
   creationTimestamp: null
-  name: v250809-5ed76a1.clusterbindings.kube-bind.io
+  name: v250925-56669b8.clusterbindings.kube-bind.io
 spec:
   conversion:
     strategy: None
@@ -32,8 +32,8 @@ spec:
     name: v1alpha1
     schema:
       description: |-
-        ClusterBinding represents a bound consumer cluster. It lives in a service
-        provider cluster and is a singleton named "cluster" per namespace.
+        ClusterBinding represents a bound consumer cluster. It lives in a service provider cluster
+        and is a singleton named "cluster".
       properties:
         apiVersion:
           description: |-

deploy/crd/kube-bind.io_clusterbindings.yaml

@@ -34,8 +34,8 @@ spec:
     schema:
       openAPIV3Schema:
         description: |-
-          ClusterBinding represents a bound consumer cluster. It lives in a service
-          provider cluster and is a singleton named "cluster" per namespace.
+          ClusterBinding represents a bound consumer cluster. It lives in a service provider cluster
+          and is a singleton named "cluster".
         properties:
           apiVersion:
             description: |-

docs/content/developers/backend/index.md

@@ -1 +1,65 @@
 # Backend
+
+The kube-bind backend provides service export and binding capabilities for single Kubernetes clusters acting as backend or many clusters with support for multiple cluster providers through the multicluster-runtime architecture.
+
+## Architecture
+
+Starting with v0.5.0, the backend leverages `sigs.k8s.io/multicluster-runtime` for enhanced cluster management capabilities.
+
+### Key Components
+
+- **MultiCluster Runtime Integration**: Built on `sigs.k8s.io/multicluster-runtime` for provider-agnostic cluster operations
+- **Provider Support**: Extensible provider system supporting different backend implementations
+- **Manager Architecture**: Uses `mcmanager.Manager` for cluster-aware resource management
+
+### Supported Providers
+
+- **Default Provider**: Standard Kubernetes cluster support
+- **KCP Provider**: Integration with [kcp](https://github.com/kcp-dev/kcp) through `github.com/kcp-dev/multicluster-provider`
+
+## Configuration
+
+The backend can be configured to use different providers:
+
+```bash
+./bin/backend \
+  --multicluster-runtime-provider kcp \
+  --server-url=$(kubectl get apiexportendpointslice kube-bind.io -o jsonpath="{.status.endpoints[0].url}") \
+  # ... other options
+```
+
+### Provider Configuration
+
+#### KCP Provider
+
+When using the KCP provider (`--multicluster-runtime-provider kcp`), the backend:
+
+- Connects to kcp workspaces through APIExports
+- Manages resources across logical clusters  
+- Supports advanced multi-tenancy features
+- Enables workspace-based isolation
+
+#### Default Provider
+
+The default provider works with standard Kubernetes clusters and provides:
+
+- Direct cluster connectivity
+- Namespace-based isolation
+- Standard RBAC integration
+
+## API Changes
+
+The backend now supports the v1alpha2 API with significant architectural improvements:
+
+- **Resource-Based Exports**: APIServiceExport now uses resource references instead of embedded CRDs
+- **BoundSchema Support**: Integration with BoundSchema resources for better schema management
+- **Multi-Resource Support**: Single exports can reference multiple CRDs efficiently
+
+## Controllers
+
+The backend includes several controllers for managing the export/binding lifecycle:
+
+- **ClusterBinding Controller**: Manages cluster binding lifecycle
+- **ServiceExport Controller**: Handles APIServiceExport resources
+- **ServiceExportRequest Controller**: Processes export requests
+- **ServiceNamespace Controller**: Manages namespace isolation

docs/content/developers/konnector/controllers/cluster/apiserviceexport.md

@@ -1,13 +1,21 @@
 # APIServiceExports
 
-The APIServiceExport controller watches `APIServiceExports` and the referenced `CustomResourceDefinitions` (CRDs) in the **provider cluster**.
+The APIServiceExport controller watches `APIServiceExports` and the referenced resources in the **provider cluster**.
 
-It is responsible for:
+Starting with v1alpha2, the APIServiceExport has been refactored to use a resource-based model instead of embedded CRD specifications.
+
+## Key Changes in v1alpha2
+
+- **Resource-Based Model**: `APIServiceExportSpec` now uses `Resources []APIServiceExportResource` instead of embedded CRD specs
+- **Multi-Resource Support**: One APIServiceExport can reference multiple CRDs more efficiently
+- **BoundSchema Integration**: Works with the new `BoundSchema` resource type for tracking bound schemas in consumer clusters
+
+## Controller Responsibilities
 
 * Ensuring the existence and validity of `APIServiceExports`.
 * Managing the lifecycle of `APIServiceExports` by starting and stopping spec and status syncers and controllers.
 * Checking `APIServiceBinding` condition and setting `ConsumerInSync` condition in `APIServiceExport`
-* Copying conditions from the referenced CRDs to the `APIServiceExport` status.
+* Managing resource references and their associated schemas.
 
 ## Overview
 

docs/content/developers/konnector/controllers/cluster/boundschema.md

@@ -0,0 +1,42 @@
+# BoundSchema
+
+The BoundSchema controller manages `BoundSchema` resources in the consumer cluster, introduced in v1alpha2.
+
+`BoundSchema` represents bound API resource schemas in consumer clusters and tracks the underlying status of synced resources.
+
+## Key Features
+
+- **Schema Validation**: Ensures the bound schema is valid and properly applied
+- **Drift Detection**: Monitors for differences between expected and actual schema state  
+- **Condition Management**: Provides status conditions for validation and drift detection
+
+## BoundSchema Structure
+
+```yaml
+apiVersion: kube-bind.io/v1alpha2
+kind: BoundSchema
+metadata:
+  labels:
+    kube-bind.io/exported: "true"
+  name: cowboys.wildwest.dev
+  namespace: kube-bind-flsd8
+spec:
+  group: wildwest.dev
+  informerScope: Namespaced
+  names:
+    kind: Cowboy
+    listKind: CowboyList
+    plural: cowboys
+    singular: cowboy
+  scope: Namespaced
+  versions: ...
+```
+
+## Integration with APIServiceExport
+
+BoundSchema works closely with the APIServiceExport resource-based model:
+
+1. APIServiceExport references multiple resources via `Resources []APIServiceExportResource`
+2. Each resource can map to a BoundSchema in the consumer cluster
+3. BoundSchema tracks the actual application and status of these schemas
+4. This enables better multi-resource management and status tracking