AWS::SSM::Document

聚焦模式

AWS::SSM::Document - AWS CloudFormation

Syntax Properties Return values Examples See also

此页面尚未翻译为您的语言。请求翻译

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.

Note

This resource does not support AWS CloudFormation drift detection.

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,
      "UpdateMethod" : 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
  UpdateMethod: String
  VersionName: String

Properties

Attachments

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

Required: No

Type: Array of AttachmentsSource

Minimum: 0

Maximum: 20

Update requires: Some interruptions

Content

The content for the new SSM document in JSON or YAML. For more information about the schemas for SSM document content, see SSM document schema features and examples in the AWS Systems Manager User Guide.

Note

This parameter also supports String data types.

Required: Yes

Type: Json

Minimum: 1

Update requires: Some interruptions

DocumentFormat

Specify the document format for the request. JSON is the default format.

Required: No

Type: String

Allowed values: YAML | JSON | TEXT

Update requires: Some interruptions

DocumentType

The type of document to create.

Required: No

Type: String

Update requires: Replacement

Name

A name for the SSM 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
AWSEC2
AWSConfigRemediation
AWSSupport

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 AWS 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 What is AWS AppConfig? in the AWS AppConfig User Guide.

Required: No

Type: Array of DocumentRequires

Minimum: 1

Update requires: Some interruptions

Tags

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

Required: No

Type: Array 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

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

Update requires: Some interruptions

UpdateMethod

If the document resource you specify in your template already exists, this parameter determines whether a new version of the existing document is created, or the existing document is replaced. Replace is the default method. If you specify NewVersion for the UpdateMethod parameter, and the Name of the document does not match an existing resource, a new document is created. When you specify NewVersion, the default version of the document is changed to the newly created version.

Required: No

Type: String

Allowed values: Replace | NewVersion

Update requires: No interruption

VersionName

An optional field specifying the version of the artifact you are creating with the document. For example, Release12.1. This value is unique across all versions of a document, and can't be changed.

Required: No

Type: String

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

Update requires: Some interruptions

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 an Automation runbook that runs commands on an EC2 Linux instance
Create a document that runs commands on an EC2 Linux instance
Join a managed instance to a directory in AWS Directory Service
Associate an SSM document with an instance
Create a Systems Manager document for Session Manager preferences
Create a Systems Manager document with JSON content
Create a Systems Manager Distributor package
Create a Systems Manager Change Calendar document

Create an Automation runbook that runs commands on an EC2 Linux instance

The following runbook runs the commands you specify on your target Amazon EC2 Linux instance. You specify the commands parameter value when starting the runbook.

YAML


document: 
    Type: AWS::SSM::Document
    Properties:
      Content:
        schemaVersion: '0.3'
        description: 'Run a script on Linux instances.'
        parameters:
          AutomationAssumeRole:
            type: String
            description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf.
            default: ''
          commands:
            type: String
            description: "(Required) The commands to run or the path to an existing script on the instance."
            default: 'echo Hello World'
          InstanceId:
            type: String
            description: "(Required) The instance ID you want to run commands on."
            default: ''
        mainSteps:
        - name: sayHello
          action: 'aws:runCommand'
          inputs:
            DocumentName: AWS-RunShellScript
            InstanceIds:
              - '{{InstanceId}}'
            Parameters:
              commands:
              - "{{ commands }}"
      DocumentFormat: YAML
      DocumentType: Automation
      Name: 'CFN_runbook_example'

JSON


"document": {
         "Type": "AWS::SSM::Document",
         "Properties": {
            "Content": {
               "schemaVersion": "0.3",
               "description": "Run a script on Linux instances.",
               "parameters": {
                  "AutomationAssumeRole": {
                     "type": "String",
                     "description": "(Optional) The ARN of the role that allows Automation to perform the actions on your behalf.",
                     "default": ""
                  },
                  "commands": {
                     "type": "String",
                     "description": "(Required) The commands to run or the path to an existing script on the instance.",
                     "default": "echo Hello World"
                  },
                  "InstanceId": {
                     "type": "String",
                     "description": "(Required) The instance ID you want to run commands on.",
                     "default": ""
                  }
               },
               "mainSteps": [
                  {
                     "name": "sayHello",
                     "action": "aws:runCommand",
                     "inputs": {
                        "DocumentName": "AWS-RunShellScript",
                        "Parameters": {
                           "InstanceIds": [
                              "{{InstanceId}}"
                           ],
                           "commands": [
                              "{{ commands }}"
                           ]
                        }
                     }
                  }
               ]
            },
            "DocumentType": "Automation",
            "Name": "CFN_runbook_example"
         }
      }

