From 3b908f86f677a25dd4952e606cac2ab9cec4398a Mon Sep 17 00:00:00 2001 From: Marvin Beckers Date: Thu, 17 Apr 2025 15:59:36 +0200 Subject: [PATCH] Rename provider `virtualworkspace` to `apiexport` and add some docs On-behalf-of: SAP Signed-off-by: Marvin Beckers --- README.md | 4 ++-- {virtualworkspace => apiexport}/cache.go | 2 +- {virtualworkspace => apiexport}/cluster.go | 2 +- apiexport/doc.go | 24 +++++++++++++++++++ .../forked_cache_reader.go | 2 +- {virtualworkspace => apiexport}/indexes.go | 2 +- .../indexes_test.go | 2 +- {virtualworkspace => apiexport}/provider.go | 21 +++++++++------- {virtualworkspace => apiexport}/wildcard.go | 4 ++-- examples/apiexport/README.md | 2 +- examples/apiexport/main.go | 6 ++--- .../manifests/{objects.yaml => bundle.yaml} | 0 examples/apiexport/manifests/workspace.yaml | 24 +++++++++++++++++++ hack/verify-boilerplate.sh | 6 ++--- test/e2e/apiexport_test.go | 6 ++--- 15 files changed, 79 insertions(+), 28 deletions(-) rename {virtualworkspace => apiexport}/cache.go (99%) rename {virtualworkspace => apiexport}/cluster.go (99%) create mode 100644 apiexport/doc.go rename {virtualworkspace => apiexport}/forked_cache_reader.go (99%) rename {virtualworkspace => apiexport}/indexes.go (98%) rename {virtualworkspace => apiexport}/indexes_test.go (99%) rename {virtualworkspace => apiexport}/provider.go (89%) rename {virtualworkspace => apiexport}/wildcard.go (98%) rename examples/apiexport/manifests/{objects.yaml => bundle.yaml} (100%) create mode 100644 examples/apiexport/manifests/workspace.yaml diff --git a/README.md b/README.md index 86e75d6..e21ca47 100644 --- a/README.md +++ b/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 diff --git a/virtualworkspace/cache.go b/apiexport/cache.go similarity index 99% rename from virtualworkspace/cache.go rename to apiexport/cache.go index 864d994..bf6ea0a 100644 --- a/virtualworkspace/cache.go +++ b/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" diff --git a/virtualworkspace/cluster.go b/apiexport/cluster.go similarity index 99% rename from virtualworkspace/cluster.go rename to apiexport/cluster.go index 7403dec..f28b2ae 100644 --- a/virtualworkspace/cluster.go +++ b/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" diff --git a/apiexport/doc.go b/apiexport/doc.go new file mode 100644 index 0000000..2695735 --- /dev/null +++ b/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 diff --git a/virtualworkspace/forked_cache_reader.go b/apiexport/forked_cache_reader.go similarity index 99% rename from virtualworkspace/forked_cache_reader.go rename to apiexport/forked_cache_reader.go index 9b67242..9f9b006 100644 --- a/virtualworkspace/forked_cache_reader.go +++ b/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" diff --git a/virtualworkspace/indexes.go b/apiexport/indexes.go similarity index 98% rename from virtualworkspace/indexes.go rename to apiexport/indexes.go index 114c73f..6c5d50a 100644 --- a/virtualworkspace/indexes.go +++ b/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" diff --git a/virtualworkspace/indexes_test.go b/apiexport/indexes_test.go similarity index 99% rename from virtualworkspace/indexes_test.go rename to apiexport/indexes_test.go index 381f5ba..ef99407 100644 --- a/virtualworkspace/indexes_test.go +++ b/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" diff --git a/virtualworkspace/provider.go b/apiexport/provider.go similarity index 89% rename from virtualworkspace/provider.go rename to apiexport/provider.go index d6dabbd..26fa5b3 100644 --- a/virtualworkspace/provider.go +++ b/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,10 +61,10 @@ 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 @@ -70,9 +72,10 @@ type Options struct { 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() diff --git a/virtualworkspace/wildcard.go b/apiexport/wildcard.go similarity index 98% rename from virtualworkspace/wildcard.go rename to apiexport/wildcard.go index 9f3eb27..0605056 100644 --- a/virtualworkspace/wildcard.go +++ b/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) diff --git a/examples/apiexport/README.md b/examples/apiexport/README.md index 909d351..65d1af7 100644 --- a/examples/apiexport/README.md +++ b/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 diff --git a/examples/apiexport/main.go b/examples/apiexport/main.go index 16106cf..05c60bd 100644 --- a/examples/apiexport/main.go +++ b/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) diff --git a/examples/apiexport/manifests/objects.yaml b/examples/apiexport/manifests/bundle.yaml similarity index 100% rename from examples/apiexport/manifests/objects.yaml rename to examples/apiexport/manifests/bundle.yaml diff --git a/examples/apiexport/manifests/workspace.yaml b/examples/apiexport/manifests/workspace.yaml new file mode 100644 index 0000000..e96d882 --- /dev/null +++ b/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 diff --git a/hack/verify-boilerplate.sh b/hack/verify-boilerplate.sh index f01c711..ef1c3fd 100755 --- a/hack/verify-boilerplate.sh +++ b/hack/verify-boilerplate.sh @@ -25,7 +25,7 @@ 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 \ @@ -33,11 +33,11 @@ _tools/boilerplate -boilerplates hack/boilerplate/kubernetes \ -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 \ No newline at end of file + envtest/workspaces.go diff --git a/test/e2e/apiexport_test.go b/test/e2e/apiexport_test.go index 72191d6..dd9e42b 100644 --- a/test/e2e/apiexport_test.go +++ b/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'")