AWS CloudFormation
User Guide (Version )

AWS::SSM::Association

The AWS::SSM::Association resource associates an SSM document in AWS Systems Manager with managed instances that contain a configuration agent to process the document.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{ "Type" : "AWS::SSM::Association", "Properties" : { "AssociationName" : String, "DocumentVersion" : String, "InstanceId" : String, "Name" : String, "OutputLocation" : InstanceAssociationOutputLocation, "Parameters" : {Key : Value, ...}, "ScheduleExpression" : String, "Targets" : [ Target, ... ] } }

YAML

Type: AWS::SSM::Association Properties: AssociationName: String DocumentVersion: String InstanceId: String Name: String OutputLocation: InstanceAssociationOutputLocation Parameters: Key : Value ScheduleExpression: String Targets: - Target

Properties

AssociationName

The name of the association.

Required: No

Type: String

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

Update requires: No interruption

DocumentVersion

The version of the SSM document to associate with the target.

Required: No

Type: String

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

Update requires: No interruption

InstanceId

The ID of the instance that the SSM document is associated with. You must specify the InstanceId or Targets property.

Note

InstanceId has been deprecated. To specify an instance ID for an association, use the Targets parameter. 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.

Required: Conditional

Type: String

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

Update requires: Replacement

Name

The name of the Systems Manager document.

Required: Yes

Type: String

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

Update requires: Replacement

OutputLocation

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

Required: No

Type: InstanceAssociationOutputLocation

Update requires: No interruption

Parameters

The parameters for the runtime configuration of the document.

Required: No

Type: Map of ParameterValues

Update requires: No interruption

ScheduleExpression

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

Required: No

Type: String

Minimum: 1

Maximum: 256

Update requires: No interruption

Targets

The targets for the association. You must specify the InstanceId or Targets property.

Required: Conditional

Type: List of Target

Maximum: 5

Update requires: Replacement

Examples

Associate a Systems Manager document with a specific instance

The following example associates an SSM document with a specific instance. The ID of the instance is specified by the myInstanceId parameter.

JSON

{ "Resources": { "Association": { "Type": "AWS::SSM::Association", "Properties": { "Name": { "Ref": "document" }, "Parameters": { "Directory": ["myWorkSpace"] }, "Targets": [{ "Key": "InstanceIds", "Values": [{ "Ref": "myInstanceId" }] }] } } } }

YAML

Resources: Association: Type: AWS::SSM::Association Properties: Name: !Ref 'document' Parameters: Directory: ["myWorkSpace"] Targets: - Key: InstanceIds Values: [!Ref 'myInstanceId']

Associate a Systems Manager document with all managed instances

The following example associates the document AWS-UpdateSSMAgent with all instances registered with Systems Manager.

JSON

{ "Resources": { "UpdateSSMAgent": { "Type": "AWS::SSM::Association", "Properties": { "AssociationName": "UpdateSSMAgent", "Name": "AWS-UpdateSSMAgent", "ScheduleExpression": "cron(0 2 ? * SUN *)", "Targets": [ { "Key": "InstanceIds", "Values": [ "*" ] } ] } } } }

YAML

Resources: UpdateSSMAgent: Type: AWS::SSM::Association Properties: AssociationName: UpdateSSMAgent Name: AWS-UpdateSSMAgent ScheduleExpression: "cron(0 2 ? * SUN *)" Targets: - Key: InstanceIds Values: - "*"

Associate a Systems Manager document with a specific tag

The following example associates the document AWS-UpdateSSMAgent with instances that have the tag key ENV and value DEV.

JSON

{ "Resources": { "UpdateSSMAgent": { "Type": "AWS::SSM::Association", "Properties": { "AssociationName": "UpdateSSMAgent", "Name": "AWS-UpdateSSMAgent", "ScheduleExpression": "cron(0 2 ? * SUN *)", "Targets": [ { "Key": "tag:ENV", "Values": [ "DEV" ] } ] } } } }

YAML

Resources: UpdateSSMAgent: Type: AWS::SSM::Association Properties: AssociationName: UpdateSSMAgent Name: AWS-UpdateSSMAgent ScheduleExpression: "cron(0 2 ? * SUN *)" Targets: - Key: "tag:ENV" Values: - "DEV"

See Also