Improve karmadactl command description

Signed-off-by: lonelyCZ <[email protected]>

pkg/karmadactl/addons/addons.go

@@ -11,6 +11,15 @@ import (
 )
 
 var (
+	addonsLong = templates.LongDesc(`
+		Enable or disable a Karmada addon.
+
+		These addons are currently supported: 
+		
+		1. karmada-descheduler
+		2. karmada-scheduler-estimator
+		3. karmada-search`)
+
 	addonsExamples = templates.Examples(`
 	# Enable or disable Karmada addons to the karmada-host cluster
 	%[1]s addons enable karmada-search
@@ -26,7 +35,7 @@ func NewCmdAddons(parentCommand string) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "addons",
 		Short:   "Enable or disable a Karmada addon",
-		Long:    "Enable or disable a Karmada addon",
+		Long:    addonsLong,
 		Example: fmt.Sprintf(addonsExamples, parentCommand),
 		Annotations: map[string]string{
 			util.TagCommandGroup: util.GroupClusterRegistration,

pkg/karmadactl/cmdinit/cmdinit.go

@@ -13,12 +13,13 @@ import (
 	"github.com/karmada-io/karmada/pkg/version"
 )
 
-const (
-	initShort = `Install Karmada in Kubernetes`
-	initLong  = `Install Karmada in Kubernetes.`
-)
-
 var (
+	initLong = templates.LongDesc(`
+		Install the Karmada control plane in a Kubernetes cluster.
+
+		By default, the images and CRD tarball are downloaded remotely.
+		For offline installation, you can set '--private-image-registry' and '--crds'.`)
+
 	initExamples = templates.Examples(`
 		# Install Karmada in Kubernetes cluster
 		# The karmada-apiserver binds the master node's IP by default
@@ -63,7 +64,7 @@ func NewCmdInit(parentCommand string) *cobra.Command {
 	opts := kubernetes.CommandInitOption{}
 	cmd := &cobra.Command{
 		Use:                   "init",
-		Short:                 initShort,
+		Short:                 "Install the Karmada control plane in a Kubernetes cluster",
 		Long:                  initLong,
 		Example:               initExample(parentCommand),
 		SilenceUsage:          true,

pkg/karmadactl/cordon/cordon.go

@@ -20,11 +20,11 @@ import (
 )
 
 var (
-	cordonShort = `Mark cluster as unschedulable`
-	cordonLong  = `Mark cluster as unschedulable.`
+	cordonLong = templates.LongDesc(`
+		Mark cluster as unschedulable.`)
 
-	uncordonShort = `Mark cluster as schedulable`
-	uncordonLong  = `Mark cluster as schedulable.`
+	uncordonLong = templates.LongDesc(`
+		Mark cluster as schedulable.`)
 
 	cordonExample = templates.Examples(`
 		# Mark cluster "foo" as unschedulable.
@@ -47,7 +47,7 @@ func NewCmdCordon(f util.Factory, parentCommand string) *cobra.Command {
 	opts := CommandCordonOption{}
 	cmd := &cobra.Command{
 		Use:                   "cordon CLUSTER",
-		Short:                 cordonShort,
+		Short:                 "Mark cluster as unschedulable",
 		Long:                  cordonLong,
 		Example:               fmt.Sprintf(cordonExample, parentCommand),
 		SilenceUsage:          true,
@@ -78,7 +78,7 @@ func NewCmdUncordon(f util.Factory, parentCommand string) *cobra.Command {
 	opts := CommandCordonOption{}
 	cmd := &cobra.Command{
 		Use:                   "uncordon CLUSTER",
-		Short:                 uncordonShort,
+		Short:                 "Mark cluster as schedulable",
 		Long:                  uncordonLong,
 		Example:               fmt.Sprintf(uncordonExample, parentCommand),
 		SilenceUsage:          true,

pkg/karmadactl/deinit/deinit.go

@@ -22,6 +22,9 @@ const (
 )
 
 var (
+	deInitLong = templates.LongDesc(`
+		Remove the Karmada control plane from the Kubernetes cluster.`)
+
 	deInitExample = templates.Examples(`
 		# Remove Karmada from the Kubernetes cluster.
 		%[1]s deinit`)
@@ -46,8 +49,8 @@ func NewCmdDeInit(parentCommand string) *cobra.Command {
 	opts := CommandDeInitOption{}
 	cmd := &cobra.Command{
 		Use:                   "deinit",
-		Short:                 "Removes Karmada from Kubernetes",
-		Long:                  "Removes Karmada from Kubernetes",
+		Short:                 "Remove the Karmada control plane from the Kubernetes cluster.",
+		Long:                  deInitLong,
 		Example:               fmt.Sprintf(deInitExample, parentCommand),
 		SilenceUsage:          true,
 		DisableFlagsInUseLine: true,

pkg/karmadactl/exec/exec.go

@@ -19,6 +19,9 @@ const (
 )
 
 var (
+	execLong = templates.LongDesc(`
+		Execute a command in a container in a cluster.`)
+
 	execExample = templates.Examples(`
 		# Get output from running the 'date' command from pod mypod, using the first container by default in cluster(member1)
 		%[1]s exec mypod -C=member1 -- date
@@ -54,7 +57,7 @@ func NewCmdExec(f util.Factory, parentCommand string, streams genericclioptions.
 	cmd := &cobra.Command{
 		Use:                   "exec (POD | TYPE/NAME) [-c CONTAINER] (-C CLUSTER) -- COMMAND [args...]",
 		Short:                 "Execute a command in a container in a cluster",
-		Long:                  "Execute a command in a container in a cluster",
+		Long:                  execLong,
 		SilenceUsage:          true,
 		DisableFlagsInUseLine: true,
 		Example:               fmt.Sprintf(execExample, parentCommand),

pkg/karmadactl/get/get.go

@@ -53,8 +53,6 @@ var (
 	}
 	eventColumn = metav1.TableColumnDefinition{Name: "EVENT", Type: "string", Format: "", Priority: 0}
 
-	getShort = `Display one or many resources`
-
 	getLong = templates.LongDesc(`
 		Display one or many resources in member clusters.
 
@@ -97,7 +95,7 @@ func NewCmdGet(f util.Factory, parentCommand string, streams genericclioptions.I
 	o := NewCommandGetOptions(streams)
 	cmd := &cobra.Command{
 		Use:                   "get [NAME | -l label | -n namespace]",
-		Short:                 getShort,
+		Short:                 "Display one or many resources",
 		Long:                  getLong,
 		SilenceUsage:          true,
 		DisableFlagsInUseLine: true,

pkg/karmadactl/join/join.go

@@ -21,8 +21,8 @@ import (
 )
 
 var (
-	joinShort = `Register a cluster to control plane`
-	joinLong  = `Join registers a cluster to control plane.`
+	joinLong = templates.LongDesc(`
+		Register a cluster to Karmada control plane with Push mode.`)
 
 	joinExample = templates.Examples(`
 		# Join cluster into karmada control plane, if '--cluster-context' not specified, take the cluster name as the context
@@ -35,7 +35,7 @@ func NewCmdJoin(f cmdutil.Factory, parentCommand string) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:                   "join CLUSTER_NAME --cluster-kubeconfig=<KUBECONFIG>",
-		Short:                 joinShort,
+		Short:                 "Register a cluster to Karmada control plane with Push mode",
 		Long:                  joinLong,
 		Example:               fmt.Sprintf(joinExample, parentCommand),
 		SilenceUsage:          true,

pkg/karmadactl/promote/promote.go

@@ -33,8 +33,14 @@ import (
 )
 
 var (
-	promoteShort   = `Promote resources from legacy clusters to karmada control plane`
-	promoteLong    = `Promote resources from legacy clusters to karmada control plane. Requires the cluster be joined or registered.`
+	promoteLong = templates.LongDesc(`
+	Promote resources from legacy clusters to Karmada control plane. 
+	Requires the cluster has been joined or registered.
+
+	If the resource already exists in Karmada control plane, 
+	please edit PropagationPolicy and OverridePolicy to propagate it.
+	`)
+
 	promoteExample = templates.Examples(`
 		# Promote deployment(default/nginx) from cluster1 to Karmada
 		%[1]s promote deployment nginx -n default -C cluster1
@@ -62,7 +68,7 @@ func NewCmdPromote(f util.Factory, parentCommand string) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:                   "promote <RESOURCE_TYPE> <RESOURCE_NAME> -n <NAME_SPACE> -C <CLUSTER_NAME>",
-		Short:                 promoteShort,
+		Short:                 "Promote resources from legacy clusters to Karmada control plane",
 		Long:                  promoteLong,
 		Example:               fmt.Sprintf(promoteExample, parentCommand),
 		SilenceUsage:          true,

pkg/karmadactl/register/register.go

@@ -46,11 +46,11 @@ import (
 )
 
 var (
-	registerShort = `Register a cluster to Karmada control plane with PULL mode`
-	registerLong  = `Register a cluster to Karmada control plane with PULL mode.`
+	registerLong = templates.LongDesc(`
+		Register a cluster to Karmada control plane with Pull mode.`)
 
 	registerExample = templates.Examples(`
-		# Register cluster into karmada control plane with PULL mode.
+		# Register cluster into karmada control plane with Pull mode.
 		# If '--cluster-name' isn't specified, the cluster of current-context will be used by default.
 		%[1]s register [karmada-apiserver-endpoint] --cluster-name=<CLUSTER_NAME> --token=<TOKEN>  --discovery-token-ca-cert-hash=<CA-CERT-HASH>
 		
@@ -131,7 +131,7 @@ func NewCmdRegister(parentCommand string) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:                   "register [karmada-apiserver-endpoint]",
-		Short:                 registerShort,
+		Short:                 "Register a cluster to Karmada control plane with Pull mode",
 		Long:                  registerLong,
 		Example:               fmt.Sprintf(registerExample, parentCommand),
 		SilenceUsage:          true,

pkg/karmadactl/taint/taint.go

@@ -32,8 +32,16 @@ const (
 )
 
 var (
-	taintShort   = `Update the taints on one or more clusters`
-	taintLong    = `Update the taints on one or more clusters.`
+	taintLong = templates.LongDesc(`
+		Update the taints on one or more clusters.
+
+		*  A taint consists of a key, value, and effect. As an argument here, it is expressed as key=value:effect.
+		*  The key must begin with a letter or number, and may contain letters, numbers, hyphens, dots, and underscores, up to 253 characters.
+		*  Optionally, the key can begin with a DNS subdomain prefix and a single '/', like example.com/my-app.
+		*  The value is optional. If given, it must begin with a letter or number, and may contain letters, numbers, hyphens, dots, and underscores, up to  63 characters.
+		*  The effect must be NoSchedule, PreferNoSchedule or NoExecute.
+		*  Currently taint can only apply to cluster.`)
+
 	taintExample = templates.Examples(`
 		# Update cluster 'foo' with a taint with key 'dedicated' and value 'special-user' and effect 'NoSchedule'
 		# If a taint with that key and effect already exists, its value is replaced as specified
@@ -55,7 +63,7 @@ func NewCmdTaint(f util.Factory, parentCommand string) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:                   "taint CLUSTER NAME KEY_1=VAL_1:TAINT_EFFECT_1 ... KEY_N=VAL_N:TAINT_EFFECT_N",
-		Short:                 taintShort,
+		Short:                 "Update the taints on one or more clusters",
 		Long:                  taintLong,
 		Example:               fmt.Sprintf(taintExample, parentCommand),
 		SilenceUsage:          true,

pkg/karmadactl/unjoin/unjoin.go

@@ -24,8 +24,9 @@ import (
 )
 
 var (
-	unjoinShort   = `Remove the registration of a cluster from control plane`
-	unjoinLong    = `Unjoin removes the registration of a cluster from control plane.`
+	unjoinLong = templates.LongDesc(`
+		Remove a cluster from Karmada control plane.`)
+
 	unjoinExample = templates.Examples(`
 		# Unjoin cluster from karmada control plane, but not to remove resources created by karmada in the unjoining cluster
 		%[1]s unjoin CLUSTER_NAME
@@ -43,7 +44,7 @@ func NewCmdUnjoin(f cmdutil.Factory, parentCommand string) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:                   "unjoin CLUSTER_NAME --cluster-kubeconfig=<KUBECONFIG>",
-		Short:                 unjoinShort,
+		Short:                 "Remove a cluster from Karmada control plane",
 		Long:                  unjoinLong,
 		Example:               fmt.Sprintf(unjoinExample, parentCommand),
 		SilenceUsage:          true,