Amazon Simple Systems Manager (SSM)

2017/08/22 - Amazon Simple Systems Manager (SSM) - 1 new 8 updated api methods

Changes  Changes to associations in Systems Manager State Manager can now be recorded. Previously, when you edited associations, you could not go back and review older association settings. Now, associations are versioned, and can be named using human-readable strings, allowing you to see a trail of association changes. You can also perform rate-based scheduling, which allows you to schedule associations more granularly.

ListAssociationVersions (new) Link ¶

Retrieves all versions of an association for a specific association ID.

See also: AWS API Documentation

Request Syntax

client.list_association_versions(
    AssociationId='string',
    MaxResults=123,
    NextToken='string'
)
type AssociationId

string

param AssociationId

[REQUIRED]

The association ID for which you want to view all versions.

type MaxResults

integer

param MaxResults

The maximum number of items to return for this call. The call also returns a token that you can specify in a subsequent call to get the next set of results.

type NextToken

string

param NextToken

A token to start the list. Use this token to get the next set of results.

rtype

dict

returns

Response Syntax

{
    'AssociationVersions': [
        {
            'AssociationId': 'string',
            'AssociationVersion': 'string',
            'CreatedDate': datetime(2015, 1, 1),
            'Name': 'string',
            'DocumentVersion': 'string',
            'Parameters': {
                'string': [
                    'string',
                ]
            },
            'Targets': [
                {
                    'Key': 'string',
                    'Values': [
                        'string',
                    ]
                },
            ],
            'ScheduleExpression': 'string',
            'OutputLocation': {
                'S3Location': {
                    'OutputS3Region': 'string',
                    'OutputS3BucketName': 'string',
                    'OutputS3KeyPrefix': 'string'
                }
            },
            'AssociationName': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • AssociationVersions (list) --

      Information about all versions of the association for the specified association ID.

      • (dict) --

        Information about the association version.

        • AssociationId (string) --

          The ID created by the system when the association was created.

        • AssociationVersion (string) --

          The association version.

        • CreatedDate (datetime) --

          The date the association version was created.

        • Name (string) --

          The name specified when the association was created.

        • DocumentVersion (string) --

          The version of an SSM document used when the association version was created.

        • Parameters (dict) --

          Parameters specified when the association version was created.

          • (string) --

            • (list) --

              • (string) --

        • Targets (list) --

          The targets specified for the association when the association version was created.

          • (dict) --

            An array of search criteria that targets instances using a Key,Value combination that you specify. Targets is required if you don't provide one or more instance IDs in the call.

            • Key (string) --

              User-defined criteria for sending commands that target instances that meet the criteria. Key can be tag:<Amazon EC2 tag> or InstanceIds. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

            • Values (list) --

              User-defined criteria that maps to Key. For example, if you specified tag:ServerRole, you could specify value:WebServer to execute a command on instances that include Amazon EC2 tags of ServerRole,WebServer. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

              • (string) --

        • ScheduleExpression (string) --

          The cron or rate schedule specified for the association when the association version was created.

        • OutputLocation (dict) --

          The location in Amazon S3 specified for the association when the association version was created.

          • S3Location (dict) --

            An Amazon S3 bucket where you want to store the results of this request.

            • OutputS3Region (string) --

              (Deprecated) You can no longer specify this parameter. The system ignores it. Instead, Systems Manager automatically determines the Amazon S3 bucket region.

            • OutputS3BucketName (string) --

              The name of the Amazon S3 bucket.

            • OutputS3KeyPrefix (string) --

              The Amazon S3 bucket subfolder.

        • AssociationName (string) --

          The name specified for the association version when the association version was created.

    • NextToken (string) --

      The token for the next set of items to return. Use this token to get the next set of results.

CreateAssociation (updated) Link ¶
Changes (request, response)
Request
{'AssociationName': 'string'}
Response
{'AssociationDescription': {'AssociationName': 'string',
                            'AssociationVersion': 'string'}}

Associates the specified Systems Manager document with the specified instances or targets.

When you associate a document with one or more instances using instance IDs or tags, the SSM Agent running on the instance processes the document and configures the instance as specified.

If you associate a document with an instance that already has an associated document, the system throws the AssociationAlreadyExists exception.

See also: AWS API Documentation

Request Syntax

client.create_association(
    Name='string',
    DocumentVersion='string',
    InstanceId='string',
    Parameters={
        'string': [
            'string',
        ]
    },
    Targets=[
        {
            'Key': 'string',
            'Values': [
                'string',
            ]
        },
    ],
    ScheduleExpression='string',
    OutputLocation={
        'S3Location': {
            'OutputS3Region': 'string',
            'OutputS3BucketName': 'string',
            'OutputS3KeyPrefix': 'string'
        }
    },
    AssociationName='string'
)
type Name

string

param Name

[REQUIRED]

The name of the Systems Manager document.

type DocumentVersion

string

param DocumentVersion

The document version you want to associate with the target(s). Can be a specific version or the default version.

type InstanceId

string

param InstanceId

The instance ID.

type Parameters

dict

param Parameters

The parameters for the documents runtime configuration.

  • (string) --

    • (list) --

      • (string) --

type Targets

list

param Targets

The targets (either instances or tags) for the association.

  • (dict) --

    An array of search criteria that targets instances using a Key,Value combination that you specify. Targets is required if you don't provide one or more instance IDs in the call.

    • Key (string) --

      User-defined criteria for sending commands that target instances that meet the criteria. Key can be tag:<Amazon EC2 tag> or InstanceIds. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

    • Values (list) --

      User-defined criteria that maps to Key. For example, if you specified tag:ServerRole, you could specify value:WebServer to execute a command on instances that include Amazon EC2 tags of ServerRole,WebServer. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

      • (string) --

type ScheduleExpression

string

param ScheduleExpression

A cron expression when the association will be applied to the target(s).

type OutputLocation

dict

param OutputLocation

An Amazon S3 bucket where you want to store the output details of the request.

  • S3Location (dict) --

    An Amazon S3 bucket where you want to store the results of this request.

    • OutputS3Region (string) --

      (Deprecated) You can no longer specify this parameter. The system ignores it. Instead, Systems Manager automatically determines the Amazon S3 bucket region.

    • OutputS3BucketName (string) --

      The name of the Amazon S3 bucket.

    • OutputS3KeyPrefix (string) --

      The Amazon S3 bucket subfolder.

type AssociationName

string

param AssociationName

Specify a descriptive name for the association.

rtype

dict

returns

Response Syntax

{
    'AssociationDescription': {
        'Name': 'string',
        'InstanceId': 'string',
        'AssociationVersion': 'string',
        'Date': datetime(2015, 1, 1),
        'LastUpdateAssociationDate': datetime(2015, 1, 1),
        'Status': {
            'Date': datetime(2015, 1, 1),
            'Name': 'Pending'|'Success'|'Failed',
            'Message': 'string',
            'AdditionalInfo': 'string'
        },
        'Overview': {
            'Status': 'string',
            'DetailedStatus': 'string',
            'AssociationStatusAggregatedCount': {
                'string': 123
            }
        },
        'DocumentVersion': 'string',
        'Parameters': {
            'string': [
                'string',
            ]
        },
        'AssociationId': 'string',
        'Targets': [
            {
                'Key': 'string',
                'Values': [
                    'string',
                ]
            },
        ],
        'ScheduleExpression': 'string',
        'OutputLocation': {
            'S3Location': {
                'OutputS3Region': 'string',
                'OutputS3BucketName': 'string',
                'OutputS3KeyPrefix': 'string'
            }
        },
        'LastExecutionDate': datetime(2015, 1, 1),
        'LastSuccessfulExecutionDate': datetime(2015, 1, 1),
        'AssociationName': 'string'
    }
}

Response Structure

  • (dict) --

    • AssociationDescription (dict) --

      Information about the association.

      • Name (string) --

        The name of the SSM document.

      • InstanceId (string) --

        The ID of the instance.

      • AssociationVersion (string) --

        The association version.

      • Date (datetime) --

        The date when the association was made.

      • LastUpdateAssociationDate (datetime) --

        The date when the association was last updated.

      • Status (dict) --

        The association status.

        • Date (datetime) --

          The date when the status changed.

        • Name (string) --

          The status.

        • Message (string) --

          The reason for the status.

        • AdditionalInfo (string) --

          A user-defined string.

      • Overview (dict) --

        Information about the association.

        • Status (string) --

          The status of the association. Status can be: Pending, Success, or Failed.

        • DetailedStatus (string) --

          A detailed status of the association.

        • AssociationStatusAggregatedCount (dict) --

          Returns the number of targets for the association status. For example, if you created an association with two instances, and one of them was successful, this would return the count of instances by status.

          • (string) --

            • (integer) --

      • DocumentVersion (string) --

        The document version.

      • Parameters (dict) --

        A description of the parameters for a document.

        • (string) --

          • (list) --

            • (string) --

      • AssociationId (string) --

        The association ID.

      • Targets (list) --

        The instances targeted by the request.

        • (dict) --

          An array of search criteria that targets instances using a Key,Value combination that you specify. Targets is required if you don't provide one or more instance IDs in the call.

          • Key (string) --

            User-defined criteria for sending commands that target instances that meet the criteria. Key can be tag:<Amazon EC2 tag> or InstanceIds. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

          • Values (list) --

            User-defined criteria that maps to Key. For example, if you specified tag:ServerRole, you could specify value:WebServer to execute a command on instances that include Amazon EC2 tags of ServerRole,WebServer. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

            • (string) --

      • ScheduleExpression (string) --

        A cron expression that specifies a schedule when the association runs.

      • OutputLocation (dict) --

        An Amazon S3 bucket where you want to store the output details of the request.

        • S3Location (dict) --

          An Amazon S3 bucket where you want to store the results of this request.

          • OutputS3Region (string) --

            (Deprecated) You can no longer specify this parameter. The system ignores it. Instead, Systems Manager automatically determines the Amazon S3 bucket region.

          • OutputS3BucketName (string) --

            The name of the Amazon S3 bucket.

          • OutputS3KeyPrefix (string) --

            The Amazon S3 bucket subfolder.

      • LastExecutionDate (datetime) --

        The date on which the association was last run.

      • LastSuccessfulExecutionDate (datetime) --

        The last date on which the association was successfully run.

      • AssociationName (string) --

        The association name.

CreateAssociationBatch (updated) Link ¶
Changes (request, response)
Request
{'Entries': {'AssociationName': 'string'}}
Response
{'Failed': {'Entry': {'AssociationName': 'string'}},
 'Successful': {'AssociationName': 'string', 'AssociationVersion': 'string'}}

Associates the specified Systems Manager document with the specified instances or targets.

When you associate a document with one or more instances using instance IDs or tags, the SSM Agent running on the instance processes the document and configures the instance as specified.

If you associate a document with an instance that already has an associated document, the system throws the AssociationAlreadyExists exception.

See also: AWS API Documentation

Request Syntax

client.create_association_batch(
    Entries=[
        {
            'Name': 'string',
            'InstanceId': 'string',
            'Parameters': {
                'string': [
                    'string',
                ]
            },
            'DocumentVersion': 'string',
            'Targets': [
                {
                    'Key': 'string',
                    'Values': [
                        'string',
                    ]
                },
            ],
            'ScheduleExpression': 'string',
            'OutputLocation': {
                'S3Location': {
                    'OutputS3Region': 'string',
                    'OutputS3BucketName': 'string',
                    'OutputS3KeyPrefix': 'string'
                }
            },
            'AssociationName': 'string'
        },
    ]
)
type Entries

list

param Entries

[REQUIRED]

One or more associations.

  • (dict) --

    Describes the association of a Systems Manager document and an instance.

    • Name (string) -- [REQUIRED]

      The name of the configuration document.

    • InstanceId (string) --

      The ID of the instance.

    • Parameters (dict) --

      A description of the parameters for a document.

      • (string) --

        • (list) --

          • (string) --

    • DocumentVersion (string) --

      The document version.

    • Targets (list) --

      The instances targeted by the request.

      • (dict) --

        An array of search criteria that targets instances using a Key,Value combination that you specify. Targets is required if you don't provide one or more instance IDs in the call.

        • Key (string) --

          User-defined criteria for sending commands that target instances that meet the criteria. Key can be tag:<Amazon EC2 tag> or InstanceIds. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

        • Values (list) --

          User-defined criteria that maps to Key. For example, if you specified tag:ServerRole, you could specify value:WebServer to execute a command on instances that include Amazon EC2 tags of ServerRole,WebServer. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

          • (string) --

    • ScheduleExpression (string) --

      A cron expression that specifies a schedule when the association runs.

    • OutputLocation (dict) --

      An Amazon S3 bucket where you want to store the results of this request.

      • S3Location (dict) --

        An Amazon S3 bucket where you want to store the results of this request.

        • OutputS3Region (string) --

          (Deprecated) You can no longer specify this parameter. The system ignores it. Instead, Systems Manager automatically determines the Amazon S3 bucket region.

        • OutputS3BucketName (string) --

          The name of the Amazon S3 bucket.

        • OutputS3KeyPrefix (string) --

          The Amazon S3 bucket subfolder.

    • AssociationName (string) --

      Specify a descriptive name for the association.

rtype

dict

returns

Response Syntax

{
    'Successful': [
        {
            'Name': 'string',
            'InstanceId': 'string',
            'AssociationVersion': 'string',
            'Date': datetime(2015, 1, 1),
            'LastUpdateAssociationDate': datetime(2015, 1, 1),
            'Status': {
                'Date': datetime(2015, 1, 1),
                'Name': 'Pending'|'Success'|'Failed',
                'Message': 'string',
                'AdditionalInfo': 'string'
            },
            'Overview': {
                'Status': 'string',
                'DetailedStatus': 'string',
                'AssociationStatusAggregatedCount': {
                    'string': 123
                }
            },
            'DocumentVersion': 'string',
            'Parameters': {
                'string': [
                    'string',
                ]
            },
            'AssociationId': 'string',
            'Targets': [
                {
                    'Key': 'string',
                    'Values': [
                        'string',
                    ]
                },
            ],
            'ScheduleExpression': 'string',
            'OutputLocation': {
                'S3Location': {
                    'OutputS3Region': 'string',
                    'OutputS3BucketName': 'string',
                    'OutputS3KeyPrefix': 'string'
                }
            },
            'LastExecutionDate': datetime(2015, 1, 1),
            'LastSuccessfulExecutionDate': datetime(2015, 1, 1),
            'AssociationName': 'string'
        },
    ],
    'Failed': [
        {
            'Entry': {
                'Name': 'string',
                'InstanceId': 'string',
                'Parameters': {
                    'string': [
                        'string',
                    ]
                },
                'DocumentVersion': 'string',
                'Targets': [
                    {
                        'Key': 'string',
                        'Values': [
                            'string',
                        ]
                    },
                ],
                'ScheduleExpression': 'string',
                'OutputLocation': {
                    'S3Location': {
                        'OutputS3Region': 'string',
                        'OutputS3BucketName': 'string',
                        'OutputS3KeyPrefix': 'string'
                    }
                },
                'AssociationName': 'string'
            },
            'Message': 'string',
            'Fault': 'Client'|'Server'|'Unknown'
        },
    ]
}

Response Structure

  • (dict) --

    • Successful (list) --

      Information about the associations that succeeded.

      • (dict) --

        Describes the parameters for a document.

        • Name (string) --

          The name of the SSM document.

        • InstanceId (string) --

          The ID of the instance.

        • AssociationVersion (string) --

          The association version.

        • Date (datetime) --

          The date when the association was made.

        • LastUpdateAssociationDate (datetime) --

          The date when the association was last updated.

        • Status (dict) --

          The association status.

          • Date (datetime) --

            The date when the status changed.

          • Name (string) --

            The status.

          • Message (string) --

            The reason for the status.

          • AdditionalInfo (string) --

            A user-defined string.

        • Overview (dict) --

          Information about the association.

          • Status (string) --

            The status of the association. Status can be: Pending, Success, or Failed.

          • DetailedStatus (string) --

            A detailed status of the association.

          • AssociationStatusAggregatedCount (dict) --

            Returns the number of targets for the association status. For example, if you created an association with two instances, and one of them was successful, this would return the count of instances by status.

            • (string) --

              • (integer) --

        • DocumentVersion (string) --

          The document version.

        • Parameters (dict) --

          A description of the parameters for a document.

          • (string) --

            • (list) --

              • (string) --

        • AssociationId (string) --

          The association ID.

        • Targets (list) --

          The instances targeted by the request.

          • (dict) --

            An array of search criteria that targets instances using a Key,Value combination that you specify. Targets is required if you don't provide one or more instance IDs in the call.

            • Key (string) --

              User-defined criteria for sending commands that target instances that meet the criteria. Key can be tag:<Amazon EC2 tag> or InstanceIds. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

            • Values (list) --

              User-defined criteria that maps to Key. For example, if you specified tag:ServerRole, you could specify value:WebServer to execute a command on instances that include Amazon EC2 tags of ServerRole,WebServer. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

              • (string) --

        • ScheduleExpression (string) --

          A cron expression that specifies a schedule when the association runs.

        • OutputLocation (dict) --

          An Amazon S3 bucket where you want to store the output details of the request.

          • S3Location (dict) --

            An Amazon S3 bucket where you want to store the results of this request.

            • OutputS3Region (string) --

              (Deprecated) You can no longer specify this parameter. The system ignores it. Instead, Systems Manager automatically determines the Amazon S3 bucket region.

            • OutputS3BucketName (string) --

              The name of the Amazon S3 bucket.

            • OutputS3KeyPrefix (string) --

              The Amazon S3 bucket subfolder.

        • LastExecutionDate (datetime) --

          The date on which the association was last run.

        • LastSuccessfulExecutionDate (datetime) --

          The last date on which the association was successfully run.

        • AssociationName (string) --

          The association name.

    • Failed (list) --

      Information about the associations that failed.

      • (dict) --

        Describes a failed association.

        • Entry (dict) --

          The association.

          • Name (string) --

            The name of the configuration document.

          • InstanceId (string) --

            The ID of the instance.

          • Parameters (dict) --

            A description of the parameters for a document.

            • (string) --

              • (list) --

                • (string) --

          • DocumentVersion (string) --

            The document version.

          • Targets (list) --

            The instances targeted by the request.

            • (dict) --

              An array of search criteria that targets instances using a Key,Value combination that you specify. Targets is required if you don't provide one or more instance IDs in the call.

              • Key (string) --

                User-defined criteria for sending commands that target instances that meet the criteria. Key can be tag:<Amazon EC2 tag> or InstanceIds. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

              • Values (list) --

                User-defined criteria that maps to Key. For example, if you specified tag:ServerRole, you could specify value:WebServer to execute a command on instances that include Amazon EC2 tags of ServerRole,WebServer. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

                • (string) --

          • ScheduleExpression (string) --

            A cron expression that specifies a schedule when the association runs.

          • OutputLocation (dict) --

            An Amazon S3 bucket where you want to store the results of this request.

            • S3Location (dict) --

              An Amazon S3 bucket where you want to store the results of this request.

              • OutputS3Region (string) --

                (Deprecated) You can no longer specify this parameter. The system ignores it. Instead, Systems Manager automatically determines the Amazon S3 bucket region.

              • OutputS3BucketName (string) --

                The name of the Amazon S3 bucket.

              • OutputS3KeyPrefix (string) --

                The Amazon S3 bucket subfolder.

          • AssociationName (string) --

            Specify a descriptive name for the association.

        • Message (string) --

          A description of the failure.

        • Fault (string) --

          The source of the failure.

DescribeAssociation (updated) Link ¶
Changes (request, response)
Request
{'AssociationVersion': 'string'}
Response
{'AssociationDescription': {'AssociationName': 'string',
                            'AssociationVersion': 'string'}}

Describes the associations for the specified Systems Manager document or instance.

See also: AWS API Documentation

Request Syntax

client.describe_association(
    Name='string',
    InstanceId='string',
    AssociationId='string',
    AssociationVersion='string'
)
type Name

string

param Name

The name of the SSM document.

type InstanceId

string

param InstanceId

The instance ID.

type AssociationId

string

param AssociationId

The association ID for which you want information.

type AssociationVersion

string

param AssociationVersion

Specify the association version to retrieve. To view the latest version, either specify $LATEST for this parameter, or omit this parameter. To view a list of all associations for an instance, use ListInstanceAssociations. To get a list of versions for a specific association, use ListAssociationVersions.

rtype

dict

returns

Response Syntax

{
    'AssociationDescription': {
        'Name': 'string',
        'InstanceId': 'string',
        'AssociationVersion': 'string',
        'Date': datetime(2015, 1, 1),
        'LastUpdateAssociationDate': datetime(2015, 1, 1),
        'Status': {
            'Date': datetime(2015, 1, 1),
            'Name': 'Pending'|'Success'|'Failed',
            'Message': 'string',
            'AdditionalInfo': 'string'
        },
        'Overview': {
            'Status': 'string',
            'DetailedStatus': 'string',
            'AssociationStatusAggregatedCount': {
                'string': 123
            }
        },
        'DocumentVersion': 'string',
        'Parameters': {
            'string': [
                'string',
            ]
        },
        'AssociationId': 'string',
        'Targets': [
            {
                'Key': 'string',
                'Values': [
                    'string',
                ]
            },
        ],
        'ScheduleExpression': 'string',
        'OutputLocation': {
            'S3Location': {
                'OutputS3Region': 'string',
                'OutputS3BucketName': 'string',
                'OutputS3KeyPrefix': 'string'
            }
        },
        'LastExecutionDate': datetime(2015, 1, 1),
        'LastSuccessfulExecutionDate': datetime(2015, 1, 1),
        'AssociationName': 'string'
    }
}

Response Structure

  • (dict) --

    • AssociationDescription (dict) --

      Information about the association.

      • Name (string) --

        The name of the SSM document.

      • InstanceId (string) --

        The ID of the instance.

      • AssociationVersion (string) --

        The association version.

      • Date (datetime) --

        The date when the association was made.

      • LastUpdateAssociationDate (datetime) --

        The date when the association was last updated.

      • Status (dict) --

        The association status.

        • Date (datetime) --

          The date when the status changed.

        • Name (string) --

          The status.

        • Message (string) --

          The reason for the status.

        • AdditionalInfo (string) --

          A user-defined string.

      • Overview (dict) --

        Information about the association.

        • Status (string) --

          The status of the association. Status can be: Pending, Success, or Failed.

        • DetailedStatus (string) --

          A detailed status of the association.

        • AssociationStatusAggregatedCount (dict) --

          Returns the number of targets for the association status. For example, if you created an association with two instances, and one of them was successful, this would return the count of instances by status.

          • (string) --

            • (integer) --

      • DocumentVersion (string) --

        The document version.

      • Parameters (dict) --

        A description of the parameters for a document.

        • (string) --

          • (list) --

            • (string) --

      • AssociationId (string) --

        The association ID.

      • Targets (list) --

        The instances targeted by the request.

        • (dict) --

          An array of search criteria that targets instances using a Key,Value combination that you specify. Targets is required if you don't provide one or more instance IDs in the call.

          • Key (string) --

            User-defined criteria for sending commands that target instances that meet the criteria. Key can be tag:<Amazon EC2 tag> or InstanceIds. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

          • Values (list) --

            User-defined criteria that maps to Key. For example, if you specified tag:ServerRole, you could specify value:WebServer to execute a command on instances that include Amazon EC2 tags of ServerRole,WebServer. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

            • (string) --

      • ScheduleExpression (string) --

        A cron expression that specifies a schedule when the association runs.

      • OutputLocation (dict) --

        An Amazon S3 bucket where you want to store the output details of the request.

        • S3Location (dict) --

          An Amazon S3 bucket where you want to store the results of this request.

          • OutputS3Region (string) --

            (Deprecated) You can no longer specify this parameter. The system ignores it. Instead, Systems Manager automatically determines the Amazon S3 bucket region.

          • OutputS3BucketName (string) --

            The name of the Amazon S3 bucket.

          • OutputS3KeyPrefix (string) --

            The Amazon S3 bucket subfolder.

      • LastExecutionDate (datetime) --

        The date on which the association was last run.

      • LastSuccessfulExecutionDate (datetime) --

        The last date on which the association was successfully run.

      • AssociationName (string) --

        The association name.

DescribeEffectiveInstanceAssociations (updated) Link ¶
Changes (response)
{'Associations': {'AssociationVersion': 'string'}}

All associations for the instance(s).

See also: AWS API Documentation

Request Syntax

client.describe_effective_instance_associations(
    InstanceId='string',
    MaxResults=123,
    NextToken='string'
)
type InstanceId

string

param InstanceId

[REQUIRED]

The instance ID for which you want to view all associations.

type MaxResults

integer

param MaxResults

The maximum number of items to return for this call. The call also returns a token that you can specify in a subsequent call to get the next set of results.

type NextToken

string

param NextToken

The token for the next set of items to return. (You received this token from a previous call.)

rtype

dict

returns

Response Syntax

{
    'Associations': [
        {
            'AssociationId': 'string',
            'InstanceId': 'string',
            'Content': 'string',
            'AssociationVersion': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • Associations (list) --

      The associations for the requested instance.

      • (dict) --

        One or more association documents on the instance.

        • AssociationId (string) --

          The association ID.

        • InstanceId (string) --

          The instance ID.

        • Content (string) --

          The content of the association document for the instance(s).

        • AssociationVersion (string) --

          Version information for the association on the instance.

    • NextToken (string) --

      The token to use when requesting the next set of items. If there are no additional items to return, the string is empty.

DescribeInstanceAssociationsStatus (updated) Link ¶
Changes (response)
{'InstanceAssociationStatusInfos': {'AssociationName': 'string',
                                    'AssociationVersion': 'string'}}

The status of the associations for the instance(s).

See also: AWS API Documentation

Request Syntax

client.describe_instance_associations_status(
    InstanceId='string',
    MaxResults=123,
    NextToken='string'
)
type InstanceId

string

param InstanceId

[REQUIRED]

The instance IDs for which you want association status information.

type MaxResults

integer

param MaxResults

The maximum number of items to return for this call. The call also returns a token that you can specify in a subsequent call to get the next set of results.

type NextToken

string

param NextToken

The token for the next set of items to return. (You received this token from a previous call.)

rtype

dict

returns

Response Syntax

{
    'InstanceAssociationStatusInfos': [
        {
            'AssociationId': 'string',
            'Name': 'string',
            'DocumentVersion': 'string',
            'AssociationVersion': 'string',
            'InstanceId': 'string',
            'ExecutionDate': datetime(2015, 1, 1),
            'Status': 'string',
            'DetailedStatus': 'string',
            'ExecutionSummary': 'string',
            'ErrorCode': 'string',
            'OutputUrl': {
                'S3OutputUrl': {
                    'OutputUrl': 'string'
                }
            },
            'AssociationName': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • InstanceAssociationStatusInfos (list) --

      Status information about the association.

      • (dict) --

        Status information about the instance association.

        • AssociationId (string) --

          The association ID.

        • Name (string) --

          The name of the association.

        • DocumentVersion (string) --

          The association document verions.

        • AssociationVersion (string) --

          The version of the association applied to the instance.

        • InstanceId (string) --

          The instance ID where the association was created.

        • ExecutionDate (datetime) --

          The date the instance association executed.

        • Status (string) --

          Status information about the instance association.

        • DetailedStatus (string) --

          Detailed status information about the instance association.

        • ExecutionSummary (string) --

          Summary information about association execution.

        • ErrorCode (string) --

          An error code returned by the request to create the association.

        • OutputUrl (dict) --

          A URL for an Amazon S3 bucket where you want to store the results of this request.

          • S3OutputUrl (dict) --

            The URL of Amazon S3 bucket where you want to store the results of this request.

            • OutputUrl (string) --

              A URL for an Amazon S3 bucket where you want to store the results of this request.

        • AssociationName (string) --

          The name of the association applied to the instance.

    • NextToken (string) --

      The token to use when requesting the next set of items. If there are no additional items to return, the string is empty.

ListAssociations (updated) Link ¶
Changes (request, response)
Request
{'AssociationFilterList': {'key': ['AssociationName']}}
Response
{'Associations': {'AssociationName': 'string', 'AssociationVersion': 'string'}}

Lists the associations for the specified Systems Manager document or instance.

See also: AWS API Documentation

Request Syntax

client.list_associations(
    AssociationFilterList=[
        {
            'key': 'InstanceId'|'Name'|'AssociationId'|'AssociationStatusName'|'LastExecutedBefore'|'LastExecutedAfter'|'AssociationName',
            'value': 'string'
        },
    ],
    MaxResults=123,
    NextToken='string'
)
type AssociationFilterList

list

param AssociationFilterList

One or more filters. Use a filter to return a more specific list of results.

  • (dict) --

    Describes a filter.

    • key (string) -- [REQUIRED]

      The name of the filter.

    • value (string) -- [REQUIRED]

      The filter value.

type MaxResults

integer

param MaxResults

The maximum number of items to return for this call. The call also returns a token that you can specify in a subsequent call to get the next set of results.

type NextToken

string

param NextToken

The token for the next set of items to return. (You received this token from a previous call.)

rtype

dict

returns

Response Syntax

{
    'Associations': [
        {
            'Name': 'string',
            'InstanceId': 'string',
            'AssociationId': 'string',
            'AssociationVersion': 'string',
            'DocumentVersion': 'string',
            'Targets': [
                {
                    'Key': 'string',
                    'Values': [
                        'string',
                    ]
                },
            ],
            'LastExecutionDate': datetime(2015, 1, 1),
            'Overview': {
                'Status': 'string',
                'DetailedStatus': 'string',
                'AssociationStatusAggregatedCount': {
                    'string': 123
                }
            },
            'ScheduleExpression': 'string',
            'AssociationName': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • Associations (list) --

      The associations.

      • (dict) --

        Describes an association of a Systems Manager document and an instance.

        • Name (string) --

          The name of the SSM document.

        • InstanceId (string) --

          The ID of the instance.

        • AssociationId (string) --

          The ID created by the system when you create an association. An association is a binding between a document and a set of targets with a schedule.

        • AssociationVersion (string) --

          The association version.

        • DocumentVersion (string) --

          The version of the document used in the association.

        • Targets (list) --

          The instances targeted by the request to create an association.

          • (dict) --

            An array of search criteria that targets instances using a Key,Value combination that you specify. Targets is required if you don't provide one or more instance IDs in the call.

            • Key (string) --

              User-defined criteria for sending commands that target instances that meet the criteria. Key can be tag:<Amazon EC2 tag> or InstanceIds. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

            • Values (list) --

              User-defined criteria that maps to Key. For example, if you specified tag:ServerRole, you could specify value:WebServer to execute a command on instances that include Amazon EC2 tags of ServerRole,WebServer. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

              • (string) --

        • LastExecutionDate (datetime) --

          The date on which the association was last run.

        • Overview (dict) --

          Information about the association.

          • Status (string) --

            The status of the association. Status can be: Pending, Success, or Failed.

          • DetailedStatus (string) --

            A detailed status of the association.

          • AssociationStatusAggregatedCount (dict) --

            Returns the number of targets for the association status. For example, if you created an association with two instances, and one of them was successful, this would return the count of instances by status.

            • (string) --

              • (integer) --

        • ScheduleExpression (string) --

          A cron expression that specifies a schedule when the association runs.

        • AssociationName (string) --

          The association name.

    • NextToken (string) --

      The token to use when requesting the next set of items. If there are no additional items to return, the string is empty.

UpdateAssociation (updated) Link ¶
Changes (request, response)
Request
{'AssociationName': 'string', 'AssociationVersion': 'string'}
Response
{'AssociationDescription': {'AssociationName': 'string',
                            'AssociationVersion': 'string'}}

Updates an association. You can update the association name and version, the document version, schedule, parameters, and Amazon S3 output.

See also: AWS API Documentation

Request Syntax

client.update_association(
    AssociationId='string',
    Parameters={
        'string': [
            'string',
        ]
    },
    DocumentVersion='string',
    ScheduleExpression='string',
    OutputLocation={
        'S3Location': {
            'OutputS3Region': 'string',
            'OutputS3BucketName': 'string',
            'OutputS3KeyPrefix': 'string'
        }
    },
    Name='string',
    Targets=[
        {
            'Key': 'string',
            'Values': [
                'string',
            ]
        },
    ],
    AssociationName='string',
    AssociationVersion='string'
)
type AssociationId

string

param AssociationId

[REQUIRED]

The ID of the association you want to update.

type Parameters

dict

param Parameters

The parameters you want to update for the association. If you create a parameter using Parameter Store, you can reference the parameter using {{ssm:parameter-name}}

  • (string) --

    • (list) --

      • (string) --

type DocumentVersion

string

param DocumentVersion

The document version you want update for the association.

type ScheduleExpression

string

param ScheduleExpression

The cron expression used to schedule the association that you want to update.

type OutputLocation

dict

param OutputLocation

An Amazon S3 bucket where you want to store the results of this request.

  • S3Location (dict) --

    An Amazon S3 bucket where you want to store the results of this request.

    • OutputS3Region (string) --

      (Deprecated) You can no longer specify this parameter. The system ignores it. Instead, Systems Manager automatically determines the Amazon S3 bucket region.

    • OutputS3BucketName (string) --

      The name of the Amazon S3 bucket.

    • OutputS3KeyPrefix (string) --

      The Amazon S3 bucket subfolder.

type Name

string

param Name

The name of the association document.

type Targets

list

param Targets

The targets of the association.

  • (dict) --

    An array of search criteria that targets instances using a Key,Value combination that you specify. Targets is required if you don't provide one or more instance IDs in the call.

    • Key (string) --

      User-defined criteria for sending commands that target instances that meet the criteria. Key can be tag:<Amazon EC2 tag> or InstanceIds. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

    • Values (list) --

      User-defined criteria that maps to Key. For example, if you specified tag:ServerRole, you could specify value:WebServer to execute a command on instances that include Amazon EC2 tags of ServerRole,WebServer. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

      • (string) --

type AssociationName

string

param AssociationName

The name of the association that you want to update.

type AssociationVersion

string

param AssociationVersion

This parameter is provided for concurrency control purposes. You must specify the latest association version in the service. If you want to ensure that this request succeeds, either specify $LATEST , or omit this parameter.

rtype

dict

returns

Response Syntax

{
    'AssociationDescription': {
        'Name': 'string',
        'InstanceId': 'string',
        'AssociationVersion': 'string',
        'Date': datetime(2015, 1, 1),
        'LastUpdateAssociationDate': datetime(2015, 1, 1),
        'Status': {
            'Date': datetime(2015, 1, 1),
            'Name': 'Pending'|'Success'|'Failed',
            'Message': 'string',
            'AdditionalInfo': 'string'
        },
        'Overview': {
            'Status': 'string',
            'DetailedStatus': 'string',
            'AssociationStatusAggregatedCount': {
                'string': 123
            }
        },
        'DocumentVersion': 'string',
        'Parameters': {
            'string': [
                'string',
            ]
        },
        'AssociationId': 'string',
        'Targets': [
            {
                'Key': 'string',
                'Values': [
                    'string',
                ]
            },
        ],
        'ScheduleExpression': 'string',
        'OutputLocation': {
            'S3Location': {
                'OutputS3Region': 'string',
                'OutputS3BucketName': 'string',
                'OutputS3KeyPrefix': 'string'
            }
        },
        'LastExecutionDate': datetime(2015, 1, 1),
        'LastSuccessfulExecutionDate': datetime(2015, 1, 1),
        'AssociationName': 'string'
    }
}

Response Structure

  • (dict) --

    • AssociationDescription (dict) --

      The description of the association that was updated.

      • Name (string) --

        The name of the SSM document.

      • InstanceId (string) --

        The ID of the instance.

      • AssociationVersion (string) --

        The association version.

      • Date (datetime) --

        The date when the association was made.

      • LastUpdateAssociationDate (datetime) --

        The date when the association was last updated.

      • Status (dict) --

        The association status.

        • Date (datetime) --

          The date when the status changed.

        • Name (string) --

          The status.

        • Message (string) --

          The reason for the status.

        • AdditionalInfo (string) --

          A user-defined string.

      • Overview (dict) --

        Information about the association.

        • Status (string) --

          The status of the association. Status can be: Pending, Success, or Failed.

        • DetailedStatus (string) --

          A detailed status of the association.

        • AssociationStatusAggregatedCount (dict) --

          Returns the number of targets for the association status. For example, if you created an association with two instances, and one of them was successful, this would return the count of instances by status.

          • (string) --

            • (integer) --

      • DocumentVersion (string) --

        The document version.

      • Parameters (dict) --

        A description of the parameters for a document.

        • (string) --

          • (list) --

            • (string) --

      • AssociationId (string) --

        The association ID.

      • Targets (list) --

        The instances targeted by the request.

        • (dict) --

          An array of search criteria that targets instances using a Key,Value combination that you specify. Targets is required if you don't provide one or more instance IDs in the call.

          • Key (string) --

            User-defined criteria for sending commands that target instances that meet the criteria. Key can be tag:<Amazon EC2 tag> or InstanceIds. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

          • Values (list) --

            User-defined criteria that maps to Key. For example, if you specified tag:ServerRole, you could specify value:WebServer to execute a command on instances that include Amazon EC2 tags of ServerRole,WebServer. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

            • (string) --

      • ScheduleExpression (string) --

        A cron expression that specifies a schedule when the association runs.

      • OutputLocation (dict) --

        An Amazon S3 bucket where you want to store the output details of the request.

        • S3Location (dict) --

          An Amazon S3 bucket where you want to store the results of this request.

          • OutputS3Region (string) --

            (Deprecated) You can no longer specify this parameter. The system ignores it. Instead, Systems Manager automatically determines the Amazon S3 bucket region.

          • OutputS3BucketName (string) --

            The name of the Amazon S3 bucket.

          • OutputS3KeyPrefix (string) --

            The Amazon S3 bucket subfolder.

      • LastExecutionDate (datetime) --

        The date on which the association was last run.

      • LastSuccessfulExecutionDate (datetime) --

        The last date on which the association was successfully run.

      • AssociationName (string) --

        The association name.

UpdateAssociationStatus (updated) Link ¶
Changes (response)
{'AssociationDescription': {'AssociationName': 'string',
                            'AssociationVersion': 'string'}}

Updates the status of the Systems Manager document associated with the specified instance.

See also: AWS API Documentation

Request Syntax

client.update_association_status(
    Name='string',
    InstanceId='string',
    AssociationStatus={
        'Date': datetime(2015, 1, 1),
        'Name': 'Pending'|'Success'|'Failed',
        'Message': 'string',
        'AdditionalInfo': 'string'
    }
)
type Name

string

param Name

[REQUIRED]

The name of the SSM document.

type InstanceId

string

param InstanceId

[REQUIRED]

The ID of the instance.

type AssociationStatus

dict

param AssociationStatus

[REQUIRED]

The association status.

  • Date (datetime) -- [REQUIRED]

    The date when the status changed.

  • Name (string) -- [REQUIRED]

    The status.

  • Message (string) -- [REQUIRED]

    The reason for the status.

  • AdditionalInfo (string) --

    A user-defined string.

rtype

dict

returns

Response Syntax

{
    'AssociationDescription': {
        'Name': 'string',
        'InstanceId': 'string',
        'AssociationVersion': 'string',
        'Date': datetime(2015, 1, 1),
        'LastUpdateAssociationDate': datetime(2015, 1, 1),
        'Status': {
            'Date': datetime(2015, 1, 1),
            'Name': 'Pending'|'Success'|'Failed',
            'Message': 'string',
            'AdditionalInfo': 'string'
        },
        'Overview': {
            'Status': 'string',
            'DetailedStatus': 'string',
            'AssociationStatusAggregatedCount': {
                'string': 123
            }
        },
        'DocumentVersion': 'string',
        'Parameters': {
            'string': [
                'string',
            ]
        },
        'AssociationId': 'string',
        'Targets': [
            {
                'Key': 'string',
                'Values': [
                    'string',
                ]
            },
        ],
        'ScheduleExpression': 'string',
        'OutputLocation': {
            'S3Location': {
                'OutputS3Region': 'string',
                'OutputS3BucketName': 'string',
                'OutputS3KeyPrefix': 'string'
            }
        },
        'LastExecutionDate': datetime(2015, 1, 1),
        'LastSuccessfulExecutionDate': datetime(2015, 1, 1),
        'AssociationName': 'string'
    }
}

Response Structure

  • (dict) --

    • AssociationDescription (dict) --

      Information about the association.

      • Name (string) --

        The name of the SSM document.

      • InstanceId (string) --

        The ID of the instance.

      • AssociationVersion (string) --

        The association version.

      • Date (datetime) --

        The date when the association was made.

      • LastUpdateAssociationDate (datetime) --

        The date when the association was last updated.

      • Status (dict) --

        The association status.

        • Date (datetime) --

          The date when the status changed.

        • Name (string) --

          The status.

        • Message (string) --

          The reason for the status.

        • AdditionalInfo (string) --

          A user-defined string.

      • Overview (dict) --

        Information about the association.

        • Status (string) --

          The status of the association. Status can be: Pending, Success, or Failed.

        • DetailedStatus (string) --

          A detailed status of the association.

        • AssociationStatusAggregatedCount (dict) --

          Returns the number of targets for the association status. For example, if you created an association with two instances, and one of them was successful, this would return the count of instances by status.

          • (string) --

            • (integer) --

      • DocumentVersion (string) --

        The document version.

      • Parameters (dict) --

        A description of the parameters for a document.

        • (string) --

          • (list) --

            • (string) --

      • AssociationId (string) --

        The association ID.

      • Targets (list) --

        The instances targeted by the request.

        • (dict) --

          An array of search criteria that targets instances using a Key,Value combination that you specify. Targets is required if you don't provide one or more instance IDs in the call.

          • Key (string) --

            User-defined criteria for sending commands that target instances that meet the criteria. Key can be tag:<Amazon EC2 tag> or InstanceIds. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

          • Values (list) --

            User-defined criteria that maps to Key. For example, if you specified tag:ServerRole, you could specify value:WebServer to execute a command on instances that include Amazon EC2 tags of ServerRole,WebServer. For more information about how to send commands that target instances using Key,Value parameters, see Executing a Command Using Systems Manager Run Command .

            • (string) --

      • ScheduleExpression (string) --

        A cron expression that specifies a schedule when the association runs.

      • OutputLocation (dict) --

        An Amazon S3 bucket where you want to store the output details of the request.

        • S3Location (dict) --

          An Amazon S3 bucket where you want to store the results of this request.

          • OutputS3Region (string) --

            (Deprecated) You can no longer specify this parameter. The system ignores it. Instead, Systems Manager automatically determines the Amazon S3 bucket region.

          • OutputS3BucketName (string) --

            The name of the Amazon S3 bucket.

          • OutputS3KeyPrefix (string) --

            The Amazon S3 bucket subfolder.

      • LastExecutionDate (datetime) --

        The date on which the association was last run.

      • LastSuccessfulExecutionDate (datetime) --

        The last date on which the association was successfully run.

      • AssociationName (string) --

        The association name.