使用文档 - Amazon Systems Manager
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

使用文档

本节包含有关如何使用 SSM 文档的信息。

在 State Manager 关联中使用 SSM 文档

如果创建适用于 State Manager (Amazon Systems Manager 的一种功能)的 SSM 文档,在将文档添加到系统后,必须将该文档与托管实例相关联。有关更多信息,请参阅 在 Systems Manager 中使用关联。

在关联中使用 State Manager SSM 文档时,请记住以下详细信息。

  • 通过创建使用不同文档的不同 State Manager 关联,您可以将多个文档分配给一个目标。

  • 如果创建的文档含有互相冲突的插件(例如,加入域的插件和从域中删除的插件),则最终状态取决于最后运行的插件。State Manager 不会验证文档中的命令或插件的逻辑顺序或合理性。

  • 处理文档时,系统首先应用实例关联,然后应用标记实例组关联。如果实例处于多个标记实例组中,则对应标记实例组的文档不会以任何特定顺序运行。如果实例通过其实例 ID 直接对应多个文档,那么也不存在特定的执行顺序。

  • 如果您更改 State Manager 的 SSM 策略文档的默认版本,则下次 Systems Manager 将关联应用到实例时,使用该文档的所有关联都将开始使用新的默认版本。

  • 如果您使用已与您共享的 SSM 文档创建关联,随后,所有者将停止共享文档,您的关联将不再有权访问该文档。但是,如果所有者后来再次与您共享同一个 SSM 文档,您的关联将自动重新映射到该文档。

比较 SSM 文档版本

您可以在 Systems Manager 文档控制台中比较 Amazon Systems Manager (SSM) 文档版本之间的内容差异。比较 SSM 文档的版本时,会突出显示版本内容之间的差异。

比较 SSM 文档内容(控制台)
  1. 访问 https://console.aws.amazon.com/systems-manager/,打开 Amazon Systems Manager 控制台。

  2. 在导航窗格中,选择文档

  3. 在文档列表中,选择要比较其内容的文档。

  4. 在存储库的内容选项卡上,选择比较版本,然后选择要将内容与其进行比较的文档版本。

创建 SSM 文档(控制台)

编写 SSM 文档内容 中所述,为自定义 SSM 文档创建内容后,您可以通过 Systems Manager 控制台使用您的内容创建 SSM 文档。

创建 SSM 文档(控制台)
  1. 访问 https://console.aws.amazon.com/systems-manager/,打开 Amazon Systems Manager 控制台。

  2. 在导航窗格中,选择文档

  3. 选择 Create command or session (创建命令或会话)

  4. 输入文档的描述性名称

  5. (可选)对于 Target type (目标类型),指定可以运行文档的资源类型。

  6. 文档类型列表中,选择您要创建的文档类型。

  7. 删除 Content (内容) 字段中的方括号,然后将您之前创建的文档内容粘贴到这里。

  8. (可选)在 Document tags (文档标签) 部分,将一个或多个标签键名称/值对应用于文档。

    标签是您分配给资源的可选元数据。标签可让您按各种标准(如用途、所有者或环境)对资源进行分类。例如,您可能希望标记文档以标识它运行的任务类型、它指向的操作系统的类型以及它在其中运行的环境。在这种情况下,您可以指定以下键名/键值对:

    • Key=TaskType,Value=MyConfigurationUpdate

    • Key=OS,Value=AMAZON_LINUX_2

    • Key=Environment,Value=Production

    有关标记 Systems Manager 资源的更多信息,请参阅 标记 Systems Manager 资源

  9. 选择创建文档以保存文档。

创建 SSM 文档(命令行)

编写 SSM 文档内容 中所述,为自定义 Amazon Systems Manager (SSM) 文档创建内容后,您可以通过 Amazon Command Line Interface (Amazon CLI) 或 Amazon Tools for PowerShell 使用您的内容创建 SSM 文档。如下面的命令所示。

开始前的准备工作

安装并配置 Amazon Tools for PowerShell (Amazon CLI)(如果尚未执行该操作)。有关信息,请参阅安装或更新 Amazon CLI 的最新版本以及安装 Amazon Tools for PowerShell

运行以下命令。将每个示例资源占位符替换为您自己的信息。

Linux & macOS
aws ssm create-document \ --content file://path/to/file/documentContent.json \ --name "document-name" \ --document-type "Command" \ --tags "Key=tag-key,Value=tag-value"
Windows
aws ssm create-document ^ --content file://C:\path\to\file\documentContent.json ^ --name "document-name" ^ --document-type "Command" ^ --tags "Key=tag-key,Value=tag-value"
PowerShell
$json = Get-Content -Path "C:\path\to\file\documentContent.json" | Out-String New-SSMDocument ` -Content $json ` -Name "document-name" ` -DocumentType "Command" ` -Tags "Key=tag-key,Value=tag-value"

如果成功,该命令将返回类似于以下内容的响应。

{
"DocumentDescription":{
  "CreatedDate":1.585061751738E9,
  "DefaultVersion":"1",
  "Description":"MyCustomDocument",
  "DocumentFormat":"JSON",
  "DocumentType":"Command",
  "DocumentVersion":"1",
  "Hash":"0d3d879b3ca072e03c12638d0255ebd004d2c65bd318f8354fcde820dEXAMPLE",
  "HashType":"Sha256",
  "LatestVersion":"1",
  "Name":"Example",
  "Owner":"111122223333",
  "Parameters":[
     --truncated--
  ],
  "PlatformTypes":[
     "Windows",
     "Linux"
  ],
  "SchemaVersion":"0.3",
  "Status":"Creating",
  "Tags": [
        {
            "Key": "Purpose",
            "Value": "Test"
        }
    ]
}
}

创建 SSM 文档 (API)

编写 SSM 文档内容 中所述,为自定义 Amazon Systems Manager (SSM) 文档创建内容后,您可以使用首选的开发工具包调用 Amazon Systems Manager CreateDocument API 操作以使用您的内容创建 SSM 文档。Content 请求参数的 JSON 或 YAML 字符串通常是从文件中读取的。以下示例函数使用适用于 Python、Go 和 Java 的开发工具包创建 SSM 文档。

Python
import boto3 ssm = boto3.client('ssm') filepath = '/path/to/file/documentContent.yaml' def createDocumentApiExample(): with open(filepath) as openFile: documentContent = openFile.read() createDocRequest = ssm.create_document( Content = documentContent, Name = 'createDocumentApiExample', DocumentType = 'Automation', DocumentFormat = 'YAML' ) print(createDocRequest) createDocumentApiExample()
Go
package main import ( "github.com/aws/aws-sdk-go/aws" "github.com/aws/aws-sdk-go/aws/session" "github.com/aws/aws-sdk-go/service/ssm" "fmt" "io/ioutil" "log" ) func main() { openFile, err := ioutil.ReadFile("/path/to/file/documentContent.yaml") if err != nil { log.Fatal(err) } documentContent := string(openFile) sesh := session.Must(session.NewSessionWithOptions(session.Options{ SharedConfigState: session.SharedConfigEnable})) ssmClient := ssm.New(sesh) createDocRequest, err := ssmClient.CreateDocument(&ssm.CreateDocumentInput{ Content: &documentContent, Name: aws.String("createDocumentApiExample"), DocumentType: aws.String("Automation"), DocumentFormat: aws.String("YAML"), }) result := *createDocRequest fmt.Println(result) }
Java
import java.io.IOException; import java.nio.charset.Charset; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Paths; import com.amazonaws.AmazonClientException; import com.amazonaws.AmazonServiceException; import com.amazonaws.auth.AWSCredentials; import com.amazonaws.auth.profile.ProfileCredentialsProvider; import com.amazonaws.regions.Regions; import com.amazonaws.services.simplesystemsmanagement.AWSSimpleSystemsManagement; import com.amazonaws.services.simplesystemsmanagement.AWSSimpleSystemsManagementClientBuilder; import com.amazonaws.services.simplesystemsmanagement.model.*; public class createDocumentApiExample { public static void main(String[] args) { try { createDocumentMethod(getDocumentContent()); } catch (IOException e) { e.printStackTrace(); } } public static String getDocumentContent() throws IOException { String filepath = new String("/path/to/file/documentContent.yaml"); byte[] encoded = Files.readAllBytes(Paths.get(filepath)); String documentContent = new String(encoded, StandardCharsets.UTF_8); return documentContent; } public static void createDocumentMethod (final String documentContent) { AWSSimpleSystemsManagement ssm = AWSSimpleSystemsManagementClientBuilder.defaultClient(); final CreateDocumentRequest createDocRequest = new CreateDocumentRequest() .withContent(documentContent) .withName("createDocumentApiExample") .withDocumentType("Automation") .withDocumentFormat("YAML"); final CreateDocumentResult result = ssm.createDocument(createDocRequest); } }

有关创建自定义文档内容的更多信息,请参阅 数据元素和参数

删除自定义 SSM 文档

如果您不再想使用自定义 SSM 文档,可以使用 Amazon Command Line Interface (Amazon CLI)或 Amazon Systems Manager 控制台。

要删除 SSM 文档 (Amazon CLI)
  1. 在删除文档之前,我们建议您取消与文档关联的所有实例的关联。

    运行以下命令以取消实例与文档的关联。

    aws ssm delete-association --instance-id "123456789012" --name "documentName"

    如果此命令成功,则无任何输出。

  2. 运行以下命令。将每个示例资源占位符替换为您自己的信息。

    Linux
    aws ssm delete-document \ --name "document-name" \ --document-version "document-version" \ --version-name "version-name"
    Windows
    aws ssm delete-document ^ --name "document-name" ^ --document-version "document-version" ^ --version-name "version-name"
    PowerShell
    Delete-SSMDocument ` -Name "document-name" ` -DocumentVersion 'document-version' ` -VersionName 'version-name'

    如果此命令成功,则无任何输出。

    重要

    如果没有提供 document-versionversion-name,则会删除该文档的所有版本。

删除 SSM 文档(控制台)
  1. 访问 https://console.aws.amazon.com/systems-manager/,打开 Amazon Systems Manager 控制台。

  2. 在导航窗格中,选择文档

  3. 选择要删除的角色。

  4. 选择删除。在提示删除文档时,选择删除