boto3_ssm

Connection module for Amazon SSM using boto3.

Renamed from boto_ssm to boto3_ssm and rewritten to use the boto3 ssm client APIs directly via saltext.boto3.utils.boto3mod. The legacy boto2 code path (object-style access, retry loops) has been removed.

depends:

  • boto3 >= 1.28.0

  • botocore >= 1.31.0

configuration:

This module accepts explicit SSM credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More Information available at:

http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html

If IAM roles are not used you need to specify them either in the minion’s config file or as a profile. For example, to specify them in the minion’s config file:

ssm.keyid: GKTADJGHEIQSXMKKRBJ08H
ssm.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs

A region may also be specified in the configuration:

ssm.region: us-east-1

It’s also possible to specify key, keyid and region via a profile, either as a passed in dict, or as a string to pull from pillars or minion config:

myprofile:
    keyid: GKTADJGHEIQSXMKKRBJ08H
    key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
    region: us-east-1

Added in version 1.0.0.

saltext.boto3.modules.boto3_ssm.__virtual__()[source]

Only load if boto3 is available.

saltext.boto3.modules.boto3_ssm.get_parameter(name, withdecryption=False, resp_json=False, region=None, key=None, keyid=None, profile=None)[source]

Retrieves a parameter from SSM Parameter Store.

CLI Example:

salt-call boto3_ssm.get_parameter test-param withdecryption=True
saltext.boto3.modules.boto3_ssm.put_parameter(Name, Value, Description=None, Type='String', KeyId=None, Overwrite=False, AllowedPattern=None, region=None, key=None, keyid=None, profile=None)[source]

Set a parameter in the SSM parameter store.

CLI Example:

salt-call boto3_ssm.put_parameter test-param test_value Type=SecureString KeyId=alias/aws/ssm
saltext.boto3.modules.boto3_ssm.delete_parameter(Name, region=None, key=None, keyid=None, profile=None)[source]

Remove a parameter from the SSM parameter store.

CLI Example:

salt-call boto3_ssm.delete_parameter test-param
saltext.boto3.modules.boto3_ssm.send_command(targets, document_name='AWS-RunShellScript', parameters=None, comment=None, timeout_seconds=None, output_s3_bucket_name=None, output_s3_key_prefix=None, max_concurrency=None, max_errors=None, region=None, key=None, keyid=None, profile=None)[source]

Invoke an SSM document against the given targets.

targets

Either a list of EC2 instance IDs (strings) or a list of Targets dicts ([{"Key": "tag:Env", "Values": ["prod"]}]). A single instance ID string is also accepted.

document_name

Name of the SSM document to run. Defaults to AWS-RunShellScript.

parameters

Dict of parameters to pass to the document. Scalar values are wrapped in a single-element list automatically.

comment

Optional user-supplied comment.

timeout_seconds

How long (in seconds) the command can remain in Pending state.

output_s3_bucket_name, output_s3_key_prefix

Optional S3 location for command output.

max_concurrency, max_errors

Optional concurrency/error thresholds (pass a number or a percentage string such as "50%").

Returns the Command dict from the API on success, or {"error": ...}.

CLI Example:

salt '*' boto3_ssm.send_command i-0123 parameters='{"commands": ["uptime"]}'
saltext.boto3.modules.boto3_ssm.run_shell_script(command, targets, comment=None, timeout_seconds=None, execution_timeout=None, output_s3_bucket_name=None, output_s3_key_prefix=None, max_concurrency=None, max_errors=None, region=None, key=None, keyid=None, profile=None)[source]

Run one or more shell commands on the given targets via the AWS-RunShellScript SSM document.

command

A single shell command string or a list of command strings.

targets

Either a list of EC2 instance IDs or a list of Targets dicts.

execution_timeout

Per-command execution timeout in seconds (document parameter executionTimeout). Distinct from timeout_seconds which bounds only the Pending state.

CLI Example:

salt '*' boto3_ssm.run_shell_script 'uptime' i-0123
saltext.boto3.modules.boto3_ssm.get_command_invocation(command_id, instance_id, region=None, key=None, keyid=None, profile=None)[source]

Fetch the result of a single Run Command invocation.

command_id

The Command ID returned by send_command().

instance_id

The EC2 instance ID the command ran on.

CLI Example:

salt '*' boto3_ssm.get_command_invocation abc123 i-0123
saltext.boto3.modules.boto3_ssm.list_command_invocations(command_id=None, instance_id=None, details=False, region=None, key=None, keyid=None, profile=None)[source]

List Run Command invocations, optionally filtered by command_id or instance_id. Set details=True to include command plugin output.

CLI Example:

salt '*' boto3_ssm.list_command_invocations command_id=abc123 details=True