AWS::SSM::Document - AWS CloudFormation

AWS::SSM::Document

The AWS::SSM::Document resource creates a Systems Manager (SSM) document in AWS Systems Manager. This document defines the actions that Systems Manager performs on your AWS resources.

Syntax

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

JSON

{ "Type" : "AWS::SSM::Document", "Properties" : { "Attachments" : [ AttachmentsSource, ... ], "Content" : Json, "DocumentFormat" : String, "DocumentType" : String, "Name" : String, "Requires" : [ DocumentRequires, ... ], "Tags" : [ Tag, ... ], "TargetType" : String, "VersionName" : String } }

YAML

Type: AWS::SSM::Document Properties: Attachments: - AttachmentsSource Content: Json DocumentFormat: String DocumentType: String Name: String Requires: - DocumentRequires Tags: - Tag TargetType: String VersionName: String

Properties

Attachments

A list of key and value pairs that describe attachments to a version of a document.

Required: No

Type: List of AttachmentsSource

Maximum: 20

Update requires: Replacement

Content

The content for the new SSM document in JSON or YAML format.

Required: Yes

Type: Json

Minimum: 1

Update requires: Replacement

DocumentFormat

Specify the document format for the request. The document format can be JSON, YAML, or TEXT. JSON is the default format.

Required: No

Type: String

Allowed values: JSON | TEXT | YAML

Update requires: Replacement

DocumentType

The type of document to create.

Allowed Values: ApplicationConfigurationSchema | Automation | ChangeCalendar | Command | DeploymentStrategy | Package | Policy | Session

Required: No

Type: String

Update requires: Replacement

Name

A name for the Systems Manager document.

Important

You can't use the following strings as document name prefixes. These are reserved by AWS for use as document name prefixes:

  • aws-

  • amazon

  • amzn

Required: No

Type: String

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

Update requires: Replacement

Requires

A list of SSM documents required by a document. This parameter is used exclusively by AWS AppConfig. When a user creates an AppConfig configuration in an SSM document, the user must also specify a required document for validation purposes. In this case, an ApplicationConfiguration document requires an ApplicationConfigurationSchema document for validation purposes. For more information, see AWS AppConfig in the AWS Systems Manager User Guide.

Required: No

Type: List of DocumentRequires

Update requires: Replacement

Tags

AWS CloudFormation resource tags to apply to the document. Use tags to help you identify and categorize resources.

Required: No

Type: List of Tag

Maximum: 1000

Update requires: No interruption

TargetType

Specify a target type to define the kinds of resources the document can run on. For example, to run a document on EC2 instances, specify the following value: /AWS::EC2::Instance. If you specify a value of '/' the document can run on all types of resources. If you don't specify a value, the document can't run on any resources. For a list of valid resource types, see AWS resource and property types reference in the AWS CloudFormation User Guide.

Required: No

Type: String

Maximum: 200

Pattern: ^\/[\w\.\-\:\/]*$

Update requires: Replacement

VersionName

An optional field specifying the version of the artifact you are creating with the document. For example, "Release 12, Update 6". This value is unique across all versions of a document, and cannot be changed.

Required: No

Type: String

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

Update requires: Replacement

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 MyNewSSMDocument.

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

Examples

Create a document that runs commands on an EC2 Linux instance

The following SSM document runs the commands you specify on your target EC2 Linux instance. You specify the commands parameter value when you run the document using Run Command.

YAML

document: Type: AWS::SSM::Document Properties: Content: schemaVersion: '2.2' description: 'Run a script on Linux instances.' parameters: commands: type: String description: "(Required) The commands to run or the path to an existing script on the instance." default: 'echo Hello World' mainSteps: - action: aws:runShellScript name: runCommands inputs: timeoutSeconds: '60' runCommand: - "{{ commands }}" DocumentType: Command Name: 'CFN_2.2_command_example'

JSON

"document": { "Type": "AWS::SSM::Document", "Properties": { "Content": { "schemaVersion": "2.2", "description": "Run a script on Linux instances.", "parameters": { "commands": { "type": "String", "description": "(Required) The commands to run or the path to an existing script on the instance.", "default": "echo Hello World" } }, "mainSteps": [ { "action": "aws:runShellScript", "name": "runCommands", "inputs": { "timeoutSeconds": "60", "runCommand": [ "{{ commands }}" ] } } ] }, "DocumentType": "Command", "Name": "CFN_2.2_command_ex" } }

Join a managed instance to a directory in AWS Directory Service

The following SSM 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.

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. For more information, see https://docs.aws.amazon.com/directoryservice/latest/admin-guide/simple_ad_dns.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 }}"

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. For more information, see https://docs.aws.amazon.com/directoryservice/latest/admin-guide/simple_ad_dns.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 an SSM document with an instance

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

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

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" } } }

See also