AWS CloudFormation
User Guide (Version )

AWS::SSM::Document

The AWS::SSM::Document resource creates an SSM document in AWS Systems Manager that defines the actions that Systems Manager performs, which you can use to set up and run commands on your instances.

Syntax

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

JSON

{ "Type" : "AWS::SSM::Document", "Properties" : { "Content" : Json, "DocumentType" : String, "Tags" : [ Tag, ... ] } }

YAML

Type: AWS::SSM::Document Properties: Content: Json DocumentType: String Tags: - Tag

Properties

Content

A valid JSON or YAML string.

Required: Yes

Type: Json

Minimum: 1

Update requires: Replacement

DocumentType

The type of document to create. Valid document types include: Command, Policy, Automation, Session, and Package.

Required: No

Type: String

Allowed Values: Automation | Command | Package | Policy | Session

Update requires: Replacement

Tags

AWS CloudFormation resource tags to apply to the document, which can help you identify and categorize these resources.

Required: No

Type: List of Tag

Maximum: 1000

Update requires: No interruption

Return Values

Ref

When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns the Systems Manager document name, such as ssm-myinstanceconfig-ABCNPH3XCAO6.

For more information about using the Ref function, see Ref.

Examples

Join a managed instance to a directory in AWS Directory Service

The following Systems Manager document joins instances to a directory in AWS Directory Service. The three runtime configuration parameters specify which directory the instance joins. You specify these parameter values when you associate the document with an instance.

JSON

"document" : { "Type" : "AWS::SSM::Document", "Properties" : { "Content" : { "schemaVersion":"1.2", "description":"Join instances to an AWS Directory Service domain.", "parameters":{ "directoryId":{ "type":"String", "description":"(Required) The ID of the AWS Directory Service directory." }, "directoryName":{ "type":"String", "description":"(Required) The name of the directory; for example, test.example.com" }, "dnsIpAddresses":{ "type":"StringList", "default":[ ], "description":"(Optional) The IP addresses of the DNS servers in the directory. Required when DHCP is not configured. Learn more at http://docs.aws.amazon.com/directoryservice/latest/simple-ad/join_get_dns_addresses.html", "allowedPattern":"((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)" } }, "runtimeConfig":{ "aws:domainJoin":{ "properties":{ "directoryId":"{{ directoryId }}", "directoryName":"{{ directoryName }}", "dnsIpAddresses":"{{ dnsIpAddresses }}" } } } } } }

YAML

document: Type: "AWS::SSM::Document" Properties: Content: schemaVersion: "1.2" description: "Join instances to an AWS Directory Service domain." parameters: directoryId: type: "String" description: "(Required) The ID of the AWS Directory Service directory." directoryName: type: "String" description: "(Required) The name of the directory; for example, test.example.com" dnsIpAddresses: type: "StringList" default: [] description: "(Optional) The IP addresses of the DNS servers in the directory. Required when DHCP is not configured. Learn more at http://docs.aws.amazon.com/directoryservice/latest/simple-ad/join_get_dns_addresses.html" allowedPattern: "((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)" runtimeConfig: aws:domainJoin: properties: directoryId: "{{ directoryId }}" directoryName: "{{ directoryName }}" dnsIpAddresses: "{{ dnsIpAddresses }}"

Associate the Systems Manager document with an instance

The following example shows how to associate the SSM document with an instance. The DocumentName property specifies the SSM document and the AssociationParameters property specifies values for the runtime configuration parameters.

JSON

"myEC2" : { "Type" : "AWS::EC2::Instance", "Properties" : { "ImageId" : {"Ref" : "myImageId"}, "InstanceType" : "t2.micro", "SsmAssociations" : [ { "DocumentName" : {"Ref" : "document"}, "AssociationParameters" : [ { "Key" : "directoryId", "Value" : [ { "Ref" : "myDirectory" } ] }, { "Key" : "directoryName", "Value" : ["testDirectory.example.com"] }, { "Key" : "dnsIpAddresses", "Value" : { "Fn::GetAtt" : ["myDirectory", "DnsIpAddresses"] } } ] } ], "IamInstanceProfile" : {"Ref" : "myInstanceProfile"}, "NetworkInterfaces" : [ { "DeviceIndex" : "0", "AssociatePublicIpAddress" : "true", "SubnetId" : {"Ref" : "mySubnet"} } ], "KeyName" : {"Ref" : "myKeyName"} } }

YAML

myEC2: Type: "AWS::EC2::Instance" Properties: ImageId: Ref: "myImageId" InstanceType: "t2.micro" SsmAssociations: - DocumentName: Ref: "document" AssociationParameters: - Key: "directoryId" Value: - Ref: "myDirectory" - Key: "directoryName" Value: - "testDirectory.example.com" - Key: "dnsIpAddresses" Value: Fn::GetAtt: - "myDirectory" - "DnsIpAddresses" IamInstanceProfile: Ref: "myInstanceProfile" NetworkInterfaces: - DeviceIndex: "0" AssociatePublicIpAddress: "true" SubnetId: Ref: "mySubnet" KeyName: Ref: "myKeyName"

See Also