DOCS-23222: Clarify use of --inclusive in `confluent iam rbac role-…

…binding list` (#2410)

Co-authored-by: Brian Strauch <[email protected]>

internal/iam/acl_utils.go

@@ -36,7 +36,7 @@ access to the provided operations on the Kafka cluster itself.`)
 	flgSet.String("transactional-id", "", "Set the TransactionalID resource.")
 	flgSet.String("topic", "", `Set the topic resource. With this option the ACL grants the provided
 operations on the topics that start with that prefix, depending on whether
-the --prefix option was also passed.`)
+the "--prefix" option was also passed.`)
 	flgSet.Bool("prefix", false, "Set to match all resource names prefixed with this value.")
 	flgSet.SortFlags = false
 	return flgSet

internal/iam/command_rbac_role_binding_create.go

@@ -64,17 +64,17 @@ func (c *roleBindingCommand) newCreateCommand() *cobra.Command {
 		exs = append(exs,
 			examples.Example{
 				Text: `Create a role binding for the principal permitting it produce to topic "my-topic":`,
-				Code: "confluent iam rbac role-binding create --principal User:appSA --role DeveloperWrite --resource Topic:my-topic --kafka-cluster $KAFKA_CLUSTER_ID",
+				Code: "confluent iam rbac role-binding create --principal User:appSA --role DeveloperWrite --resource Topic:my-topic --kafka-cluster 0000000000000000000000",
 			},
 		)
 	}
 
 	cmd.Example = examples.BuildExampleString(exs...)
 
 	cmd.Flags().String("role", "", "Role name of the new role binding.")
-	cmd.Flags().String("principal", "", "Qualified principal name for the role binding.")
+	cmd.Flags().String("principal", "", `Principal type and identifier using "Prefix:ID" format.`)
 	addClusterFlags(cmd, c.cfg, c.CLICommand)
-	cmd.Flags().String("resource", "", "Qualified resource name for the role binding.")
+	cmd.Flags().String("resource", "", `Resource type and identifier using "Prefix:ID" format.`)
 	cmd.Flags().Bool("prefix", false, "Whether the provided resource name is treated as a prefix pattern.")
 	pcmd.AddOutputFlag(cmd)
 

internal/iam/command_rbac_role_binding_delete.go

@@ -35,10 +35,10 @@ func (c *roleBindingCommand) newDeleteCommand() *cobra.Command {
 	}
 
 	cmd.Flags().String("role", "", "Role name of the existing role binding.")
-	cmd.Flags().String("principal", "", "Qualified principal name associated with the role binding.")
+	cmd.Flags().String("principal", "", `Principal type and identifier using "Prefix:ID" format.`)
 	pcmd.AddForceFlag(cmd)
 	addClusterFlags(cmd, c.cfg, c.CLICommand)
-	cmd.Flags().String("resource", "", "Qualified resource name for the role binding.")
+	cmd.Flags().String("resource", "", `Resource type and identifier using "Prefix:ID" format.`)
 	cmd.Flags().Bool("prefix", false, "Whether the provided resource name is treated as a prefix pattern.")
 	pcmd.AddOutputFlag(cmd)
 

internal/iam/command_rbac_role_binding_list.go

@@ -31,7 +31,7 @@ func (c *roleBindingCommand) newListCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "list",
 		Short: "List role bindings.",
-		Long:  "List the role bindings for a particular principal and/or role, and a particular scope.",
+		Long:  "List role bindings assigned to a principal based on scopes.",
 		Args:  cobra.NoArgs,
 		RunE:  c.list,
 	}
