OCM-10728 | interface improvements (#686)

The commands for cluster creation and management of wif-config resources
were reviewed and made consistent in order to provide the user with a
uniform experience.

cmd/ocm/create/cluster/cmd.go

@@ -110,7 +110,7 @@ var args struct {
 }
 
 const clusterNameHelp = "The name can be used as the identifier of the cluster." +
-	" The maximum length is 54 characters. Once set, the cluster name cannot be changed"
+	" The maximum length is 54 characters. Once set, the cluster name cannot be changed."
 
 const subnetTemplate = "%s (%s)"
 
@@ -203,7 +203,7 @@ func init() {
 			"will be used when generating a sub-domain for your cluster. It must be unique and consist "+
 			"of lowercase alphanumeric,characters or '-', start with an alphabetic character, and end with "+
 			"an alphanumeric character. The maximum length is 15 characters. Once set, the cluster domain "+
-			"prefix cannot be changed",
+			"prefix cannot be changed.",
 	)
 	arguments.SetQuestion(fs, "domain-prefix", "Domain Prefix:")
 
@@ -345,23 +345,23 @@ func init() {
 		&args.defaultIngressWildcardPolicy,
 		defaultIngressWildcardPolicyFlag,
 		"",
-		fmt.Sprintf("Wildcard Policy for ingress. Options are %s", strings.Join(ingress.ValidWildcardPolicies, ",")),
+		fmt.Sprintf("Wildcard Policy for ingress. Options are { %s }.", strings.Join(ingress.ValidWildcardPolicies, ", ")),
 	)
 
 	fs.StringVar(
 		&args.defaultIngressNamespaceOwnershipPolicy,
 		defaultIngressNamespaceOwnershipPolicyFlag,
 		"",
-		fmt.Sprintf("Namespace Ownership Policy for ingress. Options are %s",
-			strings.Join(ingress.ValidNamespaceOwnershipPolicies, ",")),
+		fmt.Sprintf("Namespace Ownership Policy for ingress. Options are { %s }.",
+			strings.Join(ingress.ValidNamespaceOwnershipPolicies, ", ")),
 	)
 
 	fs.StringVar(
 		&args.subscriptionType,
 		"subscription-type",
 		billing.StandardSubscriptionType,
-		fmt.Sprintf("The subscription billing model for the cluster. Options are %s",
-			strings.Join(billing.ValidSubscriptionTypes, ",")),
+		fmt.Sprintf("The subscription billing model for the cluster. Options are { %s }.",
+			strings.Join(billing.ValidSubscriptionTypes, ", ")),
 	)
 	arguments.SetQuestion(fs, "subscription-type", "Subscription type:")
 	Cmd.RegisterFlagCompletionFunc("subscription-type", arguments.MakeCompleteFunc(getSubscriptionTypeOptions))
@@ -395,9 +395,9 @@ func init() {
 		&args.gcpWifConfig,
 		"wif-config",
 		"",
-		"Specifies the GCP Workload Identity Federation config used to authenticate.",
+		"Specifies the GCP Workload Identity Federation config used for cloud authentication.",
 	)
-	arguments.SetQuestion(fs, "wif-config", "WIF Configuration:")
+	arguments.SetQuestion(fs, "wif-config", "WIF configuration:")
 	Cmd.RegisterFlagCompletionFunc("wif-config", arguments.MakeCompleteFunc(getWifConfigNameOptions))
 }
 
@@ -904,7 +904,7 @@ func promptName(argv []string) error {
 
 	if args.interactive {
 		prompt := &survey.Input{
-			Message: "cluster name",
+			Message: "Cluster name:",
 			Help:    clusterNameHelp,
 		}
 		return survey.AskOne(prompt, &args.clusterName, survey.WithValidator(survey.Required))

cmd/ocm/gcp/create-wif-config.go

@@ -35,8 +35,15 @@ const (
 // NewCreateWorkloadIdentityConfiguration provides the "gcp create wif-config" subcommand
 func NewCreateWorkloadIdentityConfiguration() *cobra.Command {
 	createWifConfigCmd := &cobra.Command{
-		Use:     "wif-config",
-		Short:   "Create workload identity configuration",
+		Use:   "wif-config",
+		Short: "Create a workload identity federation configuration (wif-config) object.",
+		Long: `Create a workload identity federation configuration (wif-config) object.
+
+wif-config objects represent a set of GCP resources that are needed in a
+deployment of WIF OSD-GCP clusters. These resources include service accounts,
+custom roles, role bindings, identity and federated pools. Running this command
+in auto-mode will generate these resources on the user's cloud, and create a
+wif-config resource within OCM to represent those resources.`,
 		PreRunE: validationForCreateWorkloadIdentityConfigurationCmd,
 		RunE:    createWorkloadIdentityConfigurationCmd,
 	}
@@ -58,12 +65,14 @@ func NewCreateWorkloadIdentityConfiguration() *cobra.Command {
 		"mode",
 		"m",
 		ModeAuto,
-		"How to perform the operation. Valid options are:\n"+
-			"auto (default): Resource changes will be automatic applied using the current GCP account\n"+
-			"manual: Commands necessary to modify GCP resources will be output to be run manually",
+		modeFlagDescription,
+	)
+	createWifConfigCmd.PersistentFlags().StringVar(
+		&CreateWifConfigOpts.TargetDir,
+		"output-dir",
+		"",
+		targetDirFlagDescription,
 	)
-	createWifConfigCmd.PersistentFlags().StringVar(&CreateWifConfigOpts.TargetDir, "output-dir", "",
-		"Directory to place generated files (defaults to current directory)")
 
 	return createWifConfigCmd
 }
@@ -89,11 +98,11 @@ func validationForCreateWorkloadIdentityConfigurationCmd(cmd *cobra.Command, arg
 }
 
 func promptWifDisplayName() error {
-	const wifNameHelp = "The name can be used as the identifier of the WifConfig resource."
+	const wifNameHelp = "The display name of the wif-config resource."
 	if CreateWifConfigOpts.Name == "" {
 		if CreateWifConfigOpts.Interactive {
 			prompt := &survey.Input{
-				Message: "WifConfig name",
+				Message: "wif-config name:",
 				Help:    wifNameHelp,
 			}
 			return survey.AskOne(
@@ -108,11 +117,11 @@ func promptWifDisplayName() error {
 }
 
 func promptProjectId() error {
-	const projectIdHelp = "The GCP Project Id that will be used by the WifConfig"
+	const projectIdHelp = "The GCP Project Id that will be used by the wif-config."
 	if CreateWifConfigOpts.Project == "" {
 		if CreateWifConfigOpts.Interactive {
 			prompt := &survey.Input{
-				Message: "Gcp Project ID",
+				Message: "Gcp Project ID:",
 				Help:    projectIdHelp,
 			}
 			return survey.AskOne(
@@ -135,15 +144,15 @@ func createWorkloadIdentityConfigurationCmd(cmd *cobra.Command, argv []string) e
 		return errors.Wrapf(err, "failed to initiate GCP client")
 	}
 
-	log.Println("Creating workload identity configuration...")
+	log.Println("Creating workload identity federation configuration...")
 	wifConfig, err := createWorkloadIdentityConfiguration(
 		ctx,
 		gcpClient,
 		CreateWifConfigOpts.Name,
 		CreateWifConfigOpts.Project,
 	)
 	if err != nil {
-		return errors.Wrapf(err, "failed to create WIF config")
+		return errors.Wrapf(err, "failed to create wif-config")
 	}
 
 	if CreateWifConfigOpts.Mode == ModeManual {
@@ -217,7 +226,7 @@ func createWorkloadIdentityConfiguration(
 	wifBuilder.DisplayName(displayName)
 	wifConfigInput, err := wifBuilder.Build()
 	if err != nil {
-		return nil, errors.Wrap(err, "failed to build WIF config")
+		return nil, errors.Wrap(err, "failed to build wif-config")
 	}
 
 	response, err := connection.ClustersMgmt().V1().GCP().
@@ -226,7 +235,7 @@ func createWorkloadIdentityConfiguration(
 		Body(wifConfigInput).
 		Send()
 	if err != nil {
-		return nil, errors.Wrap(err, "failed to create WIF config")
+		return nil, errors.Wrap(err, "failed to create wif-config")
 	}
 
 	return response.Body(), nil

cmd/ocm/gcp/delete-wif-config.go

@@ -27,8 +27,22 @@ var (
 // NewDeleteWorkloadIdentityConfiguration provides the "gcp delete wif-config" subcommand
 func NewDeleteWorkloadIdentityConfiguration() *cobra.Command {
 	deleteWifConfigCmd := &cobra.Command{
-		Use:     "wif-config [ID|Name]",
-		Short:   "Delete workload identity configuration",
+		Use:   "wif-config [ID|Name]",
+		Short: "Delete workload identity federation configuration (wif-config)",
+		Long: `Delete workload identity federation configuration (wif-config)
+
+wif-config resources may only be deleted if they are not in use by an OSD-GCP
+cluster. Deleting a wif-config that is presently utilized is prevented and
+results in an error returned. Clusters that are utilizing a specific wif-config
+may be listed using the following command: 
+
+ocm list cluster --parameter search="gcp.authentication.wif_config_id = '<WIF_ID>'"
+
+Where <WIF_ID> is the id of the wif-config resource.
+
+Deleting the wif-config resource will remove the OCM metadata, as well as the
+GCP resources represented by the wif-config.
+        `,
 		RunE:    deleteWorkloadIdentityConfigurationCmd,
 		PreRunE: validationForDeleteWorkloadIdentityConfigurationCmd,
 	}
@@ -38,12 +52,14 @@ func NewDeleteWorkloadIdentityConfiguration() *cobra.Command {
 		"mode",
 		"m",
 		ModeAuto,
-		"How to perform the operation. Valid options are:\n"+
-			"auto (default): Resource changes will be automatic applied using the current GCP account\n"+
-			"manual: Commands necessary to modify GCP resources will be output to be run manually",
+		modeFlagDescription,
+	)
+	deleteWifConfigCmd.PersistentFlags().StringVar(
+		&DeleteWifConfigOpts.TargetDir,
+		"output-dir",
+		"",
+		targetDirFlagDescription,
 	)
-	deleteWifConfigCmd.PersistentFlags().StringVar(&DeleteWifConfigOpts.TargetDir, "output-dir", "",
-		"Directory to place generated files (defaults to current directory)")
 
 	return deleteWifConfigCmd
 }

cmd/ocm/gcp/flag_descriptions.go

@@ -0,0 +1,12 @@
+package gcp
+
+const (
+	modeFlagDescription = `How to perform the operation. Valid options are:
+auto (default): Resource changes will be automatically applied using the
+                current GCP account.
+manual:         Commands necessary to modify GCP resources will be output
+                as a script to be run manually.
+`
+
+	targetDirFlagDescription = `Directory to place generated files (defaults to current directory)`
+)

cmd/ocm/gcp/gcp.go

@@ -20,8 +20,8 @@ type options struct {
 func NewGcpCmd() *cobra.Command {
 	gcpCmd := &cobra.Command{
 		Use:   "gcp COMMAND",
-		Short: "Perform actions related to GCP WIF",
-		Long:  "Manage GCP Workload Identity Federation (WIF) resources.",
+		Short: "Manage GCP resources.",
+		Long:  "Perform operations related to GCP resources.",
 		Args:  cobra.MinimumNArgs(1),
 	}
 
@@ -39,9 +39,13 @@ func NewGcpCmd() *cobra.Command {
 func NewCreateCmd() *cobra.Command {
 	createCmd := &cobra.Command{
 		Use:   "create COMMAND",
-		Short: "Create resources",
-		Long:  "Create resources.",
-		Args:  cobra.MinimumNArgs(1),
+		Short: "Create resources related to GCP.",
+		Long: `Create resources related to GCP.
+
+Deployments, such as OSD-GCP WIF clusters, require resources to be created on
+the user's cloud prior to cluster creation. This command set provides the
+methods needed to create these resources on behalf of the user.`,
+		Args: cobra.MinimumNArgs(1),
 	}
 
 	createCmd.AddCommand(NewCreateWorkloadIdentityConfiguration())
@@ -53,9 +57,13 @@ func NewCreateCmd() *cobra.Command {
 func NewUpdateCmd() *cobra.Command {
 	updateCmd := &cobra.Command{
 		Use:   "update COMMAND",
-		Short: "Update resources",
-		Long:  "Update resources.",
-		Args:  cobra.MinimumNArgs(1),
+		Short: "Update resources related to GCP.",
+		Long: `Update resources related to GCP.
+
+Deployments, such as OSD-GCP WIF clusters, utilize resources that may require
+updation between version upgrades. This command set providers the methods
+needed to update GCP resources on behalf of the user.`,
+		Args: cobra.MinimumNArgs(1),
 	}
 	updateCmd.AddCommand(NewUpdateWorkloadIdentityConfiguration())
 	return updateCmd
@@ -65,8 +73,8 @@ func NewUpdateCmd() *cobra.Command {
 func NewDeleteCmd() *cobra.Command {
 	deleteCmd := &cobra.Command{
 		Use:   "delete COMMAND",
-		Short: "Delete resources",
-		Long:  "Delete resources.",
+		Short: "Delete resources related to GCP.",
+		Long:  "Delete resources related to GCP.",
 		Args:  cobra.MinimumNArgs(1),
 	}
 	deleteCmd.AddCommand(NewDeleteWorkloadIdentityConfiguration())
@@ -77,8 +85,8 @@ func NewDeleteCmd() *cobra.Command {
 func NewGetCmd() *cobra.Command {
 	getCmd := &cobra.Command{
 		Use:   "get COMMAND",
-		Short: "Get resources",
-		Long:  "Get resources.",
+		Short: "Get resources related to GCP.",
+		Long:  "Get resources related to GCP.",
 		Args:  cobra.MinimumNArgs(1),
 	}
 	getCmd.AddCommand(NewGetWorkloadIdentityConfiguration())
@@ -89,8 +97,8 @@ func NewGetCmd() *cobra.Command {
 func NewListCmd() *cobra.Command {
 	listCmd := &cobra.Command{
 		Use:   "list COMMAND",
-		Short: "List resources",
-		Long:  "List resources.",
+		Short: "List resources related to GCP.",
+		Long:  "List resources related to GCP.",
 		Args:  cobra.MinimumNArgs(1),
 	}
 	listCmd.AddCommand(NewListWorkloadIdentityConfiguration())
@@ -101,8 +109,8 @@ func NewListCmd() *cobra.Command {
 func NewDescribeCmd() *cobra.Command {
 	describeCmd := &cobra.Command{
 		Use:   "describe COMMAND",
-		Short: "Describe resources",
-		Long:  "Describe resources.",
+		Short: "Describe resources related to GCP.",
+		Long:  "Describe resources related to GCP.",
 		Args:  cobra.MinimumNArgs(1),
 	}
 	describeCmd.AddCommand(NewDescribeWorkloadIdentityConfiguration())

cmd/ocm/gcp/get-wif-config.go

@@ -18,8 +18,16 @@ var GetWorkloadIdentityConfigurationOpts struct {
 
 func NewGetWorkloadIdentityConfiguration() *cobra.Command {
 	getWorkloadIdentityPoolCmd := &cobra.Command{
-		Use:     "wif-config [ID]",
-		Short:   "Send a GET request for wif-config.",
+		Use:   "wif-config [ID]",
+		Short: "Retrieve workload identity federation configuration (wif-config) resource data.",
+		Long: `Retrieve workload identity federation configuration (wif-config) resource data.
+
+The wif-config object returned by this command is in the json format returned
+by the OCM backend. It displays all of the data that is associated with the
+specified wif-config object.
+
+Calling this command without an ID specified results in a dump of all
+wif-config objects that belongs to the user's organization.`,
 		RunE:    getWorkloadIdentityConfigurationCmd,
 		PreRunE: validationForGetWorkloadIdentityConfigurationCmd,
 		Aliases: []string{"wif-configs"},

cmd/ocm/gcp/list-wif-config.go

@@ -22,16 +22,22 @@ func NewListWorkloadIdentityConfiguration() *cobra.Command {
 	listWorkloadIdentityPoolCmd := &cobra.Command{
 		Use:     "wif-config",
 		Aliases: []string{"wif-configs"},
-		Short:   "List wif-configs.",
-		RunE:    listWorkloadIdentityConfigurationCmd,
+		Short:   "List workload identity federation configurations (wif-configs)",
+		Long: `List workload identity federation configurations (wif-configs).
+
+The caller of the command will only view data from wif-config objects that
+belong to the user's organization.`,
+		RunE: listWorkloadIdentityConfigurationCmd,
 	}
 
 	fs := listWorkloadIdentityPoolCmd.Flags()
 	fs.StringVar(
 		&ListWorkloadIdentityConfigurationOpts.columns,
 		"columns",
 		"id, display_name, gcp.project_id",
-		"Specify which columns to display separated by commas, path is based on wif-config struct",
+		`Specify which columns to display separated by commas. 
+The path is based on wif-config struct.
+`,
 	)
 	fs.BoolVar(
 		&ListWorkloadIdentityConfigurationOpts.noHeaders,

cmd/ocm/gcp/update-wif-config.go

@@ -22,8 +22,13 @@ var (
 // NewUpdateWorkloadIdentityConfiguration provides the "gcp update wif-config" subcommand
 func NewUpdateWorkloadIdentityConfiguration() *cobra.Command {
 	updateWifConfigCmd := &cobra.Command{
-		Use:     "wif-config [ID|Name]",
-		Short:   "Update wif-config.",
+		Use:   "wif-config [ID|Name]",
+		Short: "Update workload identity federation configuration (wif-config).",
+		Long: `Update workload identity federation configuration (wif-config).
+
+wif-config that are in use by cluster deployments may require updation before
+the cluster version upgrade may continue. This command may be used to update
+the wif-config metadata and the GCP resources it represents.`,
 		RunE:    updateWorkloadIdentityConfigurationCmd,
 		PreRunE: validationForUpdateWorkloadIdentityConfigurationCmd,
 	}
@@ -33,12 +38,14 @@ func NewUpdateWorkloadIdentityConfiguration() *cobra.Command {
 		"mode",
 		"m",
 		ModeAuto,
-		"How to perform the operation. Valid options are:\n"+
-			"auto (default): Resource changes will be automatic applied using the current GCP account\n"+
-			"manual: Commands necessary to modify GCP resources will be output to be run manually",
+		modeFlagDescription,
+	)
+	updateWifConfigCmd.PersistentFlags().StringVar(
+		&UpdateWifConfigOpts.TargetDir,
+		"output-dir",
+		"",
+		targetDirFlagDescription,
 	)
-	updateWifConfigCmd.PersistentFlags().StringVar(&UpdateWifConfigOpts.TargetDir, "output-dir", "",
-		"Directory to place generated files (defaults to current directory)")
 
 	return updateWifConfigCmd
 }