documents

Creates, updates, deletes, gets or lists a documents resource.

Overview

Name	`documents`
Type	Resource
Id	`aws.ssm.documents`

Fields

The following fields are returned by SELECT queries:

describe_document

Name	Datatype	Description
`approved_version`	`string`	The version of the document currently approved for use in the organization. (pattern: <code>([$]LATEST\|[$]DEFAULT\|^[1-9][0-9]*$)</code>)
`attachments_information`	`array`	Details about the document attachments, including names, locations, sizes, and so on.
`author`	`string`	The user in your organization who created the document.
`category`	`array`	The classification of a document to help you identify and categorize its use.
`category_enum`	`array`	The value that identifies a document's category.
`created_date`	`string (date-time)`	The date when the document was created.
`default_version`	`string`	The default version. (pattern: <code>([$]LATEST\|[$]DEFAULT\|^[1-9][0-9]*$)</code>)
`description`	`string`	A description of the document.
`display_name`	`string`	The friendly name of the SSM document. This value can differ for each version of the document. If you want to update this value, see UpdateDocument. (pattern: <code>^[\w.-:/ ]*$</code>)
`document_format`	`string`	The document format, either JSON or YAML. (YAML, JSON, TEXT)
`document_type`	`string`	The type of document. (Command, Policy, Automation, Session, Package, ApplicationConfiguration, ApplicationConfigurationSchema, DeploymentStrategy, ChangeCalendar, Automation.ChangeTemplate, ProblemAnalysis, ProblemAnalysisTemplate, CloudFormation, ConformancePackTemplate, QuickSetup, ManualApprovalPolicy, AutoApprovalPolicy)
`document_version`	`string`	The document version. (pattern: <code>([$]LATEST\|[$]DEFAULT\|^[1-9][0-9]*$)</code>)
`hash`	`string`	The Sha256 or Sha1 hash created by the system when the document was created. Sha1 hashes have been deprecated.
`hash_type`	`string`	The hash type of the document. Valid values include Sha256 or Sha1. Sha1 hashes have been deprecated. (Sha256, Sha1)
`latest_version`	`string`	The latest version of the document. (pattern: <code>([$]LATEST\|[$]DEFAULT\|^[1-9][0-9]*$)</code>)
`name`	`string`	The name of the SSM document. (pattern: <code>^[a-zA-Z0-9_-.:/]{3,128}$</code>)
`owner`	`string`	The Amazon Web Services user that created the document.
`parameters`	`array`	A description of the parameters for a document.
`pending_review_version`	`string`	The version of the document that is currently under review. (pattern: <code>([$]LATEST\|[$]DEFAULT\|^[1-9][0-9]*$)</code>)
`platform_types`	`array`	The list of operating system (OS) platforms compatible with this SSM document.
`requires`	`array`	A list of SSM documents required by a document. For example, an ApplicationConfiguration document requires an ApplicationConfigurationSchema document.
`review_information`	`array`	Details about the review of a document.
`review_status`	`string`	The current status of the review. (APPROVED, NOT_REVIEWED, PENDING, REJECTED)
`schema_version`	`string`	The schema version. (pattern: <code>([0-9]+).([0-9]+)</code>)
`sha_1`	`string`	The SHA1 hash of the document, which you can use for verification.
`status`	`string`	The status of the SSM document. (Creating, Active, Updating, Deleting, Failed)
`status_information`	`string`	A message returned by Amazon Web Services Systems Manager that explains the Status value. For example, a Failed status might be explained by the StatusInformation message, "The specified S3 bucket doesn't exist. Verify that the URL of the S3 bucket is correct."
`tags`	`array`	The tags, or metadata, that have been applied to the document.
`target_type`	`string`	The target type which defines the kinds of resources the document can run on. For example, /AWS::EC2::Instance. For a list of valid resource types, see Amazon Web Services resource and property types reference in the CloudFormation User Guide. (pattern: <code>^/[\w.-:/]*$</code>)
`version_name`	`string`	The version of the artifact associated with the document. (pattern: <code>^[a-zA-Z0-9_-.]{1,128}$</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Description
`describe_document`	`select`	`region`	Describes the specified Amazon Web Services Systems Manager document (SSM document).
`create_document`	`insert`	`region`	Creates a Amazon Web Services Systems Manager (SSM document). An SSM document defines the actions that Systems Manager performs on your managed nodes. For more information about SSM documents, including information about supported schemas, features, and syntax, see Amazon Web Services Systems Manager Documents in the Amazon Web Services Systems Manager User Guide.
`update_document_default_version`	`update`	`region`, `DocumentVersion`	Set the default version of a document. If you change a document version for a State Manager association, Systems Manager immediately runs the association unless you previously specifed the apply-only-at-cron-interval parameter.
`update_document_metadata`	`update`	`region`, `DocumentReviews`	Amazon Web Services Systems Manager Change Manager is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see Amazon Web Services Systems Manager Change Manager availability change. Updates information related to approval reviews for a specific version of a change template in Change Manager.
`update_document`	`update`	`region`	Updates one or more values for an SSM document.
`delete_document`	`delete`	`region`	Deletes the Amazon Web Services Systems Manager document (SSM document) and all managed node associations to the document. Before you delete the document, we recommend that you use DeleteAssociation to disassociate all managed nodes that are associated with the document.
`get_document`	`exec`	`region`	Gets the contents of the specified Amazon Web Services Systems Manager document (SSM document).
`list_documents`	`exec`	`region`	Returns all Systems Manager (SSM) documents in the current Amazon Web Services account and Amazon Web Services Region. You can limit the results of this request by using a filter.
`start_change_request_execution`	`exec`	`region`, `DocumentName`, `Runbooks`	Amazon Web Services Systems Manager Change Manager is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see Amazon Web Services Systems Manager Change Manager availability change. Creates a change request for Change Manager. The Automation runbooks specified in the change request run only after all required approvals for the change request have been received.
`start_execution_preview`	`exec`	`region`, `DocumentName`	Initiates the process of creating a preview showing the effects that running a specified Automation runbook would have on the targeted resources.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`region`	`string`	AWS region (default: us-east-1)

`SELECT` examples

describe_document

Describes the specified Amazon Web Services Systems Manager document (SSM document).

SELECT
approved_version,
attachments_information,
author,
category,
category_enum,
created_date,
default_version,
description,
display_name,
document_format,
document_type,
document_version,
hash,
hash_type,
latest_version,
name,
owner,
parameters,
pending_review_version,
platform_types,
requires,
review_information,
review_status,
schema_version,
sha_1,
status,
status_information,
tags,
target_type,
version_name
FROM aws.ssm.documents
WHERE region = '{{ region }}' -- required
;

`INSERT` examples

create_document
Manifest

Creates a Amazon Web Services Systems Manager (SSM document). An SSM document defines the actions that Systems Manager performs on your managed nodes. For more information about SSM documents, including information about supported schemas, features, and syntax, see Amazon Web Services Systems Manager Documents in the Amazon Web Services Systems Manager User Guide.

INSERT INTO aws.ssm.documents (
Content,
Requires,
Attachments,
Name,
DisplayName,
VersionName,
DocumentType,
DocumentFormat,
TargetType,
Tags,
region
)
SELECT 
'{{ Content }}',
'{{ Requires }}',
'{{ Attachments }}',
'{{ Name }}',
'{{ DisplayName }}',
'{{ VersionName }}',
'{{ DocumentType }}',
'{{ DocumentFormat }}',
'{{ TargetType }}',
'{{ Tags }}',
'{{ region }}'
RETURNING
document_description
;

# Description fields are for documentation purposes
- name: documents
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the documents resource.
  - name: Content
    value: "{{ Content }}"
    description: |
      The content for the new SSM document in JSON or YAML format. The content of the document must not exceed 64KB. This quota also includes the content specified for input parameters at runtime. We recommend storing the contents for your new document in an external JSON or YAML file and referencing the file in a command. For examples, see the following topics in the Amazon Web Services Systems Manager User Guide. Create an SSM document (console) Create an SSM document (command line) Create an SSM document (API)
  - name: Requires
    description: |
      A list of SSM documents required by a document. This parameter is used exclusively by 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 What is AppConfig? in the AppConfig User Guide.
    value:
      - Name: "{{ Name }}"
        Version: "{{ Version }}"
        RequireType: "{{ RequireType }}"
        VersionName: "{{ VersionName }}"
  - name: Attachments
    description: |
      A list of key-value pairs that describe attachments to a version of a document.
    value:
      - Key: "{{ Key }}"
        Values: "{{ Values }}"
        Name: "{{ Name }}"
  - name: Name
    value: "{{ Name }}"
    description: |
      A name for the SSM document. You can't use the following strings as document name prefixes. These are reserved by Amazon Web Services for use as document name prefixes: aws amazon amzn AWSEC2 AWSConfigRemediation AWSSupport
  - name: DisplayName
    value: "{{ DisplayName }}"
    description: |
      An optional field where you can specify a friendly name for the SSM document. This value can differ for each version of the document. You can update this value at a later time using the UpdateDocument operation.
  - name: VersionName
    value: "{{ VersionName }}"
    description: |
      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.
  - name: DocumentType
    value: "{{ DocumentType }}"
    description: |
      The type of document to create. The DeploymentStrategy document type is an internal-use-only document type reserved for AppConfig.
    valid_values: ['Command', 'Policy', 'Automation', 'Session', 'Package', 'ApplicationConfiguration', 'ApplicationConfigurationSchema', 'DeploymentStrategy', 'ChangeCalendar', 'Automation.ChangeTemplate', 'ProblemAnalysis', 'ProblemAnalysisTemplate', 'CloudFormation', 'ConformancePackTemplate', 'QuickSetup', 'ManualApprovalPolicy', 'AutoApprovalPolicy']
  - name: DocumentFormat
    value: "{{ DocumentFormat }}"
    description: |
      Specify the document format for the request. The document format can be JSON, YAML, or TEXT. JSON is the default format.
    valid_values: ['YAML', 'JSON', 'TEXT']
  - name: TargetType
    value: "{{ TargetType }}"
    description: |
      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 Amazon Web Services resource and property types reference in the CloudFormation User Guide.
  - name: Tags
    description: |
      Optional metadata that you assign to a resource. Tags enable you to categorize a resource in different ways, such as by purpose, owner, or environment. For example, you might want to tag an SSM document to identify the types of targets or the environment where it will run. In this case, you could specify the following key-value pairs: Key=OS,Value=Windows Key=Environment,Value=Production To add tags to an existing SSM document, use the AddTagsToResource operation.
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"

`UPDATE` examples

update_document_default_version
update_document_metadata
update_document

Set the default version of a document. If you change a document version for a State Manager association, Systems Manager immediately runs the association unless you previously specifed the apply-only-at-cron-interval parameter.

UPDATE aws.ssm.documents
SET 
Name = '{{ Name }}',
DocumentVersion = '{{ DocumentVersion }}'
WHERE 
region = '{{ region }}' --required
AND DocumentVersion = '{{ DocumentVersion }}' --required
RETURNING
description;

Amazon Web Services Systems Manager Change Manager is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see Amazon Web Services Systems Manager Change Manager availability change. Updates information related to approval reviews for a specific version of a change template in Change Manager.

UPDATE aws.ssm.documents
SET 
Name = '{{ Name }}',
DocumentVersion = '{{ DocumentVersion }}',
DocumentReviews = '{{ DocumentReviews }}'
WHERE 
region = '{{ region }}' --required
AND DocumentReviews = '{{ DocumentReviews }}' --required;

Updates one or more values for an SSM document.

UPDATE aws.ssm.documents
SET 
Content = '{{ Content }}',
Attachments = '{{ Attachments }}',
Name = '{{ Name }}',
DisplayName = '{{ DisplayName }}',
VersionName = '{{ VersionName }}',
DocumentVersion = '{{ DocumentVersion }}',
DocumentFormat = '{{ DocumentFormat }}',
TargetType = '{{ TargetType }}'
WHERE 
region = '{{ region }}' --required
RETURNING
document_description;

`DELETE` examples

delete_document

Deletes the Amazon Web Services Systems Manager document (SSM document) and all managed node associations to the document. Before you delete the document, we recommend that you use DeleteAssociation to disassociate all managed nodes that are associated with the document.

DELETE FROM aws.ssm.documents
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

get_document
list_documents
start_change_request_execution
start_execution_preview

Gets the contents of the specified Amazon Web Services Systems Manager document (SSM document).

EXEC aws.ssm.documents.get_document 
@region='{{ region }}' --required 
@@json=
'{
"Name": "{{ Name }}", 
"VersionName": "{{ VersionName }}", 
"DocumentVersion": "{{ DocumentVersion }}", 
"DocumentFormat": "{{ DocumentFormat }}"
}'
;

Returns all Systems Manager (SSM) documents in the current Amazon Web Services account and Amazon Web Services Region. You can limit the results of this request by using a filter.

EXEC aws.ssm.documents.list_documents 
@region='{{ region }}' --required 
@@json=
'{
"DocumentFilterList": "{{ DocumentFilterList }}", 
"Filters": "{{ Filters }}", 
"MaxResults": {{ MaxResults }}, 
"NextToken": "{{ NextToken }}"
}'
;

Amazon Web Services Systems Manager Change Manager is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see Amazon Web Services Systems Manager Change Manager availability change. Creates a change request for Change Manager. The Automation runbooks specified in the change request run only after all required approvals for the change request have been received.

EXEC aws.ssm.documents.start_change_request_execution 
@region='{{ region }}' --required 
@@json=
'{
"ScheduledTime": "{{ ScheduledTime }}", 
"DocumentName": "{{ DocumentName }}", 
"DocumentVersion": "{{ DocumentVersion }}", 
"Parameters": "{{ Parameters }}", 
"ChangeRequestName": "{{ ChangeRequestName }}", 
"ClientToken": "{{ ClientToken }}", 
"AutoApprove": {{ AutoApprove }}, 
"Runbooks": "{{ Runbooks }}", 
"Tags": "{{ Tags }}", 
"ScheduledEndTime": "{{ ScheduledEndTime }}", 
"ChangeDetails": "{{ ChangeDetails }}"
}'
;

Initiates the process of creating a preview showing the effects that running a specified Automation runbook would have on the targeted resources.

EXEC aws.ssm.documents.start_execution_preview 
@region='{{ region }}' --required 
@@json=
'{
"DocumentName": "{{ DocumentName }}", 
"DocumentVersion": "{{ DocumentVersion }}", 
"ExecutionInputs": "{{ ExecutionInputs }}"
}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​

Lifecycle Methods​