@@ -59,57 +59,57 @@ func (c *roleBindingCommand) newListCommand() *cobra.Command {
 				Code: "confluent iam rbac role-binding list --principal User:u-123456 --inclusive",
 			},
 			examples.Example{
-				Text: "List the role bindings for the current user at the environment scope and its nested scopes:",
+				Text: "List the role bindings for the current user with the environment scope and nested scopes:",
 				Code: "confluent iam rbac role-binding list --current-user --environment env-123456 --inclusive",
 			},
 		)
 	} else {
 		cmd.Example = examples.BuildExampleString(
 			examples.Example{
 				Text: "Only use the `--resource` flag when specifying a `--role` with no `--principal` specified. If specifying a `--principal`, then the `--resource` flag is ignored. To list role bindings for a specific role on an identified resource:",
-				Code: "confluent iam rbac role-binding list --kafka-cluster $KAFKA_CLUSTER_ID --role DeveloperRead --resource Topic",
+				Code: "confluent iam rbac role-binding list --kafka-cluster 0000000000000000000000 --role DeveloperRead --resource Topic:my-topic",
 			},
 			examples.Example{
 				Text: "List the role bindings for a specific principal:",
-				Code: "confluent iam rbac role-binding list --kafka-cluster $KAFKA_CLUSTER_ID --principal User:my-user",
+				Code: "confluent iam rbac role-binding list --kafka-cluster 0000000000000000000000 --principal User:my-user",
 			},
 			examples.Example{
 				Text: "List the role bindings for a specific principal, filtered to a specific role:",
-				Code: "confluent iam rbac role-binding list --kafka-cluster $KAFKA_CLUSTER_ID --principal User:my-user --role DeveloperRead",
+				Code: "confluent iam rbac role-binding list --kafka-cluster 0000000000000000000000 --principal User:my-user --role DeveloperRead",
 			},
 			examples.Example{
 				Text: "List the principals bound to a specific role:",
-				Code: "confluent iam rbac role-binding list --kafka-cluster $KAFKA_CLUSTER_ID --role DeveloperWrite",
+				Code: "confluent iam rbac role-binding list --kafka-cluster 0000000000000000000000 --role DeveloperWrite",
 			},
 			examples.Example{
 				Text: "List the principals bound to a specific resource with a specific role:",
-				Code: "confluent iam rbac role-binding list --kafka-cluster $KAFKA_CLUSTER_ID --role DeveloperWrite --resource Topic:my-topic",
+				Code: "confluent iam rbac role-binding list --kafka-cluster 0000000000000000000000 --role DeveloperWrite --resource Topic:my-topic",
 			},
 		)
 	}
 
-	cmd.Flags().String("principal", "", "Principal whose role bindings should be listed.")
-	cmd.Flags().Bool("current-user", false, "Show role bindings belonging to the current user.")
-	cmd.Flags().String("role", "", "List role bindings under a specific role given to a principal. Or if no principal is specified, list principals with the role.")
+	cmd.Flags().String("principal", "", "Principal ID, which limits role bindings to this principal. If unspecified, list all principals and role bindings.")
+	cmd.Flags().Bool("current-user", false, "List role bindings assigned to the current user.")
+	cmd.Flags().String("role", "", `Predefined role assigned to "--principal". If "--principal" is unspecified, list all principals assigned the role.`)
 
 	if c.cfg.IsCloudLogin() {
-		cmd.Flags().String("environment", "", "Environment ID for scope of role binding listings.")
-		cmd.Flags().Bool("current-environment", false, "Use current environment ID for scope.")
-		cmd.Flags().String("cloud-cluster", "", "Cloud cluster ID for scope of role binding listings.")
-		cmd.Flags().String("kafka-cluster", "", "Kafka cluster ID for scope of role binding listings.")
-		cmd.Flags().String("schema-registry-cluster", "", "Schema Registry cluster ID for the role binding listings.")
-		cmd.Flags().String("ksql-cluster", "", "ksqlDB cluster name for the role binding listings.")
+		cmd.Flags().String("environment", "", "Environment ID, which specifies the environment scope.")
+		cmd.Flags().Bool("current-environment", false, "Use current environment ID for the environment scope.")
+		cmd.Flags().String("cloud-cluster", "", "Cloud cluster ID, which specifies the cloud cluster scope.")
+		cmd.Flags().String("kafka-cluster", "", "Kafka cluster ID, which specifies the Kafka cluster scope.")
+		cmd.Flags().String("schema-registry-cluster", "", "Schema Registry cluster ID, which specifies the Schema Registry cluster scope.")
+		cmd.Flags().String("ksql-cluster", "", "ksqlDB cluster name, which specifies the ksqlDB cluster scope.")
 	} else {
-		cmd.Flags().String("kafka-cluster", "", "Kafka cluster ID for scope of role binding listings.")
-		cmd.Flags().String("schema-registry-cluster", "", "Schema Registry cluster ID for scope of role binding listings.")
-		cmd.Flags().String("ksql-cluster", "", "ksqlDB cluster ID for scope of role binding listings.")
-		cmd.Flags().String("connect-cluster", "", "Kafka Connect cluster ID for scope of role binding listings.")
-		cmd.Flags().String("cluster-name", "", "Cluster name to uniquely identify the cluster for role binding listings.")
+		cmd.Flags().String("kafka-cluster", "", "Kafka cluster ID, which specifies the Kafka cluster scope.")
+		cmd.Flags().String("schema-registry-cluster", "", "Schema Registry cluster ID, which specifies the Schema Registry cluster scope.")
+		cmd.Flags().String("ksql-cluster", "", "ksqlDB cluster ID, which specifies the ksqlDB cluster scope.")
+		cmd.Flags().String("connect-cluster", "", "Kafka Connect cluster ID, which specifies the Connect cluster scope.")
+		cmd.Flags().String("cluster-name", "", "Cluster name, which specifies the cluster scope.")
 		pcmd.AddContextFlag(cmd, c.CLICommand)
 	}
 
