SSM ドキュメントコンテンツを作成する - AWS Systems Manager
SSM ドキュメントコンテンツを書き込むSSM ドキュメントの複製複合ドキュメントの作成

SSM ドキュメントコンテンツを作成する

AWS Systems Manager のパブリックドキュメントが AWS リソースで実行したいすべてのアクションを実行しない場合は、独自の SSM ドキュメントを作成できます。コンソールを使用して SSM ドキュメントのクローンを作成することもできます。ドキュメントのクローンにより、既存のドキュメントから変更可能な新しいドキュメントにコンテンツをコピーします。作成またはクローンするドキュメントは、その内容が 64KB を超えることはできません。このクォータには、ランタイム時に入力パラメータで指定される内容も含みます。新しい 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 の古いバージョンを使用する環境向けに下位互換性が保たれている。

SSM ドキュメントの複製

Systems Manager のドキュメントコンソールを使用して、AWS Systems Manager のドキュメントのクロ―ンを作成し、SSM ドキュメントを作成できます。SSM ドキュメントの複製により、既存のドキュメントから変更可能な新しいドキュメントにコンテンツをコピーします。64KB を超えるドキュメントをクローンすることはできません。

SSM ドキュメントを複製するには

  1. AWS Systems Manager コンソール (https://console.aws.amazon.com/systems-manager/) を開きます。

  2. ナビゲーションペインで、[ドキュメント] を選択します。

  3. 検索ボックスに、複製するドキュメントの名前を入力します。

  4. 複製するドキュメントの名前を選択し、「アクション」ドロップダウンで「ドキュメントの複製」を選択します。

  5. 必要に応じてドキュメントを変更し、[ドキュメントの作成] を選択してドキュメントを保存します。

SSM ドキュメントコンテンツを作成したら、次のいずれかの方法を使用して、コンテンツを使って SSM ドキュメントを作成できます。

SSM ドキュメントを作成する

複合ドキュメントの作成

複合 AWS Systems Manager (SSM) ドキュメントは、1 つまたは複数のセカンダリ SSM ドキュメントを実行して一連のアクションを実行するカスタムドキュメントです。複合ドキュメントは、ブートストラップソフトウェアやドメイン結合インスタンスなどの一般的なタスク用の標準 SSM ドキュメントセットを作成できるようにすることで、Infrastructure as Code (コードとしてのインフラストラクチャ)を推進します。これらのドキュメントを同じ AWS リージョン の AWS アカウント 間で共有して、SSM ドキュメントのメンテナンスを減らし、整合性を確保することができます。

たとえば、次のアクションを実行する複合ドキュメントを作成できます｡

  1. 許可リストのすべてのパッチをインストールする。

  2. ウイルス対策ソフトウェアをインストールする｡

  3. GitHub からスクリプトをダウンロードして実行する。

この例では、カスタム SSM ドキュメントに以下のアクションを実行するためのプラグインが含まれています。

  1. AWS-RunPatchBaseline ドキュメントを実行する aws:runDocument プラグインは、すべての許可されたリストのパッチをインストールします。

  2. aws:runDocument ドキュメントを実行する AWS-InstallApplication プラグインは、ウイルス対策ソフトウェアをインストールします。

  3. aws:downloadContent プラグインは、GitHub からスクリプトをダウンロードして実行します。

複合ドキュメントとセカンダリドキュメントは、Systems Manager、GitHub (パブリックおよびプライベートリポジトリ)、または Amazon S3 に保存できます。複合ドキュメントおよびセカンダリドキュメントは JSON あるいは YAML で作成できます。

注記

複合ドキュメントは最大 3 階層のドキュメントまでしか実行できません。つまり、複合ドキュメントは子ドキュメントを呼び出すことができます。その子ドキュメントは最後の 1 つのドキュメントを呼び出すことができます。

複合ドキュメントを作成するには、カスタム SSM ドキュメントで aws:runDocument プラグインを開き、必要な入力を指定します。以下に、次のアクションを実行する複合ドキュメントの例を示します｡

  1. aws:downloadContent プラグインを実行して、GitHub パブリックリポジトリからブートストラップというローカルディレクトリに SSM ドキュメントをダウンロードします。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\"}"
      }
    }
  ]
}
詳細情報