Rename provider virtualworkspace to apiexport and add some docs

README.md

@@ -4,11 +4,11 @@ This repository contains an **experimental** provider implementation for [multic
 
 ## Providers
 
-This repository is planned to contain multiple [`Provider`](https://github.com/multicluster-runtime/multicluster-runtime/blob/223b19b990050e373880d57211c90ce86c53fd80/pkg/multicluster/multicluster.go#L52) implementations depending on how your controllers are supposed to interact with kcp.
+This repository is expected to contain multiple [`Provider`](https://github.com/multicluster-runtime/multicluster-runtime/blob/223b19b990050e373880d57211c90ce86c53fd80/pkg/multicluster/multicluster.go#L52) implementations depending on how your controllers are supposed to interact with kcp.
 
 Currently available are:
 
-- [virtualworkspace](./virtualworkspace/): for interacting with virtual workspaces like the `APIExport` one.
+- [apiexport](./apiexport/): for interacting with the [`APIExport` virtual workspace](https://docs.kcp.io/kcp/latest/concepts/apis/exporting-apis/#build-your-controller) (or virtual workspaces with the same semantics).
 
 ## Examples
 

virtualworkspace/cache.go → apiexport/cache.go

@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-package virtualworkspace
+package apiexport
 
 import (
 	"context"

virtualworkspace/cluster.go → apiexport/cluster.go

@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-package virtualworkspace
+package apiexport
 
 import (
 	"context"

apiexport/doc.go

@@ -0,0 +1,24 @@
+/*
+Copyright 2025 The KCP 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 apiexport provides a [sigs.k8s.io/multicluster-runtime] provider implementation for interacting with
+APIExport virtual workspaces exposed by a [kcp] instance. This provider can be used for writing controllers
+that reconcile APIs exposed via APIExport objects.
+
+[kcp]: https://kcp.io
+*/
+package apiexport

virtualworkspace/forked_cache_reader.go → apiexport/forked_cache_reader.go

@@ -17,7 +17,7 @@ limitations under the License.
 // This file has been forked from https://github.com/kubernetes-sigs/controller-runtime/blob/78b3ce63cf927debb122dd641290a89d20d776e3/pkg/cache/internal/cache_reader.go.
 // It's been modified to allow scoping a CacheReader to a specific logical cluster.
 
-package virtualworkspace
+package apiexport
 
 import (
 	"context"

virtualworkspace/indexes.go → apiexport/indexes.go

@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-package virtualworkspace
+package apiexport
 
 import (
 	"fmt"

virtualworkspace/indexes_test.go → apiexport/indexes_test.go

@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-package virtualworkspace
+package apiexport
 
 import (
 	"testing"

virtualworkspace/provider.go → apiexport/provider.go

@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-package virtualworkspace
+package apiexport
 
 import (
 	"context"
@@ -44,8 +44,10 @@ import (
 
 var _ multicluster.Provider = &Provider{}
 
-// Provider is a cluster provider that represents each logical cluster in the
-// kcp sense as a cluster in the multicluster-runtime sense.
+// Provider is a [sigs.k8s.io/multicluster-runtime/pkg/multicluster.Provider] that represents each [logical cluster]
+// (in the kcp sense) exposed via a APIExport virtual workspace as a cluster in the [sigs.k8s.io/multicluster-runtime] sense.
+//
+// [logical cluster]: https://docs.kcp.io/kcp/latest/concepts/terminology/#logical-cluster
 type Provider struct {
 	config *rest.Config
 	scheme *runtime.Scheme
@@ -59,20 +61,21 @@ type Provider struct {
 	cancelFns map[logicalcluster.Name]context.CancelFunc
 }
 
-// Options are the options for creating a new kcp virtual workspace provider.
+// Options are the options for creating a new instance of the apiexport provider.
 type Options struct {
-	// Scheme is the scheme to use for the provider. It defaults to the
-	// client-go scheme.
+	// Scheme is the scheme to use for the provider. If this is nil, it defaults
+	// to the client-go scheme.
 	Scheme *runtime.Scheme
 
 	// WildcardCache is the wildcard cache to use for the provider. If this is
 	// nil, a new wildcard cache will be created for the given rest.Config.
 	WildcardCache WildcardCache
 }
 
-// New creates a new kcp virtual workspace provider. The provided rest.Config
+// New creates a new kcp virtual workspace provider. The provided [rest.Config]
 // must point to a virtual workspace apiserver base path, i.e. up to but without
-// the "/clusters/*" suffix.
+// the '/clusters/*' suffix. This information can be extracted from the APIExport
+// status (deprecated) or an APIExportEndpointSlice status.
 func New(cfg *rest.Config, obj client.Object, options Options) (*Provider, error) {
 	// Do the defaulting controller-runtime would do for those fields we need.
 	if options.Scheme == nil {
@@ -214,7 +217,7 @@ func (p *Provider) Run(ctx context.Context, mgr mcmanager.Manager) error {
 	return g.Wait()
 }
 
-// Get returns a cluster by name.
+// Get returns a [cluster.Cluster] by logical cluster name. Be aware that workspace paths do not work.
 func (p *Provider) Get(_ context.Context, name string) (cluster.Cluster, error) {
 	p.lock.RLock()
 	defer p.lock.RUnlock()

virtualworkspace/wildcard.go → apiexport/wildcard.go

@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-package virtualworkspace
+package apiexport
 
 import (
 	"context"
@@ -40,7 +40,7 @@ import (
 	"github.com/kcp-dev/logicalcluster/v3"
 )
 
-// WildcardCache is a cache that operates on a /clusters/* endpoint.
+// WildcardCache is a cache that operates on a '/clusters/*' endpoint.
 type WildcardCache interface {
 	cache.Cache
 	getSharedInformer(obj runtime.Object) (k8scache.SharedIndexInformer, schema.GroupVersionKind, apimeta.RESTScopeName, error)

examples/apiexport/README.md

@@ -5,7 +5,7 @@ This folder contains an example controller for the `virtualworkspace` provider i
 It can be tested by applying the necessary manifests from the respective folder while connected to the `root` workspace of a kcp instance:
 
 ```sh
-$ kubectl apply -f ./manifests/
+$ kubectl apply -f ./manifests/bundle.yaml
 apiexport.apis.kcp.io/examples-apiexport-multicluster created
 workspacetype.tenancy.kcp.io/examples-apiexport-multicluster created
 workspace.tenancy.kcp.io/example1 created

examples/apiexport/main.go

@@ -24,7 +24,7 @@ import (
 
 	"github.com/spf13/pflag"
 
-	"github.com/kcp-dev/multicluster-provider/virtualworkspace"
+	"github.com/kcp-dev/multicluster-provider/apiexport"
 
 	mcbuilder "sigs.k8s.io/multicluster-runtime/pkg/builder"
 	mcmanager "sigs.k8s.io/multicluster-runtime/pkg/manager"
@@ -61,7 +61,7 @@ func main() {
 
 	var (
 		server   string
-		provider *virtualworkspace.Provider
+		provider *apiexport.Provider
 	)
 
 	pflag.StringVar(&server, "server", "", "Override for kubeconfig server URL")
@@ -79,7 +79,7 @@ func main() {
 	opts := manager.Options{}
 
 	var err error
-	provider, err = virtualworkspace.New(cfg, &apisv1alpha1.APIBinding{}, virtualworkspace.Options{})
+	provider, err = apiexport.New(cfg, &apisv1alpha1.APIBinding{}, apiexport.Options{})
 	if err != nil {
 		entryLog.Error(err, "unable to construct cluster provider")
 		os.Exit(1)

examples/apiexport/manifests/workspace.yaml

@@ -0,0 +1,24 @@
+# Copyright 2025 The KCP 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.
+# 
+# This file allows creating further workspaces from the example bundle.
+
+apiVersion: tenancy.kcp.io/v1alpha1
+kind: Workspace
+metadata:
+  generateName: apiexport-
+spec:
+  type:
+    name: examples-apiexport-multicluster
+    path: root

hack/verify-boilerplate.sh

@@ -25,19 +25,19 @@ echo "Checking file boilerplates…"
 _tools/boilerplate \
   -boilerplates hack/boilerplate \
   -exclude .github \
-  -exclude virtualworkspace/forked_cache_reader.go \
+  -exclude apiexport/forked_cache_reader.go \
   -exclude envtest
 _tools/boilerplate -boilerplates hack/boilerplate/kubernetes \
   -exclude envtest/doc.go \
   -exclude envtest/eventually.go \
   -exclude envtest/scheme.go \
   -exclude envtest/testing.go \
   -exclude envtest/workspaces.go \
-  envtest virtualworkspace/forked_cache_reader.go
+  envtest apiexport/forked_cache_reader.go
 _tools/boilerplate \
   -boilerplates hack/boilerplate \
   envtest/doc.go \
   envtest/eventually.go \
   envtest/scheme.go \
   envtest/testing.go \
-  envtest/workspaces.go
+  envtest/workspaces.go

test/e2e/apiexport_test.go

@@ -47,9 +47,9 @@ import (
 	tenancyv1alpha1 "github.com/kcp-dev/kcp/sdk/apis/tenancy/v1alpha1"
 	"github.com/kcp-dev/logicalcluster/v3"
 
+	"github.com/kcp-dev/multicluster-provider/apiexport"
 	clusterclient "github.com/kcp-dev/multicluster-provider/client"
 	"github.com/kcp-dev/multicluster-provider/envtest"
-	"github.com/kcp-dev/multicluster-provider/virtualworkspace"
 
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -206,7 +206,7 @@ var _ = Describe("VirtualWorkspace Provider", Ordered, func() {
 		var (
 			lock        sync.RWMutex
 			engaged     = sets.NewString()
-			p           *virtualworkspace.Provider
+			p           *apiexport.Provider
 			g           *errgroup.Group
 			cancelGroup context.CancelFunc
 		)
@@ -234,7 +234,7 @@ var _ = Describe("VirtualWorkspace Provider", Ordered, func() {
 			vwConfig := rest.CopyConfig(kcpConfig)
 			vwConfig.Host = vwEndpoint
 			var err error
-			p, err = virtualworkspace.New(vwConfig, &apisv1alpha1.APIBinding{}, virtualworkspace.Options{})
+			p, err = apiexport.New(vwConfig, &apisv1alpha1.APIBinding{}, apiexport.Options{})
 			Expect(err).NotTo(HaveOccurred())
 
 			By("waiting for discovery of the virtual workspace to show 'example.com'")