Create a document that runs commands on an EC2 Linux instance

The following SSM document runs the commands you specify on your target Amazon 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 }}"
    DocumentFormat: YAML
    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"
        }
    }
}

Create a Systems Manager document for Session Manager preferences

The following example creates a Systems Manager Session type document for Session Manager preferences. Before using this example template replace the placeholder values.

JSON


{
   "Resources":{
      "SessionPreferencesDocument":{
         "Type":"AWS::SSM::Document",
         "Properties":{
            "Name":"SSM-SessionManagerRunShell",
            "Content":{
               "schemaVersion":"1.0",
               "description":"Document to hold regional settings for Session Manager",
               "sessionType":"Standard_Stream",
               "inputs":{
                  "s3BucketName":"amzn-s3-demo-bucket",
                  "s3KeyPrefix":"amzn-s3-demo-bucket-prefix",
                  "s3EncryptionEnabled":true,
                  "cloudWatchLogGroupName":"MyLogGroupName",
                  "cloudWatchEncryptionEnabled":true,
                  "cloudWatchStreamingEnabled":false,
                  "kmsKeyId":"331dba25-425c-446c-abf9-daf42EXAMPLE",
                  "runAsEnabled":false,
                  "runAsDefaultUser":"MyDefaultRunAsUser",
                  "idleSessionTimeout":"20",
                  "shellProfile":{
                     "windows":"my-windowscommands",
                     "linux":"my-linux-commands"
                  }
               }
            },
            "DocumentType":"Session"
         }
      }
   },
   "Outputs":{
      "DocumentName":{
         "Description":"Session Manager preferences document",
         "Value":"SSM-SessionManagerRunShell"
      }
   }
}

YAML


Resources:
  SessionPreferencesDocument:
    Type: AWS::SSM::Document
    Properties:
      Name: SSM-SessionManagerRunShell
      Content:
        schemaVersion: '1.0'
        description: Document to hold regional settings for Session Manager
        sessionType: Standard_Stream
        inputs:
          s3BucketName: 'amzn-s3-demo-bucket'
          s3KeyPrefix: 'amzn-s3-demo-bucket-prefix'
          s3EncryptionEnabled: true
          cloudWatchLogGroupName: 'MyLogGroupName'
          cloudWatchEncryptionEnabled: true
          cloudWatchStreamingEnabled: false
          kmsKeyId: '"331dba25-425c-446c-abf9-daf42EXAMPLE"'
          runAsEnabled: false
          runAsDefaultUser: 'MyDefaultRunAsUser'
          idleSessionTimeout: '20'
          shellProfile:
            windows: my-windows-commands
            linux: my-linux-commands
      DocumentFormat: YAML
      DocumentType: Session
Outputs:
  DocumentName:
    Description: "Session Manager preferences document"
    Value: SSM-SessionManagerRunShell

Create a Systems Manager document with JSON content

The following example creates a new Systems Manager command document with JSON content.

JSON


{
   "Type":"AWS::SSM::Document",
   "Properties":{
      "Content":"{\"schemaVersion\": \"2.2\",  \"description\": \"Command Document Example JSON\nTemplate\",  \"parameters\": {    \"Message\": {      \"type\": \"String\", \"description\":\n\"Example\",      \"default\": \"Hello World\"    }  },  \"mainSteps\": [    { \"action\":\n\"aws:runPowerShellScript\",      \"name\": \"example\",      \"inputs\": {        \"runCommand\":\n[ \"Write-Output {{Message}}\" ]      }    }  ]}",
      "DocumentType":"Command",
      "DocumentFormat":"JSON"
   }
}

YAML


--- 
Type: "AWS::SSM::Document"
Properties: 
  Content: "{\"schemaVersion\": \"2.2\",  \"description\": \"Command Document Example JSON Template\",  \"parameters\": {    \"Message\": {      \"type\": \"String\", \"description\": \"Example\",      \"default\": \"Hello World\"    }  },  \"mainSteps\": [    { \"action\": \"aws:runPowerShellScript\",      \"name\": \"example\",      \"inputs\": {        \"runCommand\": [ \"Write-Output {{Message}}\" ]      }    }  ]}"
  DocumentFormat: JSON
  DocumentType: Command

Create a Systems Manager Distributor package

The following example creates a new Systems Manager Distributor package.

JSON


{
        "Resources": {
        "ExamplePackageDocument": {
            "Type": "AWS::SSM::Document",
            "Properties": {
                "Content": "{\"files\": {\"NewPackage_WINDOWS.zip\": {\"checksums\": {\"sha256\": \"36aeb0ec2c706013cf8c68163459678f7f6daa9489cd3f91d52799331EXAMPLE\"}}}, \"publisher\": \"MyPublisherName\", \"schemaVersion\": \"2.0\", \"packages\": {\"_any\": {\"_any\": {\"x86_64\": {\"file\": \"MyNewPackage_WINDOWS.zip\"}}}}, \"version\": \"1.0\"}",
                "DocumentType": "Package",
                "Attachments": [
                    {
                        "Key": "SourceUrl",
                        "Values": [
                            "s3://example-package-path/valid-package"
                        ]
                    }
                ]
            }
        }
    }
}

YAML


Resources:
  ExamplePackageDocument:
    Type: AWS::SSM::Document
    Properties:
      Content: '{\"files\": {\"MyNewPackage_WINDOWS.zip\": {\"checksums\":
        {\"sha256\": \"36aeb0ec2c706013cf8c68163459678f7f6daa9489cd3f91d52799331EXAMPLE\"}}},
        \"publisher\": \"MyPublisherName\", \"schemaVersion\":
        \"2.0\", \"packages\": {\"_any\": {\"_any\": {\"x86_64\": {\"file\": \"MyNewPackage_WINDOWS.zip\"}}}},
        \"version\": \"1.0\"}'
      DocumentType: Package
      Attachments:
      - Key: SourceUrl
        Values:
        - "s3://example-package-path/valid-package"

Create a Systems Manager Change Calendar document

The following example creates a new Systems Manager Change Calendar document.

JSON


{
   "Resources":{
      "ExampleChangeCalendarDocument":{
         "Type":"AWS::SSM::Document",
         "Properties":{
            "Content":"BEGIN:VCALENDAR\r\nPRODID:-//AWS//Change Calendar 1.0//EN\r\nVERSION:2.0\r\nX-CALENDAR-TYPE:DEFAULT_OPEN\r\nX-WR-CALDESC:test\r\nBEGIN:VTODO\r\nDTSTAMP:20200320T004207Z\r\nUID:3b5af39a-d0b3-4049-a839-d7bb8af01f92\r\nSUMMARY:Add events to this calendar.\r\nEND:VTODO\r\nEND:VCALENDAR\r\n",
            "DocumentType":"ChangeCalendar",
            "DocumentFormat":"TEXT"
         }
      }
   }
}

YAML


Resources:
  ExampleChangeCalendarDocument:
    Type: 'AWS::SSM::Document'
    Properties:
      Content: "BEGIN:VCALENDAR\r\nPRODID:-//AWS//Change Calendar 1.0//EN\r\nVERSION:2.0\r\nX-CALENDAR-TYPE:DEFAULT_OPEN\r\nX-WR-CALDESC:test\r\nBEGIN:VTODO\r\nDTSTAMP:20200320T004207Z\r\nUID:3b5af39a-d0b3-4049-a839-d7bb8af01f92\r\nSUMMARY:Add events to this calendar.\r\nEND:VTODO\r\nEND:VCALENDAR\r\n"
      DocumentType: ChangeCalendar
      DocumentFormat: TEXT

选择您的 Cookie 首选项

AWS::SSM::Document

Note

Syntax

JSON

YAML

Properties

Note

Important

Return values

Ref

Examples

Create an Automation runbook that runs commands on an EC2 Linux instance

YAML

JSON

Create a document that runs commands on an EC2 Linux instance

YAML

JSON

Join a managed instance to a directory in AWS Directory Service

YAML

JSON

Associate an SSM document with an instance

YAML

JSON

Create a Systems Manager document for Session Manager preferences

JSON

YAML

Create a Systems Manager document with JSON content

JSON

YAML

Create a Systems Manager Distributor package

JSON

YAML

Create a Systems Manager Change Calendar document

JSON

YAML

See also

本页内容

此页内容对您是否有帮助？

下一主题：

上一主题：

需要帮助吗？