CreateAssociationBatch
Associates the specified Amazon Systems Manager document (SSM document) with the specified managed nodes or targets.
When you associate a document with one or more managed nodes using IDs or tags, Amazon Systems Manager Agent (SSM Agent) running on the managed node processes the document and configures the node as specified.
If you associate a document with a managed node that already has an associated document, the system returns the AssociationAlreadyExists exception.
Request Syntax
{
"Entries": [
{
"AlarmConfiguration": {
"Alarms": [
{
"Name": "string
"
}
],
"IgnorePollAlarmFailure": boolean
},
"ApplyOnlyAtCronInterval": boolean
,
"AssociationName": "string
",
"AutomationTargetParameterName": "string
",
"CalendarNames": [ "string
" ],
"ComplianceSeverity": "string
",
"DocumentVersion": "string
",
"Duration": number
,
"InstanceId": "string
",
"MaxConcurrency": "string
",
"MaxErrors": "string
",
"Name": "string
",
"OutputLocation": {
"S3Location": {
"OutputS3BucketName": "string
",
"OutputS3KeyPrefix": "string
",
"OutputS3Region": "string
"
}
},
"Parameters": {
"string
" : [ "string
" ]
},
"ScheduleExpression": "string
",
"ScheduleOffset": number
,
"SyncCompliance": "string
",
"TargetLocations": [
{
"Accounts": [ "string
" ],
"ExcludeAccounts": [ "string
" ],
"ExecutionRoleName": "string
",
"IncludeChildOrganizationUnits": boolean
,
"Regions": [ "string
" ],
"TargetLocationAlarmConfiguration": {
"Alarms": [
{
"Name": "string
"
}
],
"IgnorePollAlarmFailure": boolean
},
"TargetLocationMaxConcurrency": "string
",
"TargetLocationMaxErrors": "string
",
"Targets": [
{
"Key": "string
",
"Values": [ "string
" ]
}
],
"TargetsMaxConcurrency": "string
",
"TargetsMaxErrors": "string
"
}
],
"TargetMaps": [
{
"string
" : [ "string
" ]
}
],
"Targets": [
{
"Key": "string
",
"Values": [ "string
" ]
}
]
}
]
}
Request Parameters
For information about the parameters that are common to all actions, see Common Parameters.
The request accepts the following data in JSON format.
- Entries
-
One or more associations.
Type: Array of CreateAssociationBatchRequestEntry objects
Array Members: Minimum number of 1 item.
Required: Yes
Response Syntax
{
"Failed": [
{
"Entry": {
"AlarmConfiguration": {
"Alarms": [
{
"Name": "string"
}
],
"IgnorePollAlarmFailure": boolean
},
"ApplyOnlyAtCronInterval": boolean,
"AssociationName": "string",
"AutomationTargetParameterName": "string",
"CalendarNames": [ "string" ],
"ComplianceSeverity": "string",
"DocumentVersion": "string",
"Duration": number,
"InstanceId": "string",
"MaxConcurrency": "string",
"MaxErrors": "string",
"Name": "string",
"OutputLocation": {
"S3Location": {
"OutputS3BucketName": "string",
"OutputS3KeyPrefix": "string",
"OutputS3Region": "string"
}
},
"Parameters": {
"string" : [ "string" ]
},
"ScheduleExpression": "string",
"ScheduleOffset": number,
"SyncCompliance": "string",
"TargetLocations": [
{
"Accounts": [ "string" ],
"ExcludeAccounts": [ "string" ],
"ExecutionRoleName": "string",
"IncludeChildOrganizationUnits": boolean,
"Regions": [ "string" ],
"TargetLocationAlarmConfiguration": {
"Alarms": [
{
"Name": "string"
}
],
"IgnorePollAlarmFailure": boolean
},
"TargetLocationMaxConcurrency": "string",
"TargetLocationMaxErrors": "string",
"Targets": [
{
"Key": "string",
"Values": [ "string" ]
}
],
"TargetsMaxConcurrency": "string",
"TargetsMaxErrors": "string"
}
],
"TargetMaps": [
{
"string" : [ "string" ]
}
],
"Targets": [
{
"Key": "string",
"Values": [ "string" ]
}
]
},
"Fault": "string",
"Message": "string"
}
],
"Successful": [
{
"AlarmConfiguration": {
"Alarms": [
{
"Name": "string"
}
],
"IgnorePollAlarmFailure": boolean
},
"ApplyOnlyAtCronInterval": boolean,
"AssociationId": "string",
"AssociationName": "string",
"AssociationVersion": "string",
"AutomationTargetParameterName": "string",
"CalendarNames": [ "string" ],
"ComplianceSeverity": "string",
"Date": number,
"DocumentVersion": "string",
"Duration": number,
"InstanceId": "string",
"LastExecutionDate": number,
"LastSuccessfulExecutionDate": number,
"LastUpdateAssociationDate": number,
"MaxConcurrency": "string",
"MaxErrors": "string",
"Name": "string",
"OutputLocation": {
"S3Location": {
"OutputS3BucketName": "string",
"OutputS3KeyPrefix": "string",
"OutputS3Region": "string"
}
},
"Overview": {
"AssociationStatusAggregatedCount": {
"string" : number
},
"DetailedStatus": "string",
"Status": "string"
},
"Parameters": {
"string" : [ "string" ]
},
"ScheduleExpression": "string",
"ScheduleOffset": number,
"Status": {
"AdditionalInfo": "string",
"Date": number,
"Message": "string",
"Name": "string"
},
"SyncCompliance": "string",
"TargetLocations": [
{
"Accounts": [ "string" ],
"ExcludeAccounts": [ "string" ],
"ExecutionRoleName": "string",
"IncludeChildOrganizationUnits": boolean,
"Regions": [ "string" ],
"TargetLocationAlarmConfiguration": {
"Alarms": [
{
"Name": "string"
}
],
"IgnorePollAlarmFailure": boolean
},
"TargetLocationMaxConcurrency": "string",
"TargetLocationMaxErrors": "string",
"Targets": [
{
"Key": "string",
"Values": [ "string" ]
}
],
"TargetsMaxConcurrency": "string",
"TargetsMaxErrors": "string"
}
],
"TargetMaps": [
{
"string" : [ "string" ]
}
],
"Targets": [
{
"Key": "string",
"Values": [ "string" ]
}
],
"TriggeredAlarms": [
{
"Name": "string",
"State": "string"
}
]
}
]
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- Failed
-
Information about the associations that failed.
Type: Array of FailedCreateAssociation objects
- Successful
-
Information about the associations that succeeded.
Type: Array of AssociationDescription objects
Errors
For information about the errors that are common to all actions, see Common Errors.
- AssociationLimitExceeded
-
You can have at most 2,000 active associations.
HTTP Status Code: 400
- DuplicateInstanceId
-
You can't specify a managed node ID in more than one association.
HTTP Status Code: 400
- InternalServerError
-
An error occurred on the server side.
HTTP Status Code: 500
- InvalidDocument
-
The specified SSM document doesn't exist.
HTTP Status Code: 400
- InvalidDocumentVersion
-
The document version isn't valid or doesn't exist.
HTTP Status Code: 400
- InvalidInstanceId
-
The following problems can cause this exception:
-
You don't have permission to access the managed node.
-
Amazon Systems Manager Agent (SSM Agent) isn't running. Verify that SSM Agent is running.
-
SSM Agent isn't registered with the SSM endpoint. Try reinstalling SSM Agent.
-
The managed node isn't in a valid state. Valid states are:
Running
,Pending
,Stopped
, andStopping
. Invalid states are:Shutting-down
andTerminated
.
HTTP Status Code: 400
-
- InvalidOutputLocation
-
The output location isn't valid or doesn't exist.
HTTP Status Code: 400
- InvalidParameters
-
You must specify values for all required parameters in the Amazon Systems Manager document (SSM document). You can only supply values to parameters defined in the SSM document.
HTTP Status Code: 400
- InvalidSchedule
-
The schedule is invalid. Verify your cron or rate expression and try again.
HTTP Status Code: 400
- InvalidTarget
-
The target isn't valid or doesn't exist. It might not be configured for Systems Manager or you might not have permission to perform the operation.
HTTP Status Code: 400
- InvalidTargetMaps
-
TargetMap parameter isn't valid.
HTTP Status Code: 400
- UnsupportedPlatformType
-
The document doesn't support the platform type of the given managed node IDs. For example, you sent an document for a Windows managed node to a Linux node.
HTTP Status Code: 400
Examples
Example
This example illustrates one usage of CreateAssociationBatch.
Sample Request
POST / HTTP/1.1
Host: ssm.us-east-2.amazonaws.com
Accept-Encoding: identity
X-Amz-Target: AmazonSSM.CreateAssociationBatch
Content-Type: application/x-amz-json-1.1
User-Agent: aws-cli/1.17.12 Python/3.6.8 Darwin/18.7.0 botocore/1.14.12
X-Amz-Date: 20240324T142446Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20240324/us-east-2/ssm/aws4_request,
SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=39c3b3042cd2aEXAMPLE
Content-Length: 151
{
"Entries": [
{
"InstanceId": "i-0471e04240EXAMPLE",
"Name": "AWS-UpdateSSMAgent"
},
{
"InstanceId": "i-07782c72faEXAMPLE",
"Name": "AWS-UpdateSSMAgent"
}
]
}
Sample Response
{
"Failed": [],
"Successful": [
{
"ApplyOnlyAtCronInterval": false,
"AssociationId": "33858bec-0c55-4547-a054-eb5fcEXAMPLE",
"AssociationVersion": "1",
"Date": 1585059887.692,
"DocumentVersion": "$DEFAULT",
"InstanceId": "i-0471e04240EXAMPLE",
"LastUpdateAssociationDate": 1585059887.692,
"Name": "AWS-UpdateSSMAgent",
"Overview": {
"DetailedStatus": "Creating",
"Status": "Pending"
},
"Status": {
"Date": 1585059887.692,
"Message": "Associated with AWS-UpdateSSMAgent",
"Name": "Associated"
},
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-0471e04240EXAMPLE"
]
}
]
},
{
"ApplyOnlyAtCronInterval": false,
"AssociationId": "e0e0a062-3dcb-4b3e-bb2b-d01b4EXAMPLE",
"AssociationVersion": "1",
"Date": 1585059887.726,
"DocumentVersion": "$DEFAULT",
"InstanceId": "i-07782c72faEXAMPLE",
"LastUpdateAssociationDate": 1585059887.726,
"Name": "AWS-UpdateSSMAgent",
"Overview": {
"DetailedStatus": "Creating",
"Status": "Pending"
},
"Status": {
"Date": 1585059887.726,
"Message": "Associated with AWS-UpdateSSMAgent",
"Name": "Associated"
},
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-07782c72faEXAMPLE"
]
}
]
}
]
}
See Also
For more information about using this API in one of the language-specific Amazon SDKs, see the following: