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

[paulpharr]

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.

[kyleknap]

Thanks for the feedback. We will look to see if we can get examples for SSM.

[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.

[XiangkunYe]

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.

Hello! I met the same problem, but I'm a little confused that since you said the maximum execution time is 48 hours, why would this error occur when you assigned it to 36 hours?

[Rkubinski]

Hi @XiangkunYe @JeroenSchmidt , did anyone figure out what the max execution time was finally ? Struggling to find actual documentation

[tikkanz]

Hi @XiangkunYe @JeroenSchmidt , did anyone figure out what the max execution time was finally ? Struggling to find actual documentation

Spent a bit of time sorting this out. I found the error message returned when you specify an "invalid" executionTimeout a bit misleading An error occurred (InvalidParameters) when calling the SendCommand operation: document RunShellScriptLONG does not support parameters. Particularly the bit about the document not supporting parameters. Essentially this is just saying that the argument specified for the timeout was invalid according to the allowedPattern in the document. The max execution time for the default AWS-RunShellScript document is 48 hours. If you want/need a longer max execution time, then you can clone that document and update the allowedPattern for executionTimeout accordingly. For example the following would allow max execution time of 96 hours.

"allowedPattern":"([1-9][0-9]{0,4})|[1-2][0-9]{5}|(3[0-3][0-9]{4})|(34[0-4][0-9]{3})|(345[0-5][0-9]{2})|(345600)"

[tim-finnigan]

You could use the describe_document command to get the executionTimeout information:

import boto3
client = boto3.client('ssm')

response = client.describe_document(
    Name='AWS-RunShellScript',
)
 
print(response)

Does that help? If anyone is still tracking this issue please clarify any specific updates you are requesting to the documentation.

[github-actions[bot]]

Greetings! It looks like this issue hasn’t been active in longer than five days. We encourage you to check if this is still an issue in the latest release. In the absence of more information, we will be closing this issue soon. If you find that this is still a problem, please feel free to provide a comment or upvote with a reaction on the initial post to prevent automatic closure. If the issue is already closed, please feel free to open a new one.

[tikkanz]

> Although the allowedPattern specified will enable you to specify a longer executionTimeout than the default, the actual max time that a command can run is hard-coded at 172800 seconds (48 hours), so the command will run, but will be stopped after 48 hours.

[tim-finnigan]

Thanks @tikkanz for following up. I’m going to link this comment explaining how to create a custom document for increasing the max timeout as that might help some people.

To summarize the ask here I think it is to add an error message like Default executionTimeout limit exceeded (172800 seconds)... rather than An error occurred (InvalidParameters)...

[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.