2020/06/04 - Amazon Simple Systems Manager (SSM) - 6 updated api methods
Changes SSM State Manager support for executing an association only at specified CRON schedule after creating/updating an association.
{'ApplyOnlyAtCronInterval': 'boolean'}
Response {'AssociationDescription': {'ApplyOnlyAtCronInterval': 'boolean'}}
Associates the specified Systems Manager document with the specified instances or targets.
When you associate a document with one or more instances, 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 returns 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',
AutomationTargetParameterName='string',
MaxErrors='string',
MaxConcurrency='string',
ComplianceSeverity='CRITICAL'|'HIGH'|'MEDIUM'|'LOW'|'UNSPECIFIED',
SyncCompliance='AUTO'|'MANUAL',
ApplyOnlyAtCronInterval=True|False
)
string
[REQUIRED]
The name of the SSM document that contains the configuration information for the instance. You can specify Command or Automation documents.
You can specify AWS-predefined documents, documents you created, or a document that is shared with you from another account.
For SSM documents that are shared with you from other AWS accounts, you must specify the complete SSM document ARN, in the following format:
arn:partition:ssm:region:account-id:document/document-name
For example:
arn:aws:ssm:us-east-2:12345678912:document/My-Shared-Document
For AWS-predefined documents and SSM documents you created in your account, you only need to specify the document name. For example, AWS-ApplyPatchBaseline or My-Document .
string
The document version you want to associate with the target(s). Can be a specific version or the default version.
string
The instance ID.
Note
InstanceId has been deprecated. To specify an instance ID for an association, use the Targets parameter. Requests that include the parameter InstanceID with SSM documents that use schema version 2.0 or later will fail. In addition, if you use the parameter InstanceId , you cannot use the parameters AssociationName , DocumentVersion , MaxErrors , MaxConcurrency , OutputLocation , or ScheduleExpression . To use these parameters, you must use the Targets parameter.
dict
The parameters for the runtime configuration of the document.
(string) --
(list) --
(string) --
list
The targets for the association. You can target instances by using tags, AWS Resource Groups, all instances in an AWS account, or individual instance IDs. For more information about choosing targets for an association, see Using targets and rate controls with State Manager associations 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 This example demonstrates how to target all resources in the resource group ProductionResourceGroup in your maintenance window.
(Maintenance window targets only) Key=resource-groups:ResourceTypeFilters,Values=AWS::EC2::INSTANCE,AWS::EC2::VPC This example demonstrates how to target only EC2 instances and VPCs in your maintenance window.
(State Manager association targets only) Key=InstanceIds,Values=* This example demonstrates how to target all managed instances in the AWS Region where the association was created.
For information about how to send commands that target instances using Key,Value parameters, see Targeting multiple instances 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 EC2 tags of ServerRole,WebServer .
(string) --
string
A cron expression when the association will be applied to the target(s).
dict
An S3 bucket where you want to store the output details of the request.
S3Location (dict) --
An 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 Region of the S3 bucket.
OutputS3BucketName (string) --
The name of the S3 bucket.
OutputS3KeyPrefix (string) --
The S3 bucket subfolder.
string
Specify a descriptive name for the association.
string
Specify the target for the association. This target is required for associations that use an Automation document and target resources by using rate controls.
string
The number of errors that are allowed before the system stops sending requests to run the association on additional targets. You can specify either an absolute number of errors, for example 10, or a percentage of the target set, for example 10%. If you specify 3, for example, the system stops sending requests when the fourth error is received. If you specify 0, then the system stops sending requests after the first error is returned. If you run an association on 50 instances and set MaxError to 10%, then the system stops sending the request when the sixth error is received.
Executions that are already running an association when MaxErrors is reached are allowed to complete, but some of these executions may fail as well. If you need to ensure that there won't be more than max-errors failed executions, set MaxConcurrency to 1 so that executions proceed one at a time.
string
The maximum number of targets allowed to run the association at the same time. You can specify a number, for example 10, or a percentage of the target set, for example 10%. The default value is 100%, which means all targets run the association at the same time.
If a new instance starts and attempts to run an association while Systems Manager is running MaxConcurrency associations, the association is allowed to run. During the next association interval, the new instance will process its association within the limit specified for MaxConcurrency.
string
The severity level to assign to the association.
string
The mode for generating association compliance. You can specify AUTO or MANUAL . In AUTO mode, the system uses the status of the association execution to determine the compliance status. If the association execution runs successfully, then the association is COMPLIANT . If the association execution doesn't run successfully, the association is NON-COMPLIANT .
In MANUAL mode, you must specify the AssociationId as a parameter for the PutComplianceItems API action. In this case, compliance data is not managed by State Manager. It is managed by your direct call to the PutComplianceItems API action.
By default, all associations use AUTO mode.
boolean
By default, when you create a new associations, the system runs it immediately after it is created and then according to the schedule you specified. Specify this option if you don't want an association to run immediately after you create it.
dict
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',
'AutomationTargetParameterName': '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',
'MaxErrors': 'string',
'MaxConcurrency': 'string',
'ComplianceSeverity': 'CRITICAL'|'HIGH'|'MEDIUM'|'LOW'|'UNSPECIFIED',
'SyncCompliance': 'AUTO'|'MANUAL',
'ApplyOnlyAtCronInterval': True|False
}
}
Response Structure
(dict) --
AssociationDescription (dict) --
Information about the association.
Name (string) --
The name of the Systems Manager 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.
AutomationTargetParameterName (string) --
Specify the target for the association. This target is required for associations that use an Automation document and target resources by using rate controls.
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.
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 This example demonstrates how to target all resources in the resource group ProductionResourceGroup in your maintenance window.
(Maintenance window targets only) Key=resource-groups:ResourceTypeFilters,Values=AWS::EC2::INSTANCE,AWS::EC2::VPC This example demonstrates how to target only EC2 instances and VPCs in your maintenance window.
(State Manager association targets only) Key=InstanceIds,Values=* This example demonstrates how to target all managed instances in the AWS Region where the association was created.
For information about how to send commands that target instances using Key,Value parameters, see Targeting multiple instances 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 EC2 tags of ServerRole,WebServer .
(string) --
ScheduleExpression (string) --
A cron expression that specifies a schedule when the association runs.
OutputLocation (dict) --
An S3 bucket where you want to store the output details of the request.
S3Location (dict) --
An 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 Region of the S3 bucket.
OutputS3BucketName (string) --
The name of the S3 bucket.
OutputS3KeyPrefix (string) --
The 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.
MaxErrors (string) --
The number of errors that are allowed before the system stops sending requests to run the association on additional targets. You can specify either an absolute number of errors, for example 10, or a percentage of the target set, for example 10%. If you specify 3, for example, the system stops sending requests when the fourth error is received. If you specify 0, then the system stops sending requests after the first error is returned. If you run an association on 50 instances and set MaxError to 10%, then the system stops sending the request when the sixth error is received.
Executions that are already running an association when MaxErrors is reached are allowed to complete, but some of these executions may fail as well. If you need to ensure that there won't be more than max-errors failed executions, set MaxConcurrency to 1 so that executions proceed one at a time.
MaxConcurrency (string) --
The maximum number of targets allowed to run the association at the same time. You can specify a number, for example 10, or a percentage of the target set, for example 10%. The default value is 100%, which means all targets run the association at the same time.
If a new instance starts and attempts to run an association while Systems Manager is running MaxConcurrency associations, the association is allowed to run. During the next association interval, the new instance will process its association within the limit specified for MaxConcurrency.
ComplianceSeverity (string) --
The severity level that is assigned to the association.
SyncCompliance (string) --
The mode for generating association compliance. You can specify AUTO or MANUAL . In AUTO mode, the system uses the status of the association execution to determine the compliance status. If the association execution runs successfully, then the association is COMPLIANT . If the association execution doesn't run successfully, the association is NON-COMPLIANT .
In MANUAL mode, you must specify the AssociationId as a parameter for the PutComplianceItems API action. In this case, compliance data is not managed by State Manager. It is managed by your direct call to the PutComplianceItems API action.
By default, all associations use AUTO mode.
ApplyOnlyAtCronInterval (boolean) --
By default, when you create a new associations, the system runs it immediately after it is created and then according to the schedule you specified. Specify this option if you don't want an association to run immediately after you create it.
{'Entries': {'ApplyOnlyAtCronInterval': 'boolean'}}
Response {'Failed': {'Entry': {'ApplyOnlyAtCronInterval': 'boolean'}},
'Successful': {'ApplyOnlyAtCronInterval': 'boolean'}}
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, 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 returns the AssociationAlreadyExists exception.
See also: AWS API Documentation
Request Syntax
client.create_association_batch(
Entries=[
{
'Name': 'string',
'InstanceId': 'string',
'Parameters': {
'string': [
'string',
]
},
'AutomationTargetParameterName': 'string',
'DocumentVersion': 'string',
'Targets': [
{
'Key': 'string',
'Values': [
'string',
]
},
],
'ScheduleExpression': 'string',
'OutputLocation': {
'S3Location': {
'OutputS3Region': 'string',
'OutputS3BucketName': 'string',
'OutputS3KeyPrefix': 'string'
}
},
'AssociationName': 'string',
'MaxErrors': 'string',
'MaxConcurrency': 'string',
'ComplianceSeverity': 'CRITICAL'|'HIGH'|'MEDIUM'|'LOW'|'UNSPECIFIED',
'SyncCompliance': 'AUTO'|'MANUAL',
'ApplyOnlyAtCronInterval': True|False
},
]
)
list
[REQUIRED]
One or more associations.
(dict) --
Describes the association of a Systems Manager SSM document and an instance.
Name (string) -- [REQUIRED]
The name of the SSM document that contains the configuration information for the instance. You can specify Command or Automation documents.
You can specify AWS-predefined documents, documents you created, or a document that is shared with you from another account.
For SSM documents that are shared with you from other AWS accounts, you must specify the complete SSM document ARN, in the following format:
arn:aws:ssm:region:account-id:document/document-name
For example:
arn:aws:ssm:us-east-2:12345678912:document/My-Shared-Document
For AWS-predefined documents and SSM documents you created in your account, you only need to specify the document name. For example, AWS-ApplyPatchBaseline or My-Document .
InstanceId (string) --
The ID of the instance.
Parameters (dict) --
A description of the parameters for a document.
(string) --
(list) --
(string) --
AutomationTargetParameterName (string) --
Specify the target for the association. This target is required for associations that use an Automation document and target resources by using rate controls.
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.
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 This example demonstrates how to target all resources in the resource group ProductionResourceGroup in your maintenance window.
(Maintenance window targets only) Key=resource-groups:ResourceTypeFilters,Values=AWS::EC2::INSTANCE,AWS::EC2::VPC This example demonstrates how to target only EC2 instances and VPCs in your maintenance window.
(State Manager association targets only) Key=InstanceIds,Values=* This example demonstrates how to target all managed instances in the AWS Region where the association was created.
For information about how to send commands that target instances using Key,Value parameters, see Targeting multiple instances 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 EC2 tags of ServerRole,WebServer .
(string) --
ScheduleExpression (string) --
A cron expression that specifies a schedule when the association runs.
OutputLocation (dict) --
An S3 bucket where you want to store the results of this request.
S3Location (dict) --
An 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 Region of the S3 bucket.
OutputS3BucketName (string) --
The name of the S3 bucket.
OutputS3KeyPrefix (string) --
The S3 bucket subfolder.
AssociationName (string) --
Specify a descriptive name for the association.
MaxErrors (string) --
The number of errors that are allowed before the system stops sending requests to run the association on additional targets. You can specify either an absolute number of errors, for example 10, or a percentage of the target set, for example 10%. If you specify 3, for example, the system stops sending requests when the fourth error is received. If you specify 0, then the system stops sending requests after the first error is returned. If you run an association on 50 instances and set MaxError to 10%, then the system stops sending the request when the sixth error is received.
Executions that are already running an association when MaxErrors is reached are allowed to complete, but some of these executions may fail as well. If you need to ensure that there won't be more than max-errors failed executions, set MaxConcurrency to 1 so that executions proceed one at a time.
MaxConcurrency (string) --
The maximum number of targets allowed to run the association at the same time. You can specify a number, for example 10, or a percentage of the target set, for example 10%. The default value is 100%, which means all targets run the association at the same time.
If a new instance starts and attempts to run an association while Systems Manager is running MaxConcurrency associations, the association is allowed to run. During the next association interval, the new instance will process its association within the limit specified for MaxConcurrency.
ComplianceSeverity (string) --
The severity level to assign to the association.
SyncCompliance (string) --
The mode for generating association compliance. You can specify AUTO or MANUAL . In AUTO mode, the system uses the status of the association execution to determine the compliance status. If the association execution runs successfully, then the association is COMPLIANT . If the association execution doesn't run successfully, the association is NON-COMPLIANT .
In MANUAL mode, you must specify the AssociationId as a parameter for the PutComplianceItems API action. In this case, compliance data is not managed by State Manager. It is managed by your direct call to the PutComplianceItems API action.
By default, all associations use AUTO mode.
ApplyOnlyAtCronInterval (boolean) --
By default, when you create a new associations, the system runs it immediately after it is created and then according to the schedule you specified. Specify this option if you don't want an association to run immediately after you create it.
dict
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',
'AutomationTargetParameterName': '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',
'MaxErrors': 'string',
'MaxConcurrency': 'string',
'ComplianceSeverity': 'CRITICAL'|'HIGH'|'MEDIUM'|'LOW'|'UNSPECIFIED',
'SyncCompliance': 'AUTO'|'MANUAL',
'ApplyOnlyAtCronInterval': True|False
},
],
'Failed': [
{
'Entry': {
'Name': 'string',
'InstanceId': 'string',
'Parameters': {
'string': [
'string',
]
},
'AutomationTargetParameterName': 'string',
'DocumentVersion': 'string',
'Targets': [
{
'Key': 'string',
'Values': [
'string',
]
},
],
'ScheduleExpression': 'string',
'OutputLocation': {
'S3Location': {
'OutputS3Region': 'string',
'OutputS3BucketName': 'string',
'OutputS3KeyPrefix': 'string'
}
},
'AssociationName': 'string',
'MaxErrors': 'string',
'MaxConcurrency': 'string',
'ComplianceSeverity': 'CRITICAL'|'HIGH'|'MEDIUM'|'LOW'|'UNSPECIFIED',
'SyncCompliance': 'AUTO'|'MANUAL',
'ApplyOnlyAtCronInterval': True|False
},
'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 Systems Manager 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.
AutomationTargetParameterName (string) --
Specify the target for the association. This target is required for associations that use an Automation document and target resources by using rate controls.
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.
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 This example demonstrates how to target all resources in the resource group ProductionResourceGroup in your maintenance window.
(Maintenance window targets only) Key=resource-groups:ResourceTypeFilters,Values=AWS::EC2::INSTANCE,AWS::EC2::VPC This example demonstrates how to target only EC2 instances and VPCs in your maintenance window.
(State Manager association targets only) Key=InstanceIds,Values=* This example demonstrates how to target all managed instances in the AWS Region where the association was created.
For information about how to send commands that target instances using Key,Value parameters, see Targeting multiple instances 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 EC2 tags of ServerRole,WebServer .
(string) --
ScheduleExpression (string) --
A cron expression that specifies a schedule when the association runs.
OutputLocation (dict) --
An S3 bucket where you want to store the output details of the request.
S3Location (dict) --
An 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 Region of the S3 bucket.
OutputS3BucketName (string) --
The name of the S3 bucket.
OutputS3KeyPrefix (string) --
The 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.
MaxErrors (string) --
The number of errors that are allowed before the system stops sending requests to run the association on additional targets. You can specify either an absolute number of errors, for example 10, or a percentage of the target set, for example 10%. If you specify 3, for example, the system stops sending requests when the fourth error is received. If you specify 0, then the system stops sending requests after the first error is returned. If you run an association on 50 instances and set MaxError to 10%, then the system stops sending the request when the sixth error is received.
Executions that are already running an association when MaxErrors is reached are allowed to complete, but some of these executions may fail as well. If you need to ensure that there won't be more than max-errors failed executions, set MaxConcurrency to 1 so that executions proceed one at a time.
MaxConcurrency (string) --
The maximum number of targets allowed to run the association at the same time. You can specify a number, for example 10, or a percentage of the target set, for example 10%. The default value is 100%, which means all targets run the association at the same time.
If a new instance starts and attempts to run an association while Systems Manager is running MaxConcurrency associations, the association is allowed to run. During the next association interval, the new instance will process its association within the limit specified for MaxConcurrency.
ComplianceSeverity (string) --
The severity level that is assigned to the association.
SyncCompliance (string) --
The mode for generating association compliance. You can specify AUTO or MANUAL . In AUTO mode, the system uses the status of the association execution to determine the compliance status. If the association execution runs successfully, then the association is COMPLIANT . If the association execution doesn't run successfully, the association is NON-COMPLIANT .
In MANUAL mode, you must specify the AssociationId as a parameter for the PutComplianceItems API action. In this case, compliance data is not managed by State Manager. It is managed by your direct call to the PutComplianceItems API action.
By default, all associations use AUTO mode.
ApplyOnlyAtCronInterval (boolean) --
By default, when you create a new associations, the system runs it immediately after it is created and then according to the schedule you specified. Specify this option if you don't want an association to run immediately after you create it.
Failed (list) --
Information about the associations that failed.
(dict) --
Describes a failed association.
Entry (dict) --
The association.
Name (string) --
The name of the SSM document that contains the configuration information for the instance. You can specify Command or Automation documents.
You can specify AWS-predefined documents, documents you created, or a document that is shared with you from another account.
For SSM documents that are shared with you from other AWS accounts, you must specify the complete SSM document ARN, in the following format:
arn:aws:ssm:region:account-id:document/document-name
For example:
arn:aws:ssm:us-east-2:12345678912:document/My-Shared-Document
For AWS-predefined documents and SSM documents you created in your account, you only need to specify the document name. For example, AWS-ApplyPatchBaseline or My-Document .
InstanceId (string) --
The ID of the instance.
Parameters (dict) --
A description of the parameters for a document.
(string) --
(list) --
(string) --
AutomationTargetParameterName (string) --
Specify the target for the association. This target is required for associations that use an Automation document and target resources by using rate controls.
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.
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 This example demonstrates how to target all resources in the resource group ProductionResourceGroup in your maintenance window.
(Maintenance window targets only) Key=resource-groups:ResourceTypeFilters,Values=AWS::EC2::INSTANCE,AWS::EC2::VPC This example demonstrates how to target only EC2 instances and VPCs in your maintenance window.
(State Manager association targets only) Key=InstanceIds,Values=* This example demonstrates how to target all managed instances in the AWS Region where the association was created.
For information about how to send commands that target instances using Key,Value parameters, see Targeting multiple instances 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 EC2 tags of ServerRole,WebServer .
(string) --
ScheduleExpression (string) --
A cron expression that specifies a schedule when the association runs.
OutputLocation (dict) --
An S3 bucket where you want to store the results of this request.
S3Location (dict) --
An 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 Region of the S3 bucket.
OutputS3BucketName (string) --
The name of the S3 bucket.
OutputS3KeyPrefix (string) --
The S3 bucket subfolder.
AssociationName (string) --
Specify a descriptive name for the association.
MaxErrors (string) --
The number of errors that are allowed before the system stops sending requests to run the association on additional targets. You can specify either an absolute number of errors, for example 10, or a percentage of the target set, for example 10%. If you specify 3, for example, the system stops sending requests when the fourth error is received. If you specify 0, then the system stops sending requests after the first error is returned. If you run an association on 50 instances and set MaxError to 10%, then the system stops sending the request when the sixth error is received.
Executions that are already running an association when MaxErrors is reached are allowed to complete, but some of these executions may fail as well. If you need to ensure that there won't be more than max-errors failed executions, set MaxConcurrency to 1 so that executions proceed one at a time.
MaxConcurrency (string) --
The maximum number of targets allowed to run the association at the same time. You can specify a number, for example 10, or a percentage of the target set, for example 10%. The default value is 100%, which means all targets run the association at the same time.
If a new instance starts and attempts to run an association while Systems Manager is running MaxConcurrency associations, the association is allowed to run. During the next association interval, the new instance will process its association within the limit specified for MaxConcurrency.
ComplianceSeverity (string) --
The severity level to assign to the association.
SyncCompliance (string) --
The mode for generating association compliance. You can specify AUTO or MANUAL . In AUTO mode, the system uses the status of the association execution to determine the compliance status. If the association execution runs successfully, then the association is COMPLIANT . If the association execution doesn't run successfully, the association is NON-COMPLIANT .
In MANUAL mode, you must specify the AssociationId as a parameter for the PutComplianceItems API action. In this case, compliance data is not managed by State Manager. It is managed by your direct call to the PutComplianceItems API action.
By default, all associations use AUTO mode.
ApplyOnlyAtCronInterval (boolean) --
By default, when you create a new associations, the system runs it immediately after it is created and then according to the schedule you specified. Specify this option if you don't want an association to run immediately after you create it.
Message (string) --
A description of the failure.
Fault (string) --
The source of the failure.
{'AssociationDescription': {'ApplyOnlyAtCronInterval': 'boolean'}}
Describes the association for the specified target or instance. If you created the association by using the Targets parameter, then you must retrieve the association by using the association ID. If you created the association by specifying an instance ID and a Systems Manager document, then you retrieve the association by specifying the document name and the instance ID.
See also: AWS API Documentation
Request Syntax
client.describe_association(
Name='string',
InstanceId='string',
AssociationId='string',
AssociationVersion='string'
)
string
The name of the Systems Manager document.
string
The instance ID.
string
The association ID for which you want information.
string
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 ListAssociations. To get a list of versions for a specific association, use ListAssociationVersions.
dict
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',
'AutomationTargetParameterName': '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',
'MaxErrors': 'string',
'MaxConcurrency': 'string',
'ComplianceSeverity': 'CRITICAL'|'HIGH'|'MEDIUM'|'LOW'|'UNSPECIFIED',
'SyncCompliance': 'AUTO'|'MANUAL',
'ApplyOnlyAtCronInterval': True|False
}
}
Response Structure
(dict) --
AssociationDescription (dict) --
Information about the association.
Name (string) --
The name of the Systems Manager 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.
AutomationTargetParameterName (string) --
Specify the target for the association. This target is required for associations that use an Automation document and target resources by using rate controls.
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.
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 This example demonstrates how to target all resources in the resource group ProductionResourceGroup in your maintenance window.
(Maintenance window targets only) Key=resource-groups:ResourceTypeFilters,Values=AWS::EC2::INSTANCE,AWS::EC2::VPC This example demonstrates how to target only EC2 instances and VPCs in your maintenance window.
(State Manager association targets only) Key=InstanceIds,Values=* This example demonstrates how to target all managed instances in the AWS Region where the association was created.
For information about how to send commands that target instances using Key,Value parameters, see Targeting multiple instances 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 EC2 tags of ServerRole,WebServer .
(string) --
ScheduleExpression (string) --
A cron expression that specifies a schedule when the association runs.
OutputLocation (dict) --
An S3 bucket where you want to store the output details of the request.
S3Location (dict) --
An 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 Region of the S3 bucket.
OutputS3BucketName (string) --
The name of the S3 bucket.
OutputS3KeyPrefix (string) --
The 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.
MaxErrors (string) --
The number of errors that are allowed before the system stops sending requests to run the association on additional targets. You can specify either an absolute number of errors, for example 10, or a percentage of the target set, for example 10%. If you specify 3, for example, the system stops sending requests when the fourth error is received. If you specify 0, then the system stops sending requests after the first error is returned. If you run an association on 50 instances and set MaxError to 10%, then the system stops sending the request when the sixth error is received.
Executions that are already running an association when MaxErrors is reached are allowed to complete, but some of these executions may fail as well. If you need to ensure that there won't be more than max-errors failed executions, set MaxConcurrency to 1 so that executions proceed one at a time.
MaxConcurrency (string) --
The maximum number of targets allowed to run the association at the same time. You can specify a number, for example 10, or a percentage of the target set, for example 10%. The default value is 100%, which means all targets run the association at the same time.
If a new instance starts and attempts to run an association while Systems Manager is running MaxConcurrency associations, the association is allowed to run. During the next association interval, the new instance will process its association within the limit specified for MaxConcurrency.
ComplianceSeverity (string) --
The severity level that is assigned to the association.
SyncCompliance (string) --
The mode for generating association compliance. You can specify AUTO or MANUAL . In AUTO mode, the system uses the status of the association execution to determine the compliance status. If the association execution runs successfully, then the association is COMPLIANT . If the association execution doesn't run successfully, the association is NON-COMPLIANT .
In MANUAL mode, you must specify the AssociationId as a parameter for the PutComplianceItems API action. In this case, compliance data is not managed by State Manager. It is managed by your direct call to the PutComplianceItems API action.
By default, all associations use AUTO mode.
ApplyOnlyAtCronInterval (boolean) --
By default, when you create a new associations, the system runs it immediately after it is created and then according to the schedule you specified. Specify this option if you don't want an association to run immediately after you create it.
{'AssociationVersions': {'ApplyOnlyAtCronInterval': 'boolean'}}
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'
)
string
[REQUIRED]
The association ID for which you want to view all versions.
integer
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.
string
A token to start the list. Use this token to get the next set of results.
dict
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',
'MaxErrors': 'string',
'MaxConcurrency': 'string',
'ComplianceSeverity': 'CRITICAL'|'HIGH'|'MEDIUM'|'LOW'|'UNSPECIFIED',
'SyncCompliance': 'AUTO'|'MANUAL',
'ApplyOnlyAtCronInterval': True|False
},
],
'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 a Systems Manager 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.
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 This example demonstrates how to target all resources in the resource group ProductionResourceGroup in your maintenance window.
(Maintenance window targets only) Key=resource-groups:ResourceTypeFilters,Values=AWS::EC2::INSTANCE,AWS::EC2::VPC This example demonstrates how to target only EC2 instances and VPCs in your maintenance window.
(State Manager association targets only) Key=InstanceIds,Values=* This example demonstrates how to target all managed instances in the AWS Region where the association was created.
For information about how to send commands that target instances using Key,Value parameters, see Targeting multiple instances 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 EC2 tags of ServerRole,WebServer .
(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 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 Region of the S3 bucket.
OutputS3BucketName (string) --
The name of the S3 bucket.
OutputS3KeyPrefix (string) --
The S3 bucket subfolder.
AssociationName (string) --
The name specified for the association version when the association version was created.
MaxErrors (string) --
The number of errors that are allowed before the system stops sending requests to run the association on additional targets. You can specify either an absolute number of errors, for example 10, or a percentage of the target set, for example 10%. If you specify 3, for example, the system stops sending requests when the fourth error is received. If you specify 0, then the system stops sending requests after the first error is returned. If you run an association on 50 instances and set MaxError to 10%, then the system stops sending the request when the sixth error is received.
Executions that are already running an association when MaxErrors is reached are allowed to complete, but some of these executions may fail as well. If you need to ensure that there won't be more than max-errors failed executions, set MaxConcurrency to 1 so that executions proceed one at a time.
MaxConcurrency (string) --
The maximum number of targets allowed to run the association at the same time. You can specify a number, for example 10, or a percentage of the target set, for example 10%. The default value is 100%, which means all targets run the association at the same time.
If a new instance starts and attempts to run an association while Systems Manager is running MaxConcurrency associations, the association is allowed to run. During the next association interval, the new instance will process its association within the limit specified for MaxConcurrency.
ComplianceSeverity (string) --
The severity level that is assigned to the association.
SyncCompliance (string) --
The mode for generating association compliance. You can specify AUTO or MANUAL . In AUTO mode, the system uses the status of the association execution to determine the compliance status. If the association execution runs successfully, then the association is COMPLIANT . If the association execution doesn't run successfully, the association is NON-COMPLIANT .
In MANUAL mode, you must specify the AssociationId as a parameter for the PutComplianceItems API action. In this case, compliance data is not managed by State Manager. It is managed by your direct call to the PutComplianceItems API action.
By default, all associations use AUTO mode.
ApplyOnlyAtCronInterval (boolean) --
By default, when you create a new associations, the system runs it immediately after it is created and then according to the schedule you specified. Specify this option if you don't want an association to run immediately after you create it.
NextToken (string) --
The token for the next set of items to return. Use this token to get the next set of results.
{'ApplyOnlyAtCronInterval': 'boolean'}
Response {'AssociationDescription': {'ApplyOnlyAtCronInterval': 'boolean'}}
Updates an association. You can update the association name and version, the document version, schedule, parameters, and Amazon S3 output.
In order to call this API action, your IAM user account, group, or role must be configured with permission to call the DescribeAssociation API action. If you don't have permission to call DescribeAssociation, then you receive the following error: An error occurred (AccessDeniedException) when calling the UpdateAssociation operation: User: <user_arn> is not authorized to perform: ssm:DescribeAssociation on resource: <resource_arn>
Warning
When you update an association, the association immediately runs against the specified targets.
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',
AutomationTargetParameterName='string',
MaxErrors='string',
MaxConcurrency='string',
ComplianceSeverity='CRITICAL'|'HIGH'|'MEDIUM'|'LOW'|'UNSPECIFIED',
SyncCompliance='AUTO'|'MANUAL',
ApplyOnlyAtCronInterval=True|False
)
string
[REQUIRED]
The ID of the association you want to update.
dict
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) --
string
The document version you want update for the association.
string
The cron expression used to schedule the association that you want to update.
dict
An S3 bucket where you want to store the results of this request.
S3Location (dict) --
An 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 Region of the S3 bucket.
OutputS3BucketName (string) --
The name of the S3 bucket.
OutputS3KeyPrefix (string) --
The S3 bucket subfolder.
string
The name of the SSM document that contains the configuration information for the instance. You can specify Command or Automation documents.
You can specify AWS-predefined documents, documents you created, or a document that is shared with you from another account.
For SSM documents that are shared with you from other AWS accounts, you must specify the complete SSM document ARN, in the following format:
arn:aws:ssm:region:account-id:document/document-name
For example:
arn:aws:ssm:us-east-2:12345678912:document/My-Shared-Document
For AWS-predefined documents and SSM documents you created in your account, you only need to specify the document name. For example, AWS-ApplyPatchBaseline or My-Document .
list
The targets of the association.
(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 This example demonstrates how to target all resources in the resource group ProductionResourceGroup in your maintenance window.
(Maintenance window targets only) Key=resource-groups:ResourceTypeFilters,Values=AWS::EC2::INSTANCE,AWS::EC2::VPC This example demonstrates how to target only EC2 instances and VPCs in your maintenance window.
(State Manager association targets only) Key=InstanceIds,Values=* This example demonstrates how to target all managed instances in the AWS Region where the association was created.
For information about how to send commands that target instances using Key,Value parameters, see Targeting multiple instances 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 EC2 tags of ServerRole,WebServer .
(string) --
string
The name of the association that you want to update.
string
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.
string
Specify the target for the association. This target is required for associations that use an Automation document and target resources by using rate controls.
string
The number of errors that are allowed before the system stops sending requests to run the association on additional targets. You can specify either an absolute number of errors, for example 10, or a percentage of the target set, for example 10%. If you specify 3, for example, the system stops sending requests when the fourth error is received. If you specify 0, then the system stops sending requests after the first error is returned. If you run an association on 50 instances and set MaxError to 10%, then the system stops sending the request when the sixth error is received.
Executions that are already running an association when MaxErrors is reached are allowed to complete, but some of these executions may fail as well. If you need to ensure that there won't be more than max-errors failed executions, set MaxConcurrency to 1 so that executions proceed one at a time.
string
The maximum number of targets allowed to run the association at the same time. You can specify a number, for example 10, or a percentage of the target set, for example 10%. The default value is 100%, which means all targets run the association at the same time.
If a new instance starts and attempts to run an association while Systems Manager is running MaxConcurrency associations, the association is allowed to run. During the next association interval, the new instance will process its association within the limit specified for MaxConcurrency.
string
The severity level to assign to the association.
string
The mode for generating association compliance. You can specify AUTO or MANUAL . In AUTO mode, the system uses the status of the association execution to determine the compliance status. If the association execution runs successfully, then the association is COMPLIANT . If the association execution doesn't run successfully, the association is NON-COMPLIANT .
In MANUAL mode, you must specify the AssociationId as a parameter for the PutComplianceItems API action. In this case, compliance data is not managed by State Manager. It is managed by your direct call to the PutComplianceItems API action.
By default, all associations use AUTO mode.
boolean
By default, when you update an association, the system runs it immediately after it is updated and then according to the schedule you specified. Specify this option if you don't want an association to run immediately after you update it.
Also, if you specified this option when you created the association, you can reset it. To do so, specify the no-apply-only-at-cron-interval parameter when you update the association from the command line. This parameter forces the association to run immediately after updating it and according to the interval specified.
dict
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',
'AutomationTargetParameterName': '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',
'MaxErrors': 'string',
'MaxConcurrency': 'string',
'ComplianceSeverity': 'CRITICAL'|'HIGH'|'MEDIUM'|'LOW'|'UNSPECIFIED',
'SyncCompliance': 'AUTO'|'MANUAL',
'ApplyOnlyAtCronInterval': True|False
}
}
Response Structure
(dict) --
AssociationDescription (dict) --
The description of the association that was updated.
Name (string) --
The name of the Systems Manager 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.
AutomationTargetParameterName (string) --
Specify the target for the association. This target is required for associations that use an Automation document and target resources by using rate controls.
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.
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 This example demonstrates how to target all resources in the resource group ProductionResourceGroup in your maintenance window.
(Maintenance window targets only) Key=resource-groups:ResourceTypeFilters,Values=AWS::EC2::INSTANCE,AWS::EC2::VPC This example demonstrates how to target only EC2 instances and VPCs in your maintenance window.
(State Manager association targets only) Key=InstanceIds,Values=* This example demonstrates how to target all managed instances in the AWS Region where the association was created.
For information about how to send commands that target instances using Key,Value parameters, see Targeting multiple instances 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 EC2 tags of ServerRole,WebServer .
(string) --
ScheduleExpression (string) --
A cron expression that specifies a schedule when the association runs.
OutputLocation (dict) --
An S3 bucket where you want to store the output details of the request.
S3Location (dict) --
An 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 Region of the S3 bucket.
OutputS3BucketName (string) --
The name of the S3 bucket.
OutputS3KeyPrefix (string) --
The 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.
MaxErrors (string) --
The number of errors that are allowed before the system stops sending requests to run the association on additional targets. You can specify either an absolute number of errors, for example 10, or a percentage of the target set, for example 10%. If you specify 3, for example, the system stops sending requests when the fourth error is received. If you specify 0, then the system stops sending requests after the first error is returned. If you run an association on 50 instances and set MaxError to 10%, then the system stops sending the request when the sixth error is received.
Executions that are already running an association when MaxErrors is reached are allowed to complete, but some of these executions may fail as well. If you need to ensure that there won't be more than max-errors failed executions, set MaxConcurrency to 1 so that executions proceed one at a time.
MaxConcurrency (string) --
The maximum number of targets allowed to run the association at the same time. You can specify a number, for example 10, or a percentage of the target set, for example 10%. The default value is 100%, which means all targets run the association at the same time.
If a new instance starts and attempts to run an association while Systems Manager is running MaxConcurrency associations, the association is allowed to run. During the next association interval, the new instance will process its association within the limit specified for MaxConcurrency.
ComplianceSeverity (string) --
The severity level that is assigned to the association.
SyncCompliance (string) --
The mode for generating association compliance. You can specify AUTO or MANUAL . In AUTO mode, the system uses the status of the association execution to determine the compliance status. If the association execution runs successfully, then the association is COMPLIANT . If the association execution doesn't run successfully, the association is NON-COMPLIANT .
In MANUAL mode, you must specify the AssociationId as a parameter for the PutComplianceItems API action. In this case, compliance data is not managed by State Manager. It is managed by your direct call to the PutComplianceItems API action.
By default, all associations use AUTO mode.
ApplyOnlyAtCronInterval (boolean) --
By default, when you create a new associations, the system runs it immediately after it is created and then according to the schedule you specified. Specify this option if you don't want an association to run immediately after you create it.
{'AssociationDescription': {'ApplyOnlyAtCronInterval': 'boolean'}}
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'
}
)
string
[REQUIRED]
The name of the Systems Manager document.
string
[REQUIRED]
The ID of the instance.
dict
[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.
dict
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',
'AutomationTargetParameterName': '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',
'MaxErrors': 'string',
'MaxConcurrency': 'string',
'ComplianceSeverity': 'CRITICAL'|'HIGH'|'MEDIUM'|'LOW'|'UNSPECIFIED',
'SyncCompliance': 'AUTO'|'MANUAL',
'ApplyOnlyAtCronInterval': True|False
}
}
Response Structure
(dict) --
AssociationDescription (dict) --
Information about the association.
Name (string) --
The name of the Systems Manager 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.
AutomationTargetParameterName (string) --
Specify the target for the association. This target is required for associations that use an Automation document and target resources by using rate controls.
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.
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 This example demonstrates how to target all resources in the resource group ProductionResourceGroup in your maintenance window.
(Maintenance window targets only) Key=resource-groups:ResourceTypeFilters,Values=AWS::EC2::INSTANCE,AWS::EC2::VPC This example demonstrates how to target only EC2 instances and VPCs in your maintenance window.
(State Manager association targets only) Key=InstanceIds,Values=* This example demonstrates how to target all managed instances in the AWS Region where the association was created.
For information about how to send commands that target instances using Key,Value parameters, see Targeting multiple instances 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 EC2 tags of ServerRole,WebServer .
(string) --
ScheduleExpression (string) --
A cron expression that specifies a schedule when the association runs.
OutputLocation (dict) --
An S3 bucket where you want to store the output details of the request.
S3Location (dict) --
An 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 Region of the S3 bucket.
OutputS3BucketName (string) --
The name of the S3 bucket.
OutputS3KeyPrefix (string) --
The 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.
MaxErrors (string) --
The number of errors that are allowed before the system stops sending requests to run the association on additional targets. You can specify either an absolute number of errors, for example 10, or a percentage of the target set, for example 10%. If you specify 3, for example, the system stops sending requests when the fourth error is received. If you specify 0, then the system stops sending requests after the first error is returned. If you run an association on 50 instances and set MaxError to 10%, then the system stops sending the request when the sixth error is received.
Executions that are already running an association when MaxErrors is reached are allowed to complete, but some of these executions may fail as well. If you need to ensure that there won't be more than max-errors failed executions, set MaxConcurrency to 1 so that executions proceed one at a time.
MaxConcurrency (string) --
The maximum number of targets allowed to run the association at the same time. You can specify a number, for example 10, or a percentage of the target set, for example 10%. The default value is 100%, which means all targets run the association at the same time.
If a new instance starts and attempts to run an association while Systems Manager is running MaxConcurrency associations, the association is allowed to run. During the next association interval, the new instance will process its association within the limit specified for MaxConcurrency.
ComplianceSeverity (string) --
The severity level that is assigned to the association.
SyncCompliance (string) --
The mode for generating association compliance. You can specify AUTO or MANUAL . In AUTO mode, the system uses the status of the association execution to determine the compliance status. If the association execution runs successfully, then the association is COMPLIANT . If the association execution doesn't run successfully, the association is NON-COMPLIANT .
In MANUAL mode, you must specify the AssociationId as a parameter for the PutComplianceItems API action. In this case, compliance data is not managed by State Manager. It is managed by your direct call to the PutComplianceItems API action.
By default, all associations use AUTO mode.
ApplyOnlyAtCronInterval (boolean) --
By default, when you create a new associations, the system runs it immediately after it is created and then according to the schedule you specified. Specify this option if you don't want an association to run immediately after you create it.