Tweak CLI language

Misc changes to CLI help/messages to clarify behavior or make
it more consistent with current descriptions of what Sonobuoy
does and how.

Fixes #1172

Signed-off-by: John Schnake <[email protected]>

cmd/sonobuoy/app/args.go

@@ -100,7 +100,7 @@ func AddDNSPodLabelsFlag(str *[]string, flags *pflag.FlagSet) {
 func AddSonobuoyImage(image *string, flags *pflag.FlagSet) {
 	flags.StringVar(
 		image, sonobuoyImageFlag, config.DefaultImage,
-		"Container image override for the sonobuoy worker and container.",
+		"Container image override for the sonobuoy worker and aggregator.",
 	)
 }
 
@@ -110,7 +110,7 @@ func AddPluginImage(pluginTransforms *map[string][]func(*manifest.Manifest) erro
 			transforms: *pluginTransforms,
 		},
 		pluginImageFlag,
-		"Override a plugins image from what is in its definition (expects format plugin:image)",
+		"Override a plugins image from what is in its definition (e.g. myPlugin:testimage)",
 	)
 }
 
@@ -124,7 +124,7 @@ func AddKubeConformanceImage(pluginTransforms *map[string][]func(*manifest.Manif
 			},
 		},
 		"kube-conformance-image",
-		"Container image override for the kube conformance image.",
+		"Container image override for the e2e plugin. Shorthand for --plugin-image=e2e:<string>",
 	)
 }
 
@@ -138,13 +138,13 @@ func AddSystemdLogsImage(pluginTransforms *map[string][]func(*manifest.Manifest)
 			},
 		},
 		"systemd-logs-image",
-		"Container image override for the systemd-logs plugin image.",
+		"Container image override for the systemd-logs plugin. Shorthand for --plugin-image=systemd-logs:<string>",
 	)
 }
 
 // AddKubeConformanceImageVersion initialises an image version flag.
 func AddKubeConformanceImageVersion(imageVersion *image.ConformanceImageVersion, pluginTransforms *map[string][]func(*manifest.Manifest) error, flags *pflag.FlagSet) {
-	help := "Use default Conformance image, but override the version. "
+	help := "Use default e2e plugin image, but override the version. "
 	help += "Default is 'auto', which will be set to your cluster's version if detected, erroring otherwise."
 	help += "You can also choose 'latest' which will find the latest dev image upstream."
 
@@ -187,7 +187,7 @@ func AddCustomRegistryFlag(cfg *string, flags *pflag.FlagSet) {
 func AddSonobuoyConfigFlag(cfg *SonobuoyConfig, flags *pflag.FlagSet) {
 	flags.Var(
 		cfg, "config",
-		"Path to a sonobuoy configuration JSON file. Overrides --mode.",
+		"Path to a sonobuoy configuration JSON file.",
 	)
 }
 
@@ -212,23 +212,23 @@ func AddLegacyE2EFlags(env *PluginEnvVars, pluginTransforms *map[string][]func(*
 			PluginEnvVars:  *env,
 			validationFunc: regexpValidation},
 		e2eFocusFlag,
-		"Specify the E2E_FOCUS flag to the conformance tests.",
+		"Specify the E2E_FOCUS value for the e2e plugin, specifying which tests to run. Shorthand for --plugin-env=e2e.E2E_FOCUS=<string>",
 	)
 	fs.Var(
 		&envVarModierFlag{
 			plugin: e2ePlugin, field: "E2E_SKIP",
 			PluginEnvVars:  *env,
 			validationFunc: regexpValidation},
 		e2eSkipFlag,
-		"Specify the E2E_SKIP flag to the conformance tests.",
+		"Specify the E2E_SKIP value for the e2e plugin, specifying which tests to skip. Shorthand for --plugin-env=e2e.E2E_SKIP=<string>",
 	)
 	pf := fs.VarPF(
 		&envVarModierFlag{
 			plugin:        e2ePlugin,
 			field:         "E2E_PARALLEL",
 			PluginEnvVars: *env,
 		}, e2eParallelFlag, "",
-		"Specify the E2E_PARALLEL flag to the conformance tests.",
+		"Specify the E2E_PARALLEL value for the e2e plugin. Shorthand for --plugin-env=e2e.E2E_PARALLEL=<string>",
 	)
 	if err := pf.Value.Set("false"); err != nil {
 		panic("Failed to initial parallel flag")
@@ -238,7 +238,7 @@ func AddLegacyE2EFlags(env *PluginEnvVars, pluginTransforms *map[string][]func(*
 	// Used by the container when enabling E2E tests which require SSH.
 	fs.Var(
 		&envVarModierFlag{plugin: e2ePlugin, field: "KUBE_SSH_USER", PluginEnvVars: *env}, "ssh-user",
-		"SSH user for ssh-key.",
+		"SSH user for ssh-key. Required if running e2e plugin with certain tests that require SSH access to nodes.",
 	)
 
 	fs.Var(
@@ -256,15 +256,15 @@ func AddRBACModeFlags(mode *RBACMode, flags *pflag.FlagSet, defaultMode RBACMode
 	flags.Var(
 		mode, "rbac",
 		// Doesn't use the map in app.rbacModeMap to preserve order so we can add an explanation for detect.
-		"Whether to enable rbac on Sonobuoy. Valid modes are Enable, Disable, and Detect (query the server to see whether to enable RBAC).",
+		"Whether to enable RBAC on Sonobuoy. Valid modes are Enable, Disable, and Detect (query the server to see whether to enable RBAC).",
 	)
 }
 
 // AddSkipPreflightFlag adds a boolean flag to skip preflight checks.
 func AddSkipPreflightFlag(flag *bool, flags *pflag.FlagSet) {
 	flags.BoolVar(
 		flag, "skip-preflight", false,
-		"If true, skip all checks before kicking off the sonobuoy run.",
+		"If true, skip all checks before starting the sonobuoy run.",
 	)
 }
 
@@ -280,7 +280,7 @@ func AddDeleteAllFlag(flag *bool, flags *pflag.FlagSet) {
 func AddDeleteWaitFlag(flag *int, flags *pflag.FlagSet) {
 	flags.IntVar(
 		flag, "wait", 0,
-		"Wait for resources to be deleted before completing. 0 indicates do not wait. By providing --wait the default is to wait for 1 hour.",
+		"Wait for resources to be deleted before completing. 0 indicates do not wait. By providing --wait the default is to wait up to 1 hour.",
 	)
 	flags.Lookup("wait").NoOptDefVal = "60"
 }
@@ -289,7 +289,7 @@ func AddDeleteWaitFlag(flag *int, flags *pflag.FlagSet) {
 func AddRunWaitFlag(flag *int, flags *pflag.FlagSet) {
 	flags.IntVar(
 		flag, "wait", 0,
-		"How long (in minutes) to wait for sonobuoy run to be completed or fail, where 0 indicates do not wait. If specified, the default wait time is 1 day.",
+		"How long (in minutes) for the CLI to wait for sonobuoy run to be completed or fail, where 0 indicates do not wait. If specified, the default wait time is 1 day.",
 	)
 	flags.Lookup("wait").NoOptDefVal = "1440"
 }
@@ -298,7 +298,7 @@ func AddRunWaitFlag(flag *int, flags *pflag.FlagSet) {
 func AddTimeoutFlag(flag *int, flags *pflag.FlagSet) {
 	flags.IntVar(
 		flag, timeoutFlag, config.DefaultAggregationServerTimeoutSeconds,
-		"How long (in seconds) Sonobuoy will wait for plugins to complete before exiting. 0 indicates no timeout.",
+		"How long (in seconds) Sonobuoy aggregator will wait for plugins to complete before exiting. 0 indicates no timeout.",
 	)
 }
 
@@ -307,7 +307,7 @@ func AddTimeoutFlag(flag *int, flags *pflag.FlagSet) {
 func AddShowDefaultPodSpecFlag(flag *bool, flags *pflag.FlagSet) {
 	flags.BoolVar(
 		flag, "show-default-podspec", false,
-		"If true, include the default pod spec used for plugins in the output",
+		"If true, include the default pod spec used for plugins in the output.",
 	)
 }
 
@@ -323,7 +323,7 @@ func AddWaitOutputFlag(mode *WaitOutputMode, flags *pflag.FlagSet, defaultMode W
 func AddImagePullPolicyFlag(policy *string, flags *pflag.FlagSet) {
 	flags.StringVar(
 		policy, imagePullPolicyFlag, config.DefaultSonobuoyPullPolicy,
-		fmt.Sprintf("The ImagePullPolicy Sonobuoy should use for the aggregators and workers. Valid options are %s.", strings.Join(ValidPullPolicies(), ", ")),
+		fmt.Sprintf("Set the ImagePullPolicy for the Sonobuoy image and all plugins. Valid options are %s.", strings.Join(ValidPullPolicies(), ", ")),
 	)
 }
 
@@ -336,7 +336,7 @@ func AddSSHKeyPathFlag(path *string, pluginTransforms *map[string][]func(*manife
 			filename:   path,
 			transforms: *pluginTransforms,
 		}, "ssh-key",
-		"Path to the private key enabling SSH to cluster nodes.",
+		"Path to the private key enabling SSH to cluster nodes. May be required by some tests from the e2e plugin.",
 	)
 }
 
@@ -359,7 +359,7 @@ func AddPluginListFlag(p *[]string, flags *pflag.FlagSet) {
 
 // AddKubernetesVersionFlag initialises an image version flag.
 func AddKubernetesVersionFlag(imageVersion *image.ConformanceImageVersion, pluginTransforms *map[string][]func(*manifest.Manifest) error, flags *pflag.FlagSet) {
-	help := "Use default Conformance image, but override the version. "
+	help := "Use default E2E image, but override the version. "
 	help += "Default is 'auto', which will be set to your cluster's version if detected, erroring otherwise. "
 	help += "'ignore' will try version resolution but ignore errors. "
 	help += "'latest' will find the latest dev image/version upstream."
@@ -378,7 +378,7 @@ func AddKubernetesVersionFlag(imageVersion *image.ConformanceImageVersion, plugi
 func AddShortFlag(flag *bool, flags *pflag.FlagSet) {
 	flags.BoolVar(
 		flag, "short", false,
-		"If true, prints just the sonobuoy version",
+		"If true, prints just the Sonobuoy version.",
 	)
 }
 
@@ -400,7 +400,7 @@ func AddNodeSelectorsFlag(p *NodeSelectors, flags *pflag.FlagSet) {
 func AddExtractFlag(flag *bool, flags *pflag.FlagSet) {
 	flags.BoolVarP(
 		flag, "extract", "x", false,
-		"If true, extracts the results instead of just downloading the results",
+		"If true, extracts the results instead of just downloading the results tarball.",
 	)
 }
 

cmd/sonobuoy/app/gen_config.go

@@ -17,7 +17,7 @@ func NewCmdGenConfig() *cobra.Command {
 
 	var GenCommand = &cobra.Command{
 		Use:   "config",
-		Short: "Generates a sonobuoy config for input to sonobuoy gen or run.",
+		Short: "Generates a Sonobuoy config for input to sonobuoy gen or run.",
 		Run:   genConfigCobra(&f),
 		Args:  cobra.ExactArgs(0),
 	}

cmd/sonobuoy/app/gen_plugin_def.go

@@ -75,10 +75,11 @@ func NewCmdGenPluginDef() *cobra.Command {
 	}
 
 	cmd := &cobra.Command{
-		Use:   "plugin",
-		Short: "Generates the manifest Sonobuoy uses to define a plugin",
-		Run:   genPluginDefWrapper(&genPluginOpts),
-		Args:  cobra.NoArgs,
+		Use:     "plugin",
+		Short:   "Generates the manifest Sonobuoy uses to define a plugin",
+		Run:     genPluginDefWrapper(&genPluginOpts),
+		Args:    cobra.NoArgs,
+		Example: "sonobuoy gen plugin -n myPlugin -i myregistry/myimage:v0",
 	}
 
 	genPluginSet := pflag.NewFlagSet("generate plugin", pflag.ExitOnError)

cmd/sonobuoy/app/images.go

@@ -57,7 +57,7 @@ func NewCmdImages() *cobra.Command {
 	// Main command
 	cmd := &cobra.Command{
 		Use:   "images",
-		Short: "Manage images used in a plugin. Supported plugins are: 'e2e'",
+		Short: "Manage images used in a plugin to facilitate running them in airgapped (or similar) environments. Supported plugins are: 'e2e'",
 		Run: func(cmd *cobra.Command, args []string) {
 			var client image.Client
 			if flags.dryRun {
@@ -415,15 +415,15 @@ func collectPluginsImages(plugins []string, k8sVersion string, client image.Clie
 		case e2ePlugin:
 			conformanceImage := fmt.Sprintf("%v:%v", config.UpstreamKubeConformanceImageURL, k8sVersion)
 			images = append(images, conformanceImage)
-			logrus.Info("conformance image to be used: ", conformanceImage)
+			logrus.Info("e2e image to be used: ", conformanceImage)
 
 			// pull before running to ensure stderr is empty, because...
 			client.PullImages([]string{conformanceImage}, numDockerRetries)
 
 			// we only need stdout, but this combines stdout and stderr
 			e2eImages, err := client.RunImage(conformanceImage, "e2e.test", "--list-images")
 			if err != nil {
-				return images, errors.Wrap(err, "failed to gather e2e images from conformance image")
+				return images, errors.Wrap(err, "failed to gather test images from e2e image")
 			}
 
 			// in case there are empty newlines getting parsed as a slice element

cmd/sonobuoy/app/logs.go

@@ -43,18 +43,18 @@ func NewCmdLogs() *cobra.Command {
 	var f logFlags
 	cmd := &cobra.Command{
 		Use:   "logs",
-		Short: "Dumps the logs of the currently running sonobuoy containers for diagnostics",
+		Short: "Dumps the logs of the currently running Sonobuoy containers for diagnostics",
 		Run:   getLogs(&f),
 		Args:  cobra.ExactArgs(0),
 	}
 
 	cmd.Flags().BoolVarP(
 		&f.follow, "follow", "f", false,
-		"Specify if the logs should be streamed.",
+		"Continue following the logs of the Sonobuoy created containers.",
 	)
 	AddKubeconfigFlag(&f.kubeconfig, cmd.Flags())
 	AddNamespaceFlag(&f.namespace, cmd.Flags())
-	cmd.Flags().StringVarP(&f.plugin, pluginFlag, "p", "", "Show logs for a specific plugin")
+	cmd.Flags().StringVarP(&f.plugin, pluginFlag, "p", "", "Show logs only for a specific plugin")
 	return cmd
 }
 

cmd/sonobuoy/app/root.go

@@ -30,8 +30,8 @@ import (
 func NewSonobuoyCommand() *cobra.Command {
 	cmds := &cobra.Command{
 		Use:               "sonobuoy",
-		Short:             "Generate reports on your kubernetes cluster",
-		Long:              "Sonobuoy is an introspective kubernetes component that generates reports on cluster conformance, configuration, and more",
+		Short:             "Generate reports on your Kubernetes cluster by running plugins",
+		Long:              "Sonobuoy is a Kubernetes component that generates reports on cluster conformance, configuration, and more",
 		PersistentPreRunE: prerunChecks,
 		Run:               rootCmd,
 	}

cmd/sonobuoy/app/run.go

@@ -92,7 +92,7 @@ func NewCmdRun() *cobra.Command {
 	fs := RunFlagSet(&f)
 	cmd := &cobra.Command{
 		Use:   "run",
-		Short: "Submits a sonobuoy run",
+		Short: "Starts a Sonobuoy run by launching the Sonobuoy aggregator and plugin pods.",
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			return checkFlagValidity(fs, f)
 		},

pkg/client/gen_test.go

@@ -339,7 +339,7 @@ func TestGenerateManifestGolden(t *testing.T) {
 			},
 			goldenFile: filepath.Join("testdata", "use-existing-pod-spec.golden"),
 		}, {
-			name: "Conformance images >= v1.17 support progress",
+			name: "E2E images >= v1.17 support progress",
 			inputcm: &client.GenConfig{
 				DynamicPlugins: []string{"e2e"},
 				KubeVersion:    "v99+static.testing",
@@ -356,7 +356,7 @@ func TestGenerateManifestGolden(t *testing.T) {
 			},
 			goldenFile: filepath.Join("testdata", "e2e-progress-custom-port.golden"),
 		}, {
-			name: "Conformance images >= v1.17 will not override E2E_EXTRA_ARGS if specified by user",
+			name: "E2E images >= v1.17 will not override E2E_EXTRA_ARGS if specified by user",
 			inputcm: &client.GenConfig{
 				DynamicPlugins: []string{"e2e"},
 				PluginEnvOverrides: map[string]map[string]string{

pkg/config/config.go

@@ -30,13 +30,9 @@ const (
 	// DefaultNamespace is the namespace where the aggregator and plugin workers will run (but not necessarily the pods created by the plugin workers).
 	DefaultNamespace = "sonobuoy"
 
-	// DefaultKubeConformanceImageURL is the URL of the docker image to run for the kube conformance tests.
-	DefaultKubeConformanceImageURL = "gcr.io/heptio-images/kube-conformance"
 	// UpstreamKubeConformanceImageURL is the URL of the docker image to run for
 	// the kube conformance tests which is maintained by upstream Kubernetes.
 	UpstreamKubeConformanceImageURL = "k8s.gcr.io/conformance"
-	// DefaultKubeConformanceImageTag is the default tag of the conformance image
-	DefaultKubeConformanceImageTag = "latest"
 	// DefaultAggregationServerBindPort is the default port for the aggregation server to bind to.
 	DefaultAggregationServerBindPort = 8080
 	// DefaultAggregationServerBindAddress is the default address for the aggregation server to bind to.
@@ -66,8 +62,6 @@ const (
 )
 
 var (
-	// DefaultKubeConformanceImage is the URL and tag of the docker image to run for the kube conformance tests.
-	DefaultKubeConformanceImage = DefaultKubeConformanceImageURL + ":" + "$SONOBUOY_K8S_VERSION"
 	// DefaultImage is the URL of the docker image to run for the aggregator and workers
 	DefaultImage = "sonobuoy/sonobuoy:" + buildinfo.Version
 	// DefaultResources is the default set of resources which are queried for after plugins run. The strings