-	cmd.Flags().String("resource", "", "If specified with a role and no principals, list principals with role bindings to the role for this qualified resource.")
-	cmd.Flags().Bool("inclusive", false, "List all role bindings in a specific scope and its nested scopes.")
+	cmd.Flags().String("resource", "", `Resource type and identifier using "Prefix:ID" format. If specified with "--role" and no principals, list all principals and role bindings.`)
+	cmd.Flags().Bool("inclusive", false, "List role bindings for specified scopes and nested scopes. Otherwise, list role bindings for the specified scopes. If scopes are unspecified, list only organization-scoped role bindings.")
 	pcmd.AddOutputFlag(cmd)
 
 	return cmd

test/fixtures/output/iam/acl/create-help-onprem.golden

@@ -29,7 +29,7 @@ Flags:
       --transactional-id string   Set the TransactionalID resource.
       --topic string              Set the topic resource. With this option the ACL grants the provided
                                   operations on the topics that start with that prefix, depending on whether
-                                  the --prefix option was also passed.
+                                  the "--prefix" option was also passed.
       --prefix                    Set to match all resource names prefixed with this value.
       --context string            CLI context name.
 

test/fixtures/output/iam/acl/delete-help-onprem.golden

@@ -21,7 +21,7 @@ Flags:
       --transactional-id string   Set the TransactionalID resource.
       --topic string              Set the topic resource. With this option the ACL grants the provided
                                   operations on the topics that start with that prefix, depending on whether
-                                  the --prefix option was also passed.
+                                  the "--prefix" option was also passed.
       --prefix                    Set to match all resource names prefixed with this value.
       --force                     Skip the deletion confirmation prompt.
       --context string            CLI context name.

test/fixtures/output/iam/acl/list-help-onprem.golden

@@ -25,7 +25,7 @@ Flags:
       --transactional-id string   Set the TransactionalID resource.
       --topic string              Set the topic resource. With this option the ACL grants the provided
                                   operations on the topics that start with that prefix, depending on whether
-                                  the --prefix option was also passed.
+                                  the "--prefix" option was also passed.
       --prefix                    Set to match all resource names prefixed with this value.
       --context string            CLI context name.
   -o, --output string             Specify the output format as "human", "json", or "yaml". (default "human")

test/fixtures/output/iam/rbac/role-binding/create-help-onprem.golden

@@ -6,18 +6,18 @@ Usage:
 Examples:
 Create a role binding for the principal permitting it produce to topic "my-topic":
 
-  $ confluent iam rbac role-binding create --principal User:appSA --role DeveloperWrite --resource Topic:my-topic --kafka-cluster $KAFKA_CLUSTER_ID
+  $ confluent iam rbac role-binding create --principal User:appSA --role DeveloperWrite --resource Topic:my-topic --kafka-cluster 0000000000000000000000
 
 Flags:
       --role string                      REQUIRED: Role name of the new role binding.
-      --principal string                 REQUIRED: Qualified principal name for the role binding.
+      --principal string                 REQUIRED: Principal type and identifier using "Prefix:ID" format.
       --kafka-cluster string             Kafka cluster ID for the role binding.
       --schema-registry-cluster string   Schema Registry cluster ID for the role binding.
       --ksql-cluster string              ksqlDB cluster ID for the role binding.
       --connect-cluster string           Kafka Connect cluster ID for the role binding.
       --cluster-name string              Cluster name to uniquely identify the cluster for role binding listings.
       --context string                   CLI context name.
-      --resource string                  Qualified resource name for the role binding.
+      --resource string                  Resource type and identifier using "Prefix:ID" format.
       --prefix                           Whether the provided resource name is treated as a prefix pattern.
   -o, --output string                    Specify the output format as "human", "json", or "yaml". (default "human")
 

test/fixtures/output/iam/rbac/role-binding/create-help.golden

@@ -42,15 +42,15 @@ Grant the "FlinkDeveloper" role to principal "User:u-123456" in environment "env
 
 Flags:
       --role string                      REQUIRED: Role name of the new role binding.
-      --principal string                 REQUIRED: Qualified principal name for the role binding.
+      --principal string                 REQUIRED: Principal type and identifier using "Prefix:ID" format.
       --environment string               Environment ID for scope of role-binding operation.
       --current-environment              Use current environment ID for scope.
       --cloud-cluster string             Cloud cluster ID for the role binding.
       --flink-region string              Flink region ID for the role binding.
       --kafka-cluster string             Kafka cluster ID for the role binding.
       --schema-registry-cluster string   Schema Registry cluster ID for the role binding.
       --ksql-cluster string              ksqlDB cluster name for the role binding.
-      --resource string                  Qualified resource name for the role binding.
+      --resource string                  Resource type and identifier using "Prefix:ID" format.
       --prefix                           Whether the provided resource name is treated as a prefix pattern.
   -o, --output string                    Specify the output format as "human", "json", or "yaml". (default "human")
 

test/fixtures/output/iam/rbac/role-binding/delete-help-onprem.golden

@@ -5,15 +5,15 @@ Usage:
 
 Flags:
       --role string                      REQUIRED: Role name of the existing role binding.
-      --principal string                 REQUIRED: Qualified principal name associated with the role binding.
+      --principal string                 REQUIRED: Principal type and identifier using "Prefix:ID" format.
       --force                            Skip the deletion confirmation prompt.
       --kafka-cluster string             Kafka cluster ID for the role binding.
       --schema-registry-cluster string   Schema Registry cluster ID for the role binding.
       --ksql-cluster string              ksqlDB cluster ID for the role binding.
       --connect-cluster string           Kafka Connect cluster ID for the role binding.
       --cluster-name string              Cluster name to uniquely identify the cluster for role binding listings.
       --context string                   CLI context name.
-      --resource string                  Qualified resource name for the role binding.
+      --resource string                  Resource type and identifier using "Prefix:ID" format.
       --prefix                           Whether the provided resource name is treated as a prefix pattern.
   -o, --output string                    Specify the output format as "human", "json", or "yaml". (default "human")
 

test/fixtures/output/iam/rbac/role-binding/delete-help.golden

@@ -10,7 +10,7 @@ Delete the role "ResourceOwner" for the resource "Topic:my-topic" on the Kafka c
 
 Flags:
       --role string                      REQUIRED: Role name of the existing role binding.
-      --principal string                 REQUIRED: Qualified principal name associated with the role binding.
+      --principal string                 REQUIRED: Principal type and identifier using "Prefix:ID" format.
       --force                            Skip the deletion confirmation prompt.
       --environment string               Environment ID for scope of role-binding operation.
       --current-environment              Use current environment ID for scope.
@@ -19,7 +19,7 @@ Flags:
       --kafka-cluster string             Kafka cluster ID for the role binding.
       --schema-registry-cluster string   Schema Registry cluster ID for the role binding.
       --ksql-cluster string              ksqlDB cluster name for the role binding.
-      --resource string                  Qualified resource name for the role binding.
+      --resource string                  Resource type and identifier using "Prefix:ID" format.
       --prefix                           Whether the provided resource name is treated as a prefix pattern.
   -o, --output string                    Specify the output format as "human", "json", or "yaml". (default "human")
 

test/fixtures/output/iam/rbac/role-binding/delete-missing-role-cloud.golden

@@ -9,7 +9,7 @@ Delete the role "ResourceOwner" for the resource "Topic:my-topic" on the Kafka c
 
 Flags:
       --role string                      REQUIRED: Role name of the existing role binding.
-      --principal string                 REQUIRED: Qualified principal name associated with the role binding.
+      --principal string                 REQUIRED: Principal type and identifier using "Prefix:ID" format.
       --force                            Skip the deletion confirmation prompt.
       --environment string               Environment ID for scope of role-binding operation.
       --current-environment              Use current environment ID for scope.
@@ -18,7 +18,7 @@ Flags:
       --kafka-cluster string             Kafka cluster ID for the role binding.
       --schema-registry-cluster string   Schema Registry cluster ID for the role binding.
       --ksql-cluster string              ksqlDB cluster name for the role binding.
-      --resource string                  Qualified resource name for the role binding.
+      --resource string                  Resource type and identifier using "Prefix:ID" format.
       --prefix                           Whether the provided resource name is treated as a prefix pattern.
   -o, --output string                    Specify the output format as "human", "json", or "yaml". (default "human")