建立 SSM 文件內容 - AWS Systems Manager
撰寫 SSM 文件內容複製 SSM 文件建立複合文件

建立 SSM 文件內容

如果 AWS Systems Manager 公有文件不執行您想要對 AWS 資源執行的所有動作，您可以建立自己的 SSM 文件。您也可以使用主控台複製 SSM 文件。複製文件會將現有文件的內容複製到您可以修改的新文件中。建立或複製文件時，文件的內容不得超過 64 KB。此配額也包括在執行階段為輸入參數指定的內容。當您建立新的 Command 或 Policy 文件時，我們建議您使用結構描述 2.2 或更新版本，以便您可以利用最新的功能，例如文件編輯、自動版本控制、排序等。

撰寫 SSM 文件內容

若要建立您自己的 SSM 文件內容，請務必瞭解 SSM 文件提供的不同結構描述、功能、外掛程式和語法。我們建議您熟悉下列資源。

AWS 預先定義的 SSM 文件可能會執行您需要的某些動作。您可以根據文件類型，在自訂 SSM 文件中使用 aws:runDocument、aws:runCommand 或 aws:executeAutomation 外掛程式來呼叫這些文件。您也可以將這些文件的部分複製到自訂 SSM 文件中，然後編輯內容以符合您的需求。

提示

建立 SSM 文件內容時，您可能會在測試時數次變更內容並更新 SSM 文件。下列命令會以您的最新內容更新 SSM 文件，並將文件的預設版本更新為文件的最新版本。

注意

Linux 和 Windows 命令使用 jq 命令列工具來篩選 JSON 回應資料。

Linux & macOS
latestDocVersion=$(aws ssm update-document \
    --content file://path/to/file/documentContent.json \
    --name "ExampleDocument" \
    --document-format JSON \
    --document-version '$LATEST' \
    | jq -r '.DocumentDescription.LatestVersion')

aws ssm update-document-default-version \
    --name "ExampleDocument" \
    --document-version $latestDocVersion
Windows
latestDocVersion=$(aws ssm update-document ^
    --content file://C:\path\to\file\documentContent.json ^
    --name "ExampleDocument" ^
    --document-format JSON ^
    --document-version "$LATEST" ^
    | jq -r '.DocumentDescription.LatestVersion')

aws ssm update-document-default-version ^
    --name "ExampleDocument" ^
    --document-version $latestDocVersion
PowerShell
$content = Get-Content -Path "C:\path\to\file\documentContent.json" | Out-String
$latestDocVersion = Update-SSMDocument `
    -Content $content `
    -Name "ExampleDocument" `
    -DocumentFormat "JSON" `
    -DocumentVersion '$LATEST' `
    | Select-Object -ExpandProperty LatestVersion

Update-SSMDocumentDefaultVersion `
    -Name "ExampleDocument" `
    -DocumentVersion $latestDocVersion

SSM 文件的安全最佳實務

建立 SSM 文件時，請遵循這些安全最佳實務，以協助防止命令注入，確保安全處理參數：

  • 針對將在命令或指令碼中使用的字串參數，使用環境變數插補。將具有 ENV_VAR 值的 interpolationType 屬性新增至字串參數：

    {
    "command": {
        "type": "String",
        "description": "Command to execute",
        "interpolationType": "ENV_VAR"
    }
}

    您可以透過指定在插補傳遞的值中不接受雙引號，進一步提高 SSM 文件的安全性：

    {
    "command": {
        "type": "String",
        "description": "Command to execute",
        "interpolationType": "ENV_VAR",
            "allowedPattern": "^[^"]*$"
    }
}

  • 使用 Python、Ruby 或 Node.js 等編譯語言時，請使用適當的環境變數語法來參考參數：

    # Python example
import os
command = os.environ['SSM_Message']

  • 為了回溯相容於舊版 SSM Agent (3.3.2746.0 版之前)，請包含環境變數的備用邏輯：

    if [ -z "${SSM_command+x}" ]; then
    export SSM_command="{{command}}"
fi

  • 將環境變數插補與 allowedPattern 結合，以進行額外的輸入驗證。在下列範例中，allowedPattern 值 ^[^"]*$ 會特別防止字串值中的雙引號：

    {
    "command": {
        "type": "String",
        "interpolationType": "ENV_VAR",
        "allowedPattern": "^[a-zA-Z0-9_-]+$"
    }
}

  • 實作 SSM 文件之前，請驗證下列安全性考量：

    • 接受使用者輸入的所有字串參數會適時使用環境變數插補。

    • 盡可能使用 allowedPattern 實作輸入驗證。

    • 文件包含適用於參數處理的適當錯誤處理。

    • 對於使用舊版 SSM Agent 的環境，會維持回溯相容性。

如需有關 Systems Manager 存取的 AWS 服務擁有的資源以及如何設定資料周界政策的資訊，請參閱 AWS Systems Manager 中的資料周界。

複製 SSM 文件

您可以使用 Systems Manager 文件主控台複製 AWS Systems Manager 文件，以建立 SSM 文件。複製 SSM 文件會將現有文件的內容複製到您可以修改的新文件中。您無法複製大於 64 KB 的文件。

若要複製 SSM 文件

  1. 開啟位於 AWS Systems Managerhttps://console.aws.amazon.com/systems-manager/ 的主控台。https://console.aws.amazon.com/systems-manager/

  2. 在導覽窗格中，選擇 Documents (文件)。

  3. 在搜尋方塊中，輸入您要複製的文件的名稱。

  4. 選擇您要翻製的文件名稱，然後選擇 Actions (動作) 下拉式選單中的 Clone document (複製文件)。

  5. 視需要修改文件，然後選擇 Create document (建立文件) 以儲存文件。

撰寫 SSM 文件內容之後，您可以使用下列其中一種方法來建立 SSM 文件。

建立 SSM 文件

建立複合文件

複合的 AWS Systems Manager (SSM) 文件是一種自訂文件，透過驅動一個或多個次要 SSM 文件來執行一系列動作。複合文件提升了 infrastructure as code，讓您能夠為常見任務建立一組標準的 SSM 文件，例如自舉軟體或網域加入執行個體。然後，您可以在相同 AWS 區域 的 AWS 帳戶 間共用這些文件，以降低 SSM 文件的維護成本和確保一致性。

例如，您可以建立複合的文件來執行下列動作：

  1. 安裝允許清單中的所有修補程式。

  2. 安裝防毒軟體

  3. 從 GitHub 下載指令碼並執行指令碼。

在這個範例中，自訂 SSM 文件中包含下列外掛程式以執行下列動作：

  1. 用於執行 AWS-RunPatchBaseline 文件的 aws:runDocument 外掛程式，可安裝所有允許列出的修補程式。

  2. 用於執行 AWS-InstallApplication 文件的 aws:runDocument 外掛程式，可安裝防毒軟體。

  3. 用於從 GitHub 下載並執行指令碼的 aws:downloadContent 外掛程式。

複合和次要文件可以存放在 Systems Manager、GitHub (公有和私有儲存庫) 或 Amazon S3。您可以用 JSON 或 YAML 格式建立複合文件和次要文件。

注意

複合文件的執行深度最多只能為三個文件。這表示複合文件可以呼叫一個子文件，以及該子文件可以再呼叫一個文件。

若要建立複合文件，需要在自訂 SSM 文件中新增 aws:runDocument 外掛程式，並指定所需的輸入。下列的範例是個建立複合的文件來執行下列動作：

  1. 執行 aws:downloadContent 外掛程式，將 SSM 文件從 GitHub 公有儲存庫下載到名為 bootstrap 的本機目錄。此 SSM 文件稱為 StateManagerBootstrap.yml (YAML 文件)。

  2. 執行 aws:runDocument 外掛程式，以執行 StateManagerBootstrap.yml 文件。無需指定參數。

  3. 執行 aws:runDocument 外掛程式，以執行 AWS-ConfigureDocker pre-defined SSM 文件。指定的參數在執行個體上安裝 Docker。

{
  "schemaVersion": "2.2",
  "description": "My composite document for bootstrapping software and installing Docker.",
  "parameters": {
  },
  "mainSteps": [
    {
      "action": "aws:downloadContent",
      "name": "downloadContent",
      "inputs": {
        "sourceType": "GitHub",
        "sourceInfo": "{\"owner\":\"TestUser1\",\"repository\":\"TestPublic\", \"path\":\"documents/bootstrap/StateManagerBootstrap.yml\"}",
        "destinationPath": "bootstrap"
      }
    },
    {
      "action": "aws:runDocument",
      "name": "runDocument",
      "inputs": {
        "documentType": "LocalPath",
        "documentPath": "bootstrap",
        "documentParameters": "{}"
      }
    },
    {
      "action": "aws:runDocument",
      "name": "configureDocker",
      "inputs": {
        "documentType": "SSMDocument",
        "documentPath": "AWS-ConfigureDocker",
        "documentParameters": "{\"action\":\"Install\"}"
      }
    }
  ]
}
詳細資訊