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

AWS Systems Manager のパブリックドキュメントが AWS リソースで実行したいすべてのアクションを実行しない場合は、独自の SSM ドキュメントを作成できます。コンソールを使用して SSM ドキュメントのクローンを作成することもできます。ドキュメントのクローンにより、既存のドキュメントから変更可能な新しいドキュメントにコンテンツをコピーします。作成またはクローンするドキュメントは、その内容が 64KB を超えることはできません。このクォータには、ランタイム時に入力パラメータで指定される内容も含みます。新しい Command または Policy ドキュメントを作成する場合は、ドキュメントの編集、バージョンの自動管理、順序付けなどの最新の機能を利用できるように、スキーマバージョン 2.2 以降を使用することをお勧めします。

SSM ドキュメントコンテンツを書き込む

独自の SSM ドキュメントコンテンツを作成するには、SSM ドキュメントで使用できるさまざまなスキーマ、機能、プラグイン、および構文を理解することが重要です。次のリソースに精通することをお勧めします。

• 独自の AWS Systems Manager ドキュメントを作成する

• データ要素とパラメータ

• スキーマ、機能、および例

• コマンドドキュメントプラグインリファレンス

• Systems Manager Automation アクションのリファレンス

• オートメーションシステム変数

• その他のランブックの例

• AWS Toolkit for Visual Studio Code を使用して、Systems Manager オートメーションランブックを操作する

• オートメーションランブックのビジュアルデザインエクスペリエンス

• ランブックでのスクリプトの使用

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 ドキュメントの複製

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 ドキュメントを作成できます。

複合ドキュメントの作成

複合 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\"}"
      }
    }
  ]
}

詳細情報

• Run Command を使用してスクリプトを呼び出すときに使用するサーバーとインスタンスの再起動については、「コマンド実行時の再起動の処理」を参照してください。

• カスタム SSM ドキュメントに追加できるプラグインの詳細については、「コマンドドキュメントプラグインリファレンス」を参照してください。

• 複合ドキュメントを作成せずにリモートロケーションからドキュメントを実行するだけの場合は、「遠隔で ドキュメントを実行する」を参照してください。