AWS API Changes

2019/07/23 - Amazon Simple Systems Manager (SSM) - 4 updated api methods

Changes You can now use Maintenance Windows to select a resource group as the target. By selecting a resource group as the target of a Maintenance Window, customers can perform routine tasks across different resources such as Amazon Elastic Compute Cloud (AmazonEC2) instances, Amazon Elastic Block Store (Amazon EBS) volumes, and Amazon Simple Storage Service(Amazon S3) buckets within the same recurring time window.

DescribeMaintenanceWindowSchedule (updated)

Link ¶
Changes (request)

{'ResourceType': ['RESOURCE_GROUP']}

Retrieves information about upcoming executions of a maintenance window.

See also: AWS API Documentation

Request Syntax

client.describe_maintenance_window_schedule(
    WindowId='string',
    Targets=[
        {
            'Key': 'string',
            'Values': [
                'string',
            ]
        },
    ],
    ResourceType='INSTANCE'|'RESOURCE_GROUP',
    Filters=[
        {
            'Key': 'string',
            'Values': [
                'string',
            ]
        },
    ],
    MaxResults=123,
    NextToken='string'
)

type WindowId

string

param WindowId

The ID of the maintenance window to retrieve information about.

type Targets

list

param Targets

The instance ID or key/value pair to retrieve information about.

(dict) --

An array of search criteria that targets instances using a Key,Value combination that you specify.

Supported formats include the following.
- ``Key=InstanceIds,Values=*instance-id-1* ,*instance-id-2* ,*instance-id-3* ``
- ``Key=tag:my-tag-key ,Values=*my-tag-value-1* ,*my-tag-value-2* ``
- ``Key=tag-key,Values=*my-tag-key-1* ,*my-tag-key-2* ``
- (Maintenance window targets only) ``Key=resource-groups:Name,Values=*resource-group-name* ``
- (Maintenance window targets only) ``Key=resource-groups:ResourceTypeFilters,Values=*resource-type-1* ,*resource-type-2* ``
For example:
- Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE,i-07782c72faEXAMPLE
- Key=tag:CostCenter,Values=CostCenter1,CostCenter2,CostCenter3
- Key=tag-key,Values=Name,Instance-Type,CostCenter
- (Maintenance window targets only) Key=resource-groups:Name,Values=ProductionResourceGroup
- (Maintenance window targets only) ``Key=resource-groups:ResourceTypeFilters,Values=*AWS::EC2::INSTANCE* ,*AWS::EC2::VPC* ``
For information about how to send commands that target instances using Key,Value parameters, see Using Targets and Rate Controls to Send Commands to a Fleet in the AWS Systems Manager User Guide .
- Key (string) --
  
  User-defined criteria for sending commands that target instances that meet the criteria.
- Values (list) --
  
  User-defined criteria that maps to Key . For example, if you specified tag:ServerRole , you could specify value:WebServer to run a command on instances that include Amazon EC2 tags of ServerRole,WebServer .
  - (string) --

type ResourceType

string

param ResourceType

The type of resource you want to retrieve information about. For example, "INSTANCE".

type Filters

list

param Filters

Filters used to limit the range of results. For example, you can limit maintenance window executions to only those scheduled before or after a certain date and time.

(dict) --

Defines a filter used in Patch Manager APIs.
- Key (string) --
  
  The key for the filter.
- Values (list) --
  
  The value for the filter.
  - (string) --

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

{
    'ScheduledWindowExecutions': [
        {
            'WindowId': 'string',
            'Name': 'string',
            'ExecutionTime': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

(dict) --
- ScheduledWindowExecutions (list) --
  
  Information about maintenance window executions scheduled for the specified time range.
  - (dict) --
    
    Information about a scheduled execution for a maintenance window.
    - WindowId (string) --
      
      The ID of the maintenance window to be run.
    - Name (string) --
      
      The name of the maintenance window to be run.
    - ExecutionTime (string) --
      
      The time, in ISO-8601 Extended format, that the maintenance window is scheduled to be run.
- NextToken (string) --
  
  The token for the next set of items to return. (You use this token in the next call.)

DescribeMaintenanceWindowTargets (updated)

Link ¶
Changes (response)

{'Targets': {'ResourceType': ['RESOURCE_GROUP']}}

Lists the targets registered with the maintenance window.

See also: AWS API Documentation

Request Syntax

client.describe_maintenance_window_targets(
    WindowId='string',
    Filters=[
        {
            'Key': 'string',
            'Values': [
                'string',
            ]
        },
    ],
    MaxResults=123,
    NextToken='string'
)

type WindowId

string

param WindowId

[REQUIRED]

The ID of the maintenance window whose targets should be retrieved.

type Filters

list

param Filters

Optional filters that can be used to narrow down the scope of the returned window targets. The supported filter keys are Type, WindowTargetId and OwnerInformation.

(dict) --

Filter used in the request. Supported filter keys are Name and Enabled.
- Key (string) --
  
  The name of the filter.
- Values (list) --
  
  The filter values.
  - (string) --

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

{
    'Targets': [
        {
            'WindowId': 'string',
            'WindowTargetId': 'string',
            'ResourceType': 'INSTANCE'|'RESOURCE_GROUP',
            'Targets': [
                {
                    'Key': 'string',
                    'Values': [
                        'string',
                    ]
                },
            ],
            'OwnerInformation': 'string',
            'Name': 'string',
            'Description': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

(dict) --
- Targets (list) --
  
  Information about the targets in the maintenance window.
  - (dict) --
    
    The target registered with the maintenance window.
    - WindowId (string) --
      
      The ID of the maintenance window to register the target with.
    - WindowTargetId (string) --
      
      The ID of the target.
    - ResourceType (string) --
      
      The type of target that is being registered with the maintenance window.
    - Targets (list) --
      
      The targets, either instances or tags.
      
      Specify instances using the following format:
      
      Key=instanceids,Values=<instanceid1>,<instanceid2>
      
      Tags are specified using the following format:
      
      Key=<tag name>,Values=<tag value> .
      - (dict) --
        
        An array of search criteria that targets instances using a Key,Value combination that you specify.
        
        Supported formats include the following.
        
        ``Key=InstanceIds,Values=*instance-id-1* ,*instance-id-2* ,*instance-id-3* ``
        
        ``Key=tag:my-tag-key ,Values=*my-tag-value-1* ,*my-tag-value-2* ``
        
        ``Key=tag-key,Values=*my-tag-key-1* ,*my-tag-key-2* ``
        
        (Maintenance window targets only) ``Key=resource-groups:Name,Values=*resource-group-name* ``
        
        (Maintenance window targets only) ``Key=resource-groups:ResourceTypeFilters,Values=*resource-type-1* ,*resource-type-2* ``
        
        For example:
        
        Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE,i-07782c72faEXAMPLE
        
        Key=tag:CostCenter,Values=CostCenter1,CostCenter2,CostCenter3
        
        Key=tag-key,Values=Name,Instance-Type,CostCenter
        
        (Maintenance window targets only) Key=resource-groups:Name,Values=ProductionResourceGroup
        
        (Maintenance window targets only) ``Key=resource-groups:ResourceTypeFilters,Values=*AWS::EC2::INSTANCE* ,*AWS::EC2::VPC* ``
        
        For information about how to send commands that target instances using Key,Value parameters, see Using Targets and Rate Controls to Send Commands to a Fleet in the AWS Systems Manager User Guide .
        
        Key (string) --
        
        User-defined criteria for sending commands that target instances that meet the criteria.
        
        Values (list) --
        
        User-defined criteria that maps to Key . For example, if you specified tag:ServerRole , you could specify value:WebServer to run a command on instances that include Amazon EC2 tags of ServerRole,WebServer .
        
        (string) --
    - OwnerInformation (string) --
      
      A user-provided value that will be included in any CloudWatch events that are raised while running tasks for these targets in this maintenance window.
    - Name (string) --
      
      The name for the maintenance window target.
    - Description (string) --
      
      A description for the target.
- 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.

DescribeMaintenanceWindowsForTarget (updated)

Link ¶
Changes (request)

{'ResourceType': ['RESOURCE_GROUP']}

Retrieves information about the maintenance window targets or tasks that an instance is associated with.

See also: AWS API Documentation

Request Syntax

client.describe_maintenance_windows_for_target(
    Targets=[
        {
            'Key': 'string',
            'Values': [
                'string',
            ]
        },
    ],
    ResourceType='INSTANCE'|'RESOURCE_GROUP',
    MaxResults=123,
    NextToken='string'
)

type Targets

list

param Targets

[REQUIRED]

The instance ID or key/value pair to retrieve information about.

(dict) --

An array of search criteria that targets instances using a Key,Value combination that you specify.

Supported formats include the following.
- ``Key=InstanceIds,Values=*instance-id-1* ,*instance-id-2* ,*instance-id-3* ``
- ``Key=tag:my-tag-key ,Values=*my-tag-value-1* ,*my-tag-value-2* ``
- ``Key=tag-key,Values=*my-tag-key-1* ,*my-tag-key-2* ``
- (Maintenance window targets only) ``Key=resource-groups:Name,Values=*resource-group-name* ``
- (Maintenance window targets only) ``Key=resource-groups:ResourceTypeFilters,Values=*resource-type-1* ,*resource-type-2* ``
For example:
- Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE,i-07782c72faEXAMPLE
- Key=tag:CostCenter,Values=CostCenter1,CostCenter2,CostCenter3
- Key=tag-key,Values=Name,Instance-Type,CostCenter
- (Maintenance window targets only) Key=resource-groups:Name,Values=ProductionResourceGroup
- (Maintenance window targets only) ``Key=resource-groups:ResourceTypeFilters,Values=*AWS::EC2::INSTANCE* ,*AWS::EC2::VPC* ``
For information about how to send commands that target instances using Key,Value parameters, see Using Targets and Rate Controls to Send Commands to a Fleet in the AWS Systems Manager User Guide .
- Key (string) --
  
  User-defined criteria for sending commands that target instances that meet the criteria.
- Values (list) --
  
  User-defined criteria that maps to Key . For example, if you specified tag:ServerRole , you could specify value:WebServer to run a command on instances that include Amazon EC2 tags of ServerRole,WebServer .
  - (string) --

type ResourceType

string

param ResourceType

[REQUIRED]

The type of resource you want to retrieve information about. For example, "INSTANCE".

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

{
    'WindowIdentities': [
        {
            'WindowId': 'string',
            'Name': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

(dict) --
- WindowIdentities (list) --
  
  Information about the maintenance window targets and tasks an instance is associated with.
  - (dict) --
    
    The maintenance window to which the specified target belongs.
    - WindowId (string) --
      
      The ID of the maintenance window.
    - Name (string) --
      
      The name of the maintenance window.
- NextToken (string) --
  
  The token for the next set of items to return. (You use this token in the next call.)

RegisterTargetWithMaintenanceWindow (updated)

Link ¶
Changes (request)

{'ResourceType': ['RESOURCE_GROUP']}

Registers a target with a maintenance window.

See also: AWS API Documentation

Request Syntax

client.register_target_with_maintenance_window(
    WindowId='string',
    ResourceType='INSTANCE'|'RESOURCE_GROUP',
    Targets=[
        {
            'Key': 'string',
            'Values': [
                'string',
            ]
        },
    ],
    OwnerInformation='string',
    Name='string',
    Description='string',
    ClientToken='string'
)

type WindowId

string

param WindowId

[REQUIRED]

The ID of the maintenance window the target should be registered with.

type ResourceType

string

param ResourceType

[REQUIRED]

The type of target being registered with the maintenance window.

type Targets

list

param Targets

[REQUIRED]

The targets to register with the maintenance window. In other words, the instances to run commands on when the maintenance window runs.

You can specify targets using instance IDs, resource group names, or tags that have been applied to instances.

Example 1 : Specify instance IDs

``Key=InstanceIds,Values=*instance-id-1* ,*instance-id-2* ,*instance-id-3* ``

Example 2 : Use tag key-pairs applied to instances

``Key=tag:my-tag-key ,Values=*my-tag-value-1* ,*my-tag-value-2* ``

Example 3 : Use tag-keys applied to instances

``Key=tag-key,Values=*my-tag-key-1* ,*my-tag-key-2* ``

Example 4 : Use resource group names

``Key=resource-groups:Name,Values=*resource-group-name* ``

Example 5 : Use filters for resource group types

``Key=resource-groups:ResourceTypeFilters,Values=*resource-type-1* ,*resource-type-2* ``

Note

For Key=resource-groups:ResourceTypeFilters , specify resource types in the following format

``Key=resource-groups:ResourceTypeFilters,Values=*AWS::EC2::INSTANCE* ,*AWS::EC2::VPC* ``

For more information about these examples formats, including the best use case for each one, see Examples: Register Targets with a Maintenance Window in the AWS Systems Manager User Guide .

(dict) --

An array of search criteria that targets instances using a Key,Value combination that you specify.

Supported formats include the following.
- ``Key=InstanceIds,Values=*instance-id-1* ,*instance-id-2* ,*instance-id-3* ``
- ``Key=tag:my-tag-key ,Values=*my-tag-value-1* ,*my-tag-value-2* ``
- ``Key=tag-key,Values=*my-tag-key-1* ,*my-tag-key-2* ``
- (Maintenance window targets only) ``Key=resource-groups:Name,Values=*resource-group-name* ``
- (Maintenance window targets only) ``Key=resource-groups:ResourceTypeFilters,Values=*resource-type-1* ,*resource-type-2* ``
For example:
- Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE,i-07782c72faEXAMPLE
- Key=tag:CostCenter,Values=CostCenter1,CostCenter2,CostCenter3
- Key=tag-key,Values=Name,Instance-Type,CostCenter
- (Maintenance window targets only) Key=resource-groups:Name,Values=ProductionResourceGroup
- (Maintenance window targets only) ``Key=resource-groups:ResourceTypeFilters,Values=*AWS::EC2::INSTANCE* ,*AWS::EC2::VPC* ``
For information about how to send commands that target instances using Key,Value parameters, see Using Targets and Rate Controls to Send Commands to a Fleet in the AWS Systems Manager User Guide .
- Key (string) --
  
  User-defined criteria for sending commands that target instances that meet the criteria.
- Values (list) --
  
  User-defined criteria that maps to Key . For example, if you specified tag:ServerRole , you could specify value:WebServer to run a command on instances that include Amazon EC2 tags of ServerRole,WebServer .
  - (string) --

type OwnerInformation

string

param OwnerInformation

User-provided value that will be included in any CloudWatch events raised while running tasks for these targets in this maintenance window.

type Name

string

param Name

An optional name for the target.

type Description

string

param Description

An optional description for the target.

type ClientToken

string

param ClientToken

User-provided idempotency token.

This field is autopopulated if not provided.

rtype

dict

returns

Response Syntax

{
    'WindowTargetId': 'string'
}

Response Structure

(dict) --
- WindowTargetId (string) --
  
  The ID of the target definition in this maintenance window.