Boto3-1.3.1 - cryptic errors for invalid Parameters - SSM send_command for AWS-RunShellScript

I spent hours figuring out how to send a list of commands to SSM send_command for document AWS-RunShellScript.

Really this is a basic documentation problem - once a few examples of using AWS SSM become easy to find, things will be a lot better, but the number of combinations of possible errors is large, and there is a lot of trial and error pain in store for those who experiment.

This is the documentation for doc parameters:

"               u'Parameters': [{u'Description': u'(Required) Specify a shell script or a command to run.',",
"                                u'Name': u'commands',",
"                                u'Type': u'StringList'},",
"                               {u'DefaultValue': u'\"\"',",
"                                u'Description': u'(Optional) The path to the working directory on your instance.',",
"                                u'Name': u'workingDirectory',",
"                                u'Type': u'String'},",
"                               {u'DefaultValue': u'\"3600\"',",
"                                u'Description': u'(Optional) The time in seconds for a command to complete before it is considered to have failed. Default is 3600 (1 hour). Maximum is 28800 (8 hours).',",
"                                u'Name': u'executionTimeout',",
"                                u'Type': u'String'}],",

but then there are lots of examples of plugin parameters as well, which have different names:

    "aws:runPowerShellScript":{
        "properties":[
            {
                "id":"0.aws:runPowerShellScript",
                "runCommand":"{{ commands }}",
                "workingDirectory":"{{ workingDirectory }}",
                "timeoutSeconds":"{{ executionTimeout }}"
            }
        ]
    }

And this is the (almost totally undocumented) structure required for success:

    commandList = []

    commandList.append("echo 96954a4265c80bc92763776de384daf0")
    commandList.append("echo 96954a4265c80bc92763776de384XXXX")

    parameterDict = {}
    parameterDict["commands"] = commandList
    parameterDict["workingDirectory"] = ["/home/ec2-user/"]
    parameterDict["executionTimeout"] = ["600"]

My two complaints which caused me hours of experimentation:

workingDirectory and executionTimeout keys require lists or tuples despite the fact that this makes no intuitive sense (what does passing lists of length > 1 mean?) and the documentation explicitly states u’Type’: u’String’. In this case, the error messages told me about the type incompatibility and I was able to work through it, but why is the documentation wrong? I was under the impression that the structure drove the type checking internally and was very reluctant to believe the errors - it would be much more straightforward if everything were at least consistent especially when it is not intuitive.

But the real kicker was this one:

It was hard to figure out even which key names I should be using because there were lots of possibilities online and I was not sure where to begin. But when the keys passed in the parameters dict are wrong, the error is:

Info: <class ‘botocore.exceptions.ClientError’>

ClientError(u’An error occurred (InvalidParameters) when calling the SendCommand operation: ',)

it took hours to find that I was using timeoutSeconds instead of executionTimeout when creating my Parameter dict.

Sorry this is so long - just wanted to give you full context so you can divine how to improve the error feedback for people getting started. I find most boto/aws systems to be reasonably straightforward to get started with despite the complexities - but this one surprised me.

Thanks.

[JeroenSchmidt]

I would just like to add some more information to this topic for future visitors. I had a similar problem but I wanted to assign the execution timeout to 36 hours, which produced the following error: InvalidParameters: An error occurred (InvalidParameters) when calling the SendCommand operation: . It turns out that the max execution time someone can assign is 48 hours.

Documentation related to this topic.

[tim-finnigan]

Checking in again - I think feature requests directly related to the SSM agent should be opened for tracking in this repository instead: https://github.com/aws/amazon-ssm-agent/issues. I believe that is the best place to escalate issues involving error messages or documentation examples for this going forward. Please let us know if you have any feedback or updates on this issue as it was originally opened quite a while ago.