Rework & simplify documentation (#366)

* rework & simplify documentation

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

Author: mjudeikis

Makefile

@@ -409,33 +409,42 @@ build-web:
 PLATFORMS ?= linux/$(ARCH)
 .PHONY: image-local
 image-local:
-	@echo "Building multi-arch images locally with tag $(REV) for platforms: $(PLATFORMS)"
+	@echo "Building images locally with tag $(REV) for platforms: $(PLATFORMS)"
 	@command -v docker >/dev/null 2>&1 || { echo "docker not found. Please install Docker"; exit 1; }
 	@docker buildx version >/dev/null 2>&1 || { echo "docker buildx not found. Please enable buildx in Docker"; exit 1; }
 
 	@# Create buildx builder if it doesn't exist
 	@docker buildx create --name kube-bind-builder --use 2>/dev/null || docker buildx use kube-bind-builder 2>/dev/null || true
 	@docker buildx inspect --bootstrap >/dev/null 2>&1
 
-	@echo "Building konnector multi-arch image locally..."
+	@# Check if building for multiple platforms
+	@if [[ "$(PLATFORMS)" == *","* ]]; then \
+		echo "Multi-platform build detected. Images will be pushed to registry instead of loaded locally."; \
+		LOAD_FLAG="--push"; \
+	else \
+		echo "Single platform build. Images will be loaded to local Docker daemon."; \
+		LOAD_FLAG="--load"; \
+	fi && \
+	\
+	echo "Building konnector image..." && \
 	docker buildx build \
 		--platform $(PLATFORMS) \
 		--build-arg LDFLAGS="$(LDFLAGS)" \
 		-t $(IMAGE_REPO)/konnector:$(REV) \
 		-f Dockerfile.konnector \
-		--load .
-
-	@echo "Building backend multi-arch image locally..."
+		$$LOAD_FLAG . && \
+	\
+	echo "Building backend image..." && \
 	docker buildx build \
 		--platform $(PLATFORMS) \
 		--build-arg LDFLAGS="$(LDFLAGS)" \
 		-t $(IMAGE_REPO)/backend:$(REV) \
 		-f Dockerfile \
-		--load .
-
-	@echo "Successfully built multi-arch local images:"
-	@echo "  $(IMAGE_REPO)/konnector:$(REV) ($(PLATFORMS))"
-	@echo "  $(IMAGE_REPO)/backend:$(REV) ($(PLATFORMS))"
+		$$LOAD_FLAG . && \
+	\
+	echo "Successfully built images:" && \
+	echo "  $(IMAGE_REPO)/konnector:$(REV) ($(PLATFORMS))" && \
+	echo "  $(IMAGE_REPO)/backend:$(REV) ($(PLATFORMS))"
 
 # Kind cluster configuration
 KIND_CLUSTER ?= kube-bind

cli/pkg/kubectl/bind-apiservice/cmd/cmd.go

@@ -35,11 +35,8 @@ var (
 	# bind to a remote API service. Use kubectl bind to create the APIServiceExportRequest interactively.
 	%[1]s apiservice --remote-kubeconfig file -f apiservice-export-request.yaml
 
-	# bind to a remote API service via a request manifest from a https URL.
-	%[1]s apiservice --remote-kubeconfig file https://some-url.com/apiservice-export-requests.yaml
-
-	# bind to a API service directly without any remote agent or service provider.
-	%[1]s apiservice --remote-kubeconfig file -n remote-namespace resources.group/v1
+	# bind to a remote API using template name
+	%[1]s apiservice --name my-api --template-name database-service
 	`
 )
 

cli/pkg/kubectl/bind-apiservice/plugin/bind.go

@@ -324,9 +324,9 @@ func (b *BindAPIServiceOptions) bindTemplate(ctx context.Context) (*bindTemplate
 		return nil, err
 	}
 	if created {
-		fmt.Fprintf(b.Options.IOStreams.ErrOut, "Created secret %s/%s for host %s, namespace %s\n", "kube-bind", secret.Name, remoteHost, remoteNamespace)
+		fmt.Fprintf(b.Options.IOStreams.ErrOut, "🔒 Created secret %s/%s for host %s, namespace %s\n", "kube-bind", secret.Name, remoteHost, remoteNamespace)
 	} else {
-		fmt.Fprintf(b.Options.IOStreams.ErrOut, "Updated secret %s/%s for host %s, namespace %s\n", "kube-bind", secret.Name, remoteHost, remoteNamespace)
+		fmt.Fprintf(b.Options.IOStreams.ErrOut, "🔒 Updated secret %s/%s for host %s, namespace %s\n", "kube-bind", secret.Name, remoteHost, remoteNamespace)
 	}
 	return &bindTemplateResult{
 		response:  bindResponse,

cli/pkg/kubectl/bind-apiservice/plugin/binder.go

@@ -66,6 +66,17 @@ func NewBinder(config *rest.Config, opts *BinderOptions) *Binder {
 // https://github.com/kube-bind/kube-bind/issues/360
 
 func (b *Binder) BindFromFile(ctx context.Context) ([]*kubebindv1alpha2.APIServiceBinding, error) {
+	// Generate the kubectl command that would be equivalent
+	remoteFlags := ""
+	if b.opts.RemoteKubeconfigFile != "" {
+		remoteFlags = fmt.Sprintf("--remote-kubeconfig %s", b.opts.RemoteKubeconfigFile)
+	} else if b.opts.RemoteKubeconfigNamespace != "" && b.opts.RemoteKubeconfigName != "" {
+		remoteFlags = fmt.Sprintf("--remote-kubeconfig-namespace %s --remote-kubeconfig-name %s", b.opts.RemoteKubeconfigNamespace, b.opts.RemoteKubeconfigName)
+	}
+	fmt.Fprintf(b.opts.IOStreams.ErrOut, "🚀 Executing: kubectl bind apiservice %s -f -\n", remoteFlags)
+	fmt.Fprintf(b.opts.IOStreams.ErrOut, "✨ Use \"-o yaml\" and \"--dry-run\" to get the APIServiceExportRequest.\n")
+	fmt.Fprintf(b.opts.IOStreams.ErrOut, "    and pass it to \"kubectl bind apiservice\" directly. Great for automation.\n")
+
 	// Ensure client side namespace exists
 	err := b.ensureClientSideNamespaceExists(ctx)
 	if err != nil {
@@ -99,9 +110,9 @@ func (b *Binder) BindFromFile(ctx context.Context) ([]*kubebindv1alpha2.APIServi
 	}
 
 	if created {
-		fmt.Fprintf(b.opts.IOStreams.ErrOut, "Created secret %s/%s for host %s, namespace %s\n", "kube-bind", secret.Name, remoteHost, remoteNamespace)
+		fmt.Fprintf(b.opts.IOStreams.ErrOut, "🔒 Created secret %s/%s for host %s, namespace %s\n", "kube-bind", secret.Name, remoteHost, remoteNamespace)
 	} else {
-		fmt.Fprintf(b.opts.IOStreams.ErrOut, "Updated secret %s/%s for host %s, namespace %s\n", "kube-bind", secret.Name, remoteHost, remoteNamespace)
+		fmt.Fprintf(b.opts.IOStreams.ErrOut, "🔒 Updated secret %s/%s for host %s, namespace %s\n", "kube-bind", secret.Name, remoteHost, remoteNamespace)
 	}
 
 	if b.opts.DryRun {
@@ -184,9 +195,9 @@ func (b *Binder) BindFromResponse(ctx context.Context, response *kubebindv1alpha
 	}
 
 	if created {
-		fmt.Fprintf(b.opts.IOStreams.ErrOut, "Created secret %s/%s for host %s, namespace %s\n", "kube-bind", secret.Name, remoteHost, remoteNamespace)
+		fmt.Fprintf(b.opts.IOStreams.ErrOut, "🔒 Created secret %s/%s for host %s, namespace %s\n", "kube-bind", secret.Name, remoteHost, remoteNamespace)
 	} else {
-		fmt.Fprintf(b.opts.IOStreams.ErrOut, "Updated secret %s/%s for host %s, namespace %s\n", "kube-bind", secret.Name, remoteHost, remoteNamespace)
+		fmt.Fprintf(b.opts.IOStreams.ErrOut, "🔒 Updated secret %s/%s for host %s, namespace %s\n", "kube-bind", secret.Name, remoteHost, remoteNamespace)
 	}
 
 	if b.opts.DryRun {

cli/pkg/kubectl/bind-apiservice/plugin/konnector.go

@@ -68,7 +68,7 @@ func (b *BindAPIServiceOptions) deployKonnector(ctx context.Context, config *res
 	}
 
 	if b.KonnectorImageOverride != "" {
-		fmt.Fprintf(b.Options.ErrOut, "Deploying konnector %s to namespace kube-bind with custom image %q.\n", bindVersion, b.KonnectorImageOverride)
+		fmt.Fprintf(b.Options.ErrOut, "🚀 Deploying konnector %s to namespace kube-bind with custom image %q.\n", bindVersion, b.KonnectorImageOverride)
 		if err := konnector.Bootstrap(ctx, discoveryClient, dynamicClient, b.KonnectorImageOverride); err != nil {
 			return err
 		}
@@ -103,7 +103,7 @@ func (b *BindAPIServiceOptions) deployKonnector(ctx context.Context, config *res
 				}
 			}
 		} else {
-			fmt.Fprintf(b.Options.ErrOut, "Deploying konnector %s to namespace kube-bind.\n", bindVersion)
+			fmt.Fprintf(b.Options.ErrOut, "🚀 Deploying konnector %s to namespace kube-bind.\n", bindVersion)
 			if err := konnector.Bootstrap(ctx, discoveryClient, dynamicClient, konnectorImage); err != nil {
 				return err
 			}

cli/pkg/kubectl/bind-apiservice/plugin/secret.go

@@ -76,9 +76,9 @@ func (b *BindAPIServiceOptions) ensureKubeconfigSecretWithLogging(ctx context.Co
 
 	if b.remoteKubeconfigFile != "" {
 		if created {
-			fmt.Fprintf(b.Options.ErrOut, "Created secret %s/%s for host %s, namespace %s\n", "kube-bind", secret.Name, remoteHost, remoteNamespace)
+			fmt.Fprintf(b.Options.ErrOut, "🔒 Created secret %s/%s for host %s, namespace %s\n", "kube-bind", secret.Name, remoteHost, remoteNamespace)
 		} else {
-			fmt.Fprintf(b.Options.ErrOut, "Updated secret %s/%s for host %s, namespace %s\n", "kube-bind", secret.Name, remoteHost, remoteNamespace)
+			fmt.Fprintf(b.Options.ErrOut, "🔒 Updated secret %s/%s for host %s, namespace %s\n", "kube-bind", secret.Name, remoteHost, remoteNamespace)
 		}
 	}
 

cli/pkg/kubectl/bind-apiservice/plugin/servicebindings.go

@@ -106,6 +106,6 @@ func (b *BindAPIServiceOptions) createAPIServiceBindings(ctx context.Context, co
 		return nil, err
 	}
 
-	fmt.Fprintf(b.Options.IOStreams.ErrOut, "Created APIServiceBinding %s for %d resources\n", bindingName, len(request.Spec.Resources))
+	fmt.Fprintf(b.Options.IOStreams.ErrOut, "✅ Created APIServiceBinding %s for %d resources\n", bindingName, len(request.Spec.Resources))
 	return []*kubebindv1alpha2.APIServiceBinding{created}, nil
 }

cli/pkg/kubectl/bind-collections/cmd/cmd.go

@@ -32,14 +32,12 @@ var (
 	# List collections from currently authenticated server
 	%[1]s collections
 
-	# List collections from specific server 
-	%[1]s collections https://mangodb.com
-
 	# List collections using --server flag to override current server
 	%[1]s collections --server https://mangodb.com
 
-	# List collections with JSON output
+	# List collections with JSON/YAML output
 	%[1]s collections -o json
+	%[1]s collections -o yaml
 	`
 )
 

cli/pkg/kubectl/bind-login/plugin/login.go

@@ -209,10 +209,10 @@ func (o *LoginOptions) Run(ctx context.Context, authURLCh chan<- string) error {
 	}
 
 	if token.Cluster != "" {
-		fmt.Fprintf(o.Streams.ErrOut, "Successfully authenticated to %s (cluster: %s)\n", serverHost.Host, token.Cluster)
-		fmt.Fprintf(o.Streams.ErrOut, "  Server key: %s\n", fmt.Sprintf("%s@%s", serverURL, token.Cluster))
+		fmt.Fprintf(o.Streams.ErrOut, "🔑 Successfully authenticated to %s (cluster: %s)\n", serverHost.Host, token.Cluster)
+		fmt.Fprintf(o.Streams.ErrOut, "   Server key: %s\n", fmt.Sprintf("%s@%s", serverURL, token.Cluster))
 	} else {
-		fmt.Fprintf(o.Streams.ErrOut, "Successfully authenticated to %s\n", serverHost.Host)
+		fmt.Fprintf(o.Streams.ErrOut, "🔑 Successfully authenticated to %s\n", serverHost.Host)
 	}
 
 	if o.ShowToken {

cli/pkg/kubectl/bind-templates/cmd/cmd.go

@@ -33,13 +33,14 @@ var (
 	%[1]s templates
 
 	# List templates from specific server 
-	%[1]s templates https://mangodb.com
+	%[1]s templates
 
 	# List templates using --server flag to override current server
 	%[1]s templates --server https://mangodb.com
 
-	# List templates with JSON output
+	# List templates with JSON/YAML output
 	%[1]s templates -o json
+	%[1]s templates -o yaml
 	`
 )