Improve Powershell sdk by specifying required permissions

[Kralizek]

Hi all.
I love the PowerShell toolkit. I really do!
If there is one thing i would love to see improved is the documentation of which permission each method requires.

Whilst it can easily be inferred in the C# SDK since the methods have similiar name, the PowerShell SDK defines methods according to PS standard naming conventions. This makes the SDK feel natural (that's why i love it) but it's a nightmare to scope the permission needed for a certain script (think of deployment/administrative scripts).

It would be perfect if methods specified the required permission in their comment snippet, but i can settle for having the required permission clearly stated on the PowerShell SDK reference.

[Kralizek]

As a concrete example, it's really hard to tell that the cmdlet Get-Ec2Instance maps to the API call describe-instances and therefore such permission is required.

Showing that information here would suffice for me

[stevejroberts]

Happy to hear you are enjoying the tools!

The cmdlets do list the underlying API operation in their 'synopsis' documentation, as shown here for Get-EC2Instance:

PS C:> Get-Help Get-EC2Instance
NAME
Get-EC2Instance

SYNOPSIS
Invokes the DescribeInstances operation against Amazon Elastic Compute Cloud._
...

I'm wondering if we can somehow make this even clearer (and usable in automation scenarios, e.g. in a script obtain the API call to be made and then setup the necessary permissions ahead of the call). We could achieve this with a cmdlet that outputs the underlying API operation for a given cmdlet (to save wading through the help text). We have the ability, through Get-AWSCmdletName, to output the name of a cmdlet given the service API name, but not the inverse. Perhaps this could be extended to offer the inverse operation although a separate cmdlet, if we go that route, feels cleaner to me.

Open to other ideas too if you have workflow scenarios (beyond simple lookup) you'd like us to consider.

[Kralizek]

Oh my, sorry. I had totally missed the synopsis. Even in the link I posted. Shame on me. I was so expecting to see it as a specific section so i just scrolled through.

A feature I would love both on the PowerShell and in the normal SDK is to track api calls in a certain context and then return the list of operations.

In PowerShell could be

Start-AWSTracking
... Execute your code
Stop-AWSTracking

[outputs list of api invoked]

This would be awesome also in the normal SDK.

My use case is that we had to purify our code base from usages of developer keys in production and tracking what each application does proved to be quite time consuming and error-prone.

Once the list of used APIs is given, generating the IAM policy is almost automatable.

[PavelSafronov]

The tracking approach sounds like a great idea for PowerShell.
You can actually track similar details when using the SDK. There are at least two approaches:

1. Use the BeforeRequestEvent/AfterResponseEvent/ExceptionEvent events on the client object to track which calls were made by the client.
2. Enable SDK metrics and parse the metrics logs - or use an in-memory logger - to identify which calls are made.

[stevejroberts]

Added items to our backlog to consider either (or both) the tracking cmdlets approach and also extending the cmdlet documentation to include required permissions, if this can be auto-generated. Thanks for the feature requests!