address reviews

Signed-off-by: Mangirdas Judeikis <mangirdas@judeikis.lt>

Author: mjudeikis

backend/options/options.go

@@ -154,7 +154,7 @@ func (options *Options) AddFlags(fs *pflag.FlagSet) {
 	// TODO(mjudeikis): remove deprecated flag in future release
 	fs.StringVar(&options.Isolation, "cluster-scoped-isolation", options.Isolation, "How cluster scoped service objects are isolated between multiple consumers on the provider side. Among the choices, \"prefixed\" prepends the name of the cluster namespace to an object's name; \"namespaced\" maps a consumer side object into a namespaced object inside the corresponding cluster namespace; \"none\" is used for the case of a dedicated provider where isolation is not necessary.")
 	_ = fs.MarkDeprecated("cluster-scoped-isolation", "use --isolation instead")
-	fs.StringVar(&options.Isolation, "isolation", options.Isolation, "Deprecated: use --cluster-scoped-isolation instead. How cluster scoped service objects are isolated between multiple consumers on the provider side. Among the choices, \"prefixed\" prepends the name of the cluster namespace to an object's name; \"namespaced\" maps a consumer side object into a namespaced object inside the corresponding cluster namespace; \"none\" is used for the case of a dedicated provider where isolation is not necessary.")
+	fs.StringVar(&options.Isolation, "isolation", options.Isolation, "Deprecated: use --isolation instead. How cluster scoped service objects are isolated between multiple consumers on the provider side. Among the choices, \"prefixed\" prepends the name of the cluster namespace to an object's name; \"namespaced\" maps a consumer side object into a namespaced object inside the corresponding cluster namespace; \"none\" is used for the case of a dedicated provider where isolation is not necessary.")
 	fs.StringVar(&options.ExternalAddress, "external-address", options.ExternalAddress, "The external address for the service provider cluster, including https:// and port. If not specified, service account's hosts are used.")
 	fs.StringVar(&options.ExternalCAFile, "external-ca-file", options.ExternalCAFile, "The external CA file for the service provider cluster. If not specified, service account's CA is used.")
 	fs.StringVar(&options.TLSExternalServerName, "external-server-name", options.TLSExternalServerName, "The external (TLS) server name used by consumers to talk to the service provider cluster. This can be useful to select the right certificate via SNI.")

cli/pkg/kubectl/dev/plugin/create.go

@@ -70,32 +70,25 @@ type DevOptions struct {
 	KindNetwork         string
 }
 
-// assetVersion is the version of the kube-bind backend assets used in dev mode
-var assetVersion = ""
-
 // fallbackAssetVersion is used when unable to fetch the latest version
-var fallbackAssetVersion = "0.6.0"
+const fallbackAssetVersion = "0.6.0"
 
-// GitHubRelease represents a GitHub release response
-type GitHubRelease struct {
+// gitHubRelease represents a GitHub release response
+type gitHubRelease struct {
 	TagName string `json:"tag_name"`
 }
 
 // NewDevOptions creates a new DevOptions
 func NewDevOptions(streams genericclioptions.IOStreams) *DevOptions {
 	opts := base.NewOptions(streams)
-	// Initialize assetVersion with fallback if not set
-	if assetVersion == "" {
-		assetVersion = fallbackAssetVersion
-	}
 	return &DevOptions{
 		Options:             opts,
 		Logs:                logs.NewOptions(),
 		Streams:             streams,
 		ProviderClusterName: "kind-provider",
 		ConsumerClusterName: "kind-consumer",
 		ChartPath:           "oci://ghcr.io/kube-bind/charts/backend",
-		ChartVersion:        assetVersion,
+		ChartVersion:        fallbackAssetVersion,
 	}
 }
 
@@ -110,14 +103,15 @@ func (o *DevOptions) AddCmdFlags(cmd *cobra.Command) {
 	cmd.Flags().StringVar(&o.ChartPath, "chart-path", o.ChartPath, "Helm chart path or OCI registry URL")
 	cmd.Flags().StringVar(&o.ChartVersion, "chart-version", o.ChartVersion, "Helm chart version")
 	cmd.Flags().StringVar(&o.Image, "image", "ghcr.io/kube-bind/backend", "kube-bind backend image to use in dev mode")
-	cmd.Flags().StringVar(&o.Tag, "tag", "v"+assetVersion, "kube-bind backend image tag to use in dev mode")
+	cmd.Flags().StringVar(&o.Tag, "tag", "", "kube-bind backend image tag to use in dev mode")
 	cmd.Flags().StringVar(&o.KindNetwork, "kind-network", "kube-bind-dev", "kind network to use in dev mode")
 }
 
 // Complete completes the options
 func (o *DevOptions) Complete(args []string) error {
-	// Only fetch the latest version if assetVersion is not set
-	if assetVersion == "" {
+	// Only fetch the latest version if tag is not set
+	var assetVersion string
+	if o.Tag == "" {
 		version, err := fetchLatestRelease()
 		if err != nil {
 			// Log the error but continue with fallback version
@@ -164,7 +158,7 @@ func fetchLatestRelease() (string, error) {
 		return "", fmt.Errorf("failed to read response body: %w", err)
 	}
 
-	var release GitHubRelease
+	var release gitHubRelease
 	if err := json.Unmarshal(body, &release); err != nil {
 		return "", fmt.Errorf("failed to parse release data: %w", err)
 	}
@@ -173,7 +167,6 @@ func fetchLatestRelease() (string, error) {
 		return "", fmt.Errorf("no tag name in release data")
 	}
 
-	// Remove 'v' prefix if present
 	version := strings.TrimPrefix(release.TagName, "v")
 	return version, nil
 }

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

@@ -62,7 +62,7 @@ spec:
       crd: {}
   - group: kube-bind.io
     name: apiserviceexports
-    schema: v251230-e36591a1.apiserviceexports.kube-bind.io
+    schema: v260119-2e5a3e93.apiserviceexports.kube-bind.io
     storage:
       crd: {}
   - group: kube-bind.io

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

@@ -1,7 +1,7 @@
 apiVersion: apis.kcp.io/v1alpha1
 kind: APIResourceSchema
 metadata:
-  name: v251230-e36591a1.apiserviceexports.kube-bind.io
+  name: v260119-2e5a3e93.apiserviceexports.kube-bind.io
 spec:
   conversion:
     strategy: None
@@ -466,7 +466,8 @@ spec:
               description: |-
                 ClusterScopedIsolation specifies how cluster scoped service objects are isolated between multiple consumers on the provider side.
                 It can be "Prefixed", "Namespaced", or "None".
-                Deprecated: use Isolation instead.
+
+                Deprecated: ClusterScopedIsolation is deprecated, use Isolation instead.
               enum:
               - Prefixed
               - Namespaced
@@ -491,9 +492,8 @@ spec:
               - message: informerScope is immutable
                 rule: self == oldSelf
             isolation:
-              description: |-
-                Isolation specifies how service objects are isolated between multiple consumers on the provider side.
-                It can be "Prefixed", "Namespaced", or "None".
+              description: Isolation specifies how service objects are isolated between
+                multiple consumers on the provider side.
               enum:
               - Prefixed
               - Namespaced

deploy/charts/backend/crds/kube-bind.io_apiserviceexports.yaml

@@ -469,7 +469,8 @@ spec:
                 description: |-
                   ClusterScopedIsolation specifies how cluster scoped service objects are isolated between multiple consumers on the provider side.
                   It can be "Prefixed", "Namespaced", or "None".
-                  Deprecated: use Isolation instead.
+
+                  Deprecated: ClusterScopedIsolation is deprecated, use Isolation instead.
                 enum:
                 - Prefixed
                 - Namespaced
@@ -494,9 +495,8 @@ spec:
                 - message: informerScope is immutable
                   rule: self == oldSelf
               isolation:
-                description: |-
-                  Isolation specifies how service objects are isolated between multiple consumers on the provider side.
-                  It can be "Prefixed", "Namespaced", or "None".
+                description: Isolation specifies how service objects are isolated
+                  between multiple consumers on the provider side.
                 enum:
                 - Prefixed
                 - Namespaced

deploy/crd/kube-bind.io_apiserviceexports.yaml

@@ -470,7 +470,8 @@ spec:
                 description: |-
                   ClusterScopedIsolation specifies how cluster scoped service objects are isolated between multiple consumers on the provider side.
                   It can be "Prefixed", "Namespaced", or "None".
-                  Deprecated: use Isolation instead.
+
+                  Deprecated: ClusterScopedIsolation is deprecated, use Isolation instead.
                 enum:
                 - Prefixed
                 - Namespaced
@@ -495,9 +496,8 @@ spec:
                 - message: informerScope is immutable
                   rule: self == oldSelf
               isolation:
-                description: |-
-                  Isolation specifies how service objects are isolated between multiple consumers on the provider side.
-                  It can be "Prefixed", "Namespaced", or "None".
+                description: Isolation specifies how service objects are isolated
+                  between multiple consumers on the provider side.
                 enum:
                 - Prefixed
                 - Namespaced

docs/content/developers/architecture.md

@@ -2,6 +2,9 @@
 
 This document provides detailed architecture diagrams and explanations for how kube-bind handles resource synchronization between consumer and provider clusters, with a focus on isolation strategies and namespace mapping.
 
+This is development-focused documentation intended to help contributors understand the internal workings of kube-bind.
+If you are looking for user-focused documentation, please refer to the [Synchronization User Guide](../usage/synchronization.md).
+
 ## Cluster-Scoped Resources
 
 Cluster-scoped resources (like Sheriffs in our examples) can use different isolation strategies to control how they are placed on the provider cluster and how their associated secrets are isolated.

pkg/konnector/controllers/cluster/serviceexport/serviceexport_reconcile.go

@@ -280,7 +280,8 @@ func (r *reconciler) ensureControllerForSchema(ctx context.Context, export *kube
 		isolationStrategy = isolation.NewNamespaced(r.providerNamespace)
 	default:
 		// Default to None isolation strategy if no valid isolation strategy is specified
-		logger.V(4).Info("Using default None isolation strategy", "export", export.Name)
+		// This should never happen due to validation, but we add this as a safety net.
+		logger.V(2).Info("Using default None isolation strategy", "export", export.Name)
 		isolationStrategy = isolation.NewNone(r.providerNamespace, providerNamespaceUID)
 	}
 

pkg/resources/resources.go

@@ -208,7 +208,7 @@ func IsClaimedWithReference(
 
 			if !isReferenceAllowed(ref, apiServiceExport) {
 				logger.Info("reference not allowed, resource is not part of the contract",
-					"isolation", apiServiceExport.Spec.ClusterScopedIsolation,
+					"isolation", apiServiceExport.Spec.Isolation,
 					"referenceGroup", ref.Group,
 					"referenceResource", ref.Resource,
 				)
@@ -254,7 +254,7 @@ func IsClaimedWithReference(
 
 	if consumerSide {
 		logger.Info("checking claim on consumer side")
-		result := IsClaimed(logger, claim.Selector, copy, potentiallyReferencedResources, apiServiceExport.Spec.ClusterScopedIsolation)
+		result := IsClaimed(logger, claim.Selector, copy, potentiallyReferencedResources, apiServiceExport.Spec.Isolation)
 		logger.Info("IsClaimed result", "result", result)
 		return result
 	}
@@ -280,14 +280,14 @@ func IsClaimedWithReference(
 		copy.SetNamespace(sn.Name)
 	}
 
-	result := IsClaimed(logger, claim.Selector, copy, potentiallyReferencedResources, apiServiceExport.Spec.ClusterScopedIsolation)
+	result := IsClaimed(logger, claim.Selector, copy, potentiallyReferencedResources, apiServiceExport.Spec.Isolation)
 	logger.V(4).Info("IsClaimed result (provider side)", "result", result)
 	return result
 }
 
 func isReferenceAllowed(ref kubebindv1alpha2.SelectorReference, apiServiceExport *kubebindv1alpha2.APIServiceExport) bool {
 	// If isolation is None, everything should be allowed, as both ends are owned.
-	if apiServiceExport.Spec.ClusterScopedIsolation == kubebindv1alpha2.IsolationNone {
+	if apiServiceExport.Spec.Isolation == kubebindv1alpha2.IsolationNone {
 		return true
 	}
 	for _, resource := range apiServiceExport.Spec.Resources {

pkg/resources/resources_test.go

@@ -1129,8 +1129,8 @@ func TestReferenceSelector_IsolationMode(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			export := &kubebindv1alpha2.APIServiceExport{
 				Spec: kubebindv1alpha2.APIServiceExportSpec{
-					ClusterScopedIsolation: tt.isolation,
-					Resources:              tt.exportedResources,
+					Isolation: tt.isolation,
+					Resources: tt.exportedResources,
 				},
 			}
 			got := isReferenceAllowed(tt.reference, export)