Amazon-ssm-agent: Clarify differences between command, policy, and automation

[copumpkin]

This is more of a bug against the public documentation on the AWS site, but it's very unclear to me (as a potential plugin author as well as an SSM user looking at extensibility) what the primary differences between the three are.

My (probably very wrong!) understanding so far, based on the examples I can find in this repo:

1. Command-based plugins run off a long-poll, so you get nearly instantaneous response times.
2. Policy-based plugins run on a schedule. The only example I could find was the inventory which seems to do that, and I couldn't trigger it via a command
3. Automations can trigger AWS API actions like spinning up instances and snapping images

Ideally what I'd like to see is clearer user-level documentation on the distinctions between the document types on the AWS site, as well as some commentary in this repository on the distinctions as they apply to the programming model.

[AnanthatAWS]

Hi copumpkin, thank you for being an active customer of the service. I presume you are referring to the documentation available here - http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/sysman-ssm-docs.html

Thanks for the feedback on the documentation, we will look at how we can make it easier for customers to understand and on this repository as well. To answer your specific question, you can use:

1. Run Command - Command documents
2. State Manager (on schedule) - Command and Policy documents
3. Automation - Automation documents

Thanks
Ananth

[copumpkin]

Yeah, that was the page I was referring to, sorry. I guess all I mean is what a "policy" document means when it comes down to the code and what actually runs on my machines. I see that the inventory policy document is running the inventory plugin periodically. At a plugin interface level, is there any difference in how inventory gets invoked vs. runShellScript?

My mental model is that each plugin can basically expose a "function" which you can invoke (by passing it parameters) as a task in _any_ of the three document types. A command document would be a one-off immediate invocation, a policy document would be a cron invocation, and an automation still feels a bit nebulous to me, other than allowing AWS API calls in addition to commands.

Unfortunately my mental model is shattered immediately by the web interface, which (seemingly arbitrarily by my model above) tells me for example that I'm not allowed to use aws:softwareInventory in a Command document. That's where I'm really struggling to understand the differences. It seems like aws:softwareInventory is basically a "command" (not by SSM definition but everyone else would call it that) that runs on a machine and "returns" some sort of JSON representation of an inventory. By making it a Policy, I'm asking SSM to run that "command" every half hour, but otherwise it's still the same sort of thing.

What am I missing?

[defond0]

Just to elaborate on @copumpkins point above, if I create a command document with the aws:softwareInventory and run it through send-command action I get

aws:softwareInventory plugin can only be invoked via ssm-associate

when I check out the docs I do not see this behavior documented. I am not complaining about the behavior, just that I cannot find it in the docs.

[mmendonca3]

Thank you for your request.

I have updated the appropriate team so that they are aware of this issue and can make the required changes.

[nehalaws]

Thank you we have updated our documentation https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-inventory-configuring.html

[copumpkin]

@nehalaws I'm not quite clear on how that page explains this. Did you include the right link?

Edit: I mean, it covers my very specific example of one confusion around aws:softwareInventory, but not the broader point on what the three concepts mean or why the distinctions must exist.