add --roles flag to tsh request search, that allows listing requestable roles

[tangyatsu]

What

Resolves: #7693

tsh now supports listing requestable roles via tsh request search --roles, enforces mutual exclusivity between --roles and --kind flags, and adds a hint to tsh request new --roles, that suggests using tsh request search --roles when the requested role is not allowed.

changelog: Added --roles flag for tsh request search, allowing users to list all requestable roles. This flag is mutually exclusive with --kind

Manual Tests

A local test cluster was created with a requester role that is allowed to request several other roles.
A test user with the requester role was created.

The following tests were performed:

• tsh request search returns an error

• tsh request search --roles succeeds, lists requestable roles

• tsh request search --kind returns an error

• tsh request search --kind=db succeeds

• tsh request search --roles --kind=db returns error

• tsh request search --roles --kind returns error

• tsh request new --roles confirmed the new hint suggesting tsh request search --roles

[github-actions]

Amplify deployment status

Branch	Commit	Job ID	Status	Preview	Updated (UTC)
tangyatsu/add-ability-to-list-requestable-roles-via-tsh	d9d7e1c	8	✅SUCCEED	tangyatsu-add-ability-to-list-requestable-roles-via-tsh	2025-11-21 19:51:58

[zmb3]

What's the difference between GetAccessCapabilities and ListRequestableRoles?

The latter seems more appropriate (at least in name).

[tangyatsu]

Yeah, good point, ListRequestableRoles looks much better here

[zmb3]

I would take a look at clientutils.Resources, which is a helper function that implements the pagination loop here.

[tangyatsu]

So, I used clientutils.Resources here instead of my original loop. I also thought about adding a new client method with a suitable signature, something like:

ListRequestableRolesV2(ctx context.Context, pageSize int, pageToken string) (*proto.ListRequestableRolesResponse, error)

but I wasn’t sure. We have examples like:

// ListAccessLists returns a paginated list of access lists. 
ListAccessLists(context.Context, int, string) ([]*accesslist.AccessList, string, error) 
// ListAccessListsV2 returns a filtered and sorted paginated list of access lists. 
ListAccessListsV2(context.Context, *accesslistv1.ListAccessListsV2Request) ([]*accesslist.AccessList, string, error)

And the original ListAccessLists, which had a suitable signature, is now deprecated.

[rosstimothy]

If we used the generated Getters which are nil safe we could eliminate a few lines here.

Suggested change

	resp, err := clt.ListRequestableRoles(ctx, req)
	if err != nil {
	return nil, "", trace.Wrap(err)
	}
	return resp.Roles, resp.NextPageToken, nil
	resp, err := clt.ListRequestableRoles(ctx, req)
	return resp.GetRoles(), resp.GetNextPageToken(), trace.Wrap(err)

[tangyatsu]

I really like that, I’ll update the PR

[backport-bot-workflows]

@tangyatsu See the table below for backport results.

Branch	Result
branch/v18	Failed