AWS Systems Manager
API Reference (API Version 2014-11-06)

CreateAssociation

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.

Request Syntax

{ "AssociationName": "string", "ComplianceSeverity": "string", "DocumentVersion": "string", "InstanceId": "string", "MaxConcurrency": "string", "MaxErrors": "string", "Name": "string", "OutputLocation": { "S3Location": { "OutputS3BucketName": "string", "OutputS3KeyPrefix": "string", "OutputS3Region": "string" } }, "Parameters": { "string" : [ "string" ] }, "ScheduleExpression": "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.

AssociationName

Specify a descriptive name for the association.

Type: String

Pattern: ^[a-zA-Z0-9_\-.]{3,128}$

Required: No

ComplianceSeverity

The severity level to assign to the association.

Type: String

Valid Values: CRITICAL | HIGH | MEDIUM | LOW | UNSPECIFIED

Required: No

DocumentVersion

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

Type: String

Pattern: ([$]LATEST|[$]DEFAULT|^[1-9][0-9]*$)

Required: No

InstanceId

The instance ID.

Type: String

Pattern: (^i-(\w{8}|\w{17})$)|(^mi-\w{17}$)

Required: No

MaxConcurrency

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 execute an association while Systems Manager is executing 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.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 7.

Pattern: ^([1-9][0-9]*|[1-9][0-9]%|[1-9]%|100%)$

Required: No

MaxErrors

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.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 7.

Pattern: ^([1-9][0-9]*|[0]|[1-9][0-9]%|[0-9]%|100%)$

Required: No

Name

The name of the Systems Manager document.

Type: String

Pattern: ^[a-zA-Z0-9_\-.]{3,128}$

Required: Yes

OutputLocation

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

Type: InstanceAssociationOutputLocation object

Required: No

Parameters

The parameters for the documents runtime configuration.

Type: String to array of strings map

Required: No

ScheduleExpression

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

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Required: No

Targets

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

Type: Array of Target objects

Array Members: Minimum number of 0 items. Maximum number of 5 items.

Required: No

Response Syntax

{ "AssociationDescription": { "AssociationId": "string", "AssociationName": "string", "AssociationVersion": "string", "ComplianceSeverity": "string", "Date": number, "DocumentVersion": "string", "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", "Status": { "AdditionalInfo": "string", "Date": number, "Message": "string", "Name": "string" }, "Targets": [ { "Key": "string", "Values": [ "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.

AssociationDescription

Information about the association.

Type: AssociationDescription object

Errors

For information about the errors that are common to all actions, see Common Errors.

AssociationAlreadyExists

The specified association already exists.

HTTP Status Code: 400

AssociationLimitExceeded

You can have at most 2,000 active associations.

HTTP Status Code: 400

InternalServerError

An error occurred on the server side.

HTTP Status Code: 500

InvalidDocument

The specified document does not exist.

HTTP Status Code: 400

InvalidDocumentVersion

The document version is not valid or does not exist.

HTTP Status Code: 400

InvalidInstanceId

The following problems can cause this exception:

You do not have permission to access the instance.

SSM Agent is not running. On managed instances and Linux instances, verify that the SSM Agent is running. On EC2 Windows instances, verify that the EC2Config service is running.

SSM Agent or EC2Config service is not registered to the SSM endpoint. Try reinstalling SSM Agent or EC2Config service.

The instance is not in valid state. Valid states are: Running, Pending, Stopped, Stopping. Invalid states are: Shutting-down and Terminated.

HTTP Status Code: 400

InvalidOutputLocation

The output location is not valid or does not exist.

HTTP Status Code: 400

InvalidParameters

You must specify values for all required parameters in the Systems Manager document. You can only supply values to parameters defined in the Systems Manager 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 is not valid or does not exist. It might not be configured for EC2 Systems Manager or you might not have permission to perform the operation.

HTTP Status Code: 400

UnsupportedPlatformType

The document does not support the platform type of the given instance ID(s). For example, you sent an document for a Windows instance to a Linux instance.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: