【Python】AWS::SSM::Document の Script プロパティでローカルファイルを指定する方法

作成日: 2025/04/13, 更新日: 2025/04/13

aws cloudformation package コマンドでは、AWS::SSM::Document で SSM オートメーションで利用するランブックを定義する際に利用する、aws:executeScript ステップの Script プロパティで指定するファイルを S3 にアップロードすることができません。
この処理にしばらく AWS の機能アップデート対応されていない理由として、AWS::SSM::Document に S3 バケットへ配置したスクリプトを指定するためには
格納した S3 バケットの名前、ファイル名だけでなく、チェックサムとしてハッシュ値を AWS::SSM::Document で指定する必要がある仕様になっているからだと推測します。
本記事では、AWS::SSM::Document の Script プロパティでローカルファイルをパスで指定してもデプロイできるよう
変換処理を Python で実装しましたので、その方法を記載いたします。

注意事項
コーディングルール・前提条件
AWS::SSM::Document の Script プロパティで指定したファイル内容を CloudFormatio テンプレートへ書き込む処理

注意事項

本記事に記載の Python スクリプトを実行することで、CloudFormation テンプレートの AWS::SSM::Document リソースの Script プロパティで指定したファイルの内容を CloudFormation テンプレートに書き込むことができます。
Python スクリプトの場合、実行するスクリプトで利用できるモジュールは Lambda の標準のモジュールと同等のものとなります。Lambda の標準モジュール以外を利用する場合はこの Python スクリプトでは対応できません。
- os, argparse, boto3, json, logging, time, datetime などの標準モジュールは利用可能です。
Lambda の標準モジュール以外を利用する場合は、手動で S3 バケットに Python スクリプトとパッケージを含めた ZIP ファイルをアップロード後、CloudFormation テンプレートをデプロイする必要があります。

コーディングルール・前提条件

本記事に記載の Python スクリプトでは、PEP8 に準拠しています。
- flake 8 による構文チェックと、 black による自動フォーマットを実施しています。
- 処理の都合上チェックを無視する必要があるコードには、 # noqa を記載しています。
- 1行当たりの最大文字数（ max-line-length ）は 200 に設定しています。

Python のランタイムバージョンは 3.12.1 を利用して動作確認を行っています。

AWS::SSM::Document の Script プロパティで指定したファイル内容を CloudFormatio テンプレートへ書き込む処理

実行に必要なモジュールは以下の通りです。 argparse、os は標準ライブラリのため、追加のインストールは不要です。


                    ruamel.yaml

以下の Python スクリプトが、 AWS::SSM::Document の Script プロパティで指定したファイルの内容を CloudFormation テンプレートへ書き込みます。適当 Python ファイルの名前（例： package-ssm-document.py ）で保存してください。
- aws cloudformation package コマンドと同様、Cloud Formation テンプレートをデプロイする前に実行する必要があります。実行手順や CI/CD に組み込んでご利用ください。


                    import argparse
                    import os
                    from ruamel.yaml import YAML
                    from ruamel.yaml.scalarstring import LiteralScalarString

                    yaml = YAML()
                    yaml.default_flow_style = False
                    yaml.sort_keys = False


                    def replace_script_with_inline_code(input_file, output_file):
                        base_dir = os.path.dirname(input_file)

                        with open(input_file, "r") as file:
                            yaml_content = yaml.load(file)

                        def process_main_steps(main_steps):
                            for step in main_steps:
                                if step.get("action") == "aws:executeScript" and "Script" in step["inputs"]:
                                    script_path = step["inputs"]["Script"]
                                    full_script_path = os.path.normpath(os.path.join(base_dir, script_path))
                                    if os.path.exists(full_script_path):
                                        with open(full_script_path, "r") as script_file:
                                            script_content = script_file.read()
                                        step["inputs"]["Script"] = apply_literal_block_style(script_content)
                                    else:
                                        print(f"Warning: Script file not found at {full_script_path}")
                                elif step.get("action") == "aws:loop" and "Steps" in step["inputs"]:
                                    process_main_steps(step["inputs"]["Steps"])
                                if "nextStep" in step:
                                    process_main_steps(step.get("nextStep", []))

                        def apply_literal_block_style(script_content):
                            return LiteralScalarString(script_content)

                        for resource in yaml_content.get("Resources", {}).values():
                            if resource.get("Type") == "AWS::SSM::Document":
                                content = resource.get("Properties", {}).get("Content", {})
                                if "mainSteps" in content:
                                    process_main_steps(content["mainSteps"])

                        output_dir = os.path.dirname(output_file)
                        if output_dir and not os.path.exists(output_dir):
                            os.makedirs(output_dir)

                        with open(output_file, "w") as file:
                            yaml.dump(yaml_content, file)


                    if __name__ == "__main__":
                        parser = argparse.ArgumentParser(description="Transform parameter overrides in a YAML file.")
                        parser.add_argument("--input-file", help="Path to the input YAML file.", default="template.original.yml")
                        parser.add_argument("--output-file", help="Path to the output YAML file.", default="template.yml")
                        args = parser.parse_args()
                        replace_script_with_inline_code(args.input_file, args.output_file)

以下は実行例となります。
- template.original.yml を template.yml に変換する場合のオプションを指定しています。
- 要件に応じて、引数でファイルパスを指定して実行してください。


                    python package-ssm-document.py \
                    --input-file tests/template1.original.yml \
                    --output-file .alcache/template.yml

template.original.yml の内容は以下の通りです。 Script プロパティで指定したファイルは src/sample1.py です。


                    AWSTemplateFormatVersion: 2010-09-09
                    Description: template.yml
                    Resources:
                      TestRunbook:
                        Type: AWS::SSM::Document
                        Properties:
                          Name: Sample-TestRunbook
                          DocumentType: Automation
                          DocumentFormat: YAML
                          UpdateMethod: NewVersion
                          Content:
                            schemaVersion: '0.3'
                            mainSteps:
                              - name: SampleStep
                                action: aws:executeScript
                                isEnd: true
                                inputs:
                                  Runtime: python3.11
                                  Handler: main
                                  Script: src/sample1.py

以下は、変換後の template.yml の内容です。 Script プロパティで指定したファイルの内容が Script プロパティの値に置き換わっていることが確認できます。


                    AWSTemplateFormatVersion: 2010-09-09
                    Description: template.yml
                    Resources:
                      TestRunbook:
                        Type: AWS::SSM::Document
                        Properties:
                          Name: Sample-TestRunbook
                          DocumentType: Automation
                          DocumentFormat: YAML
                          UpdateMethod: NewVersion
                          Content:
                            schemaVersion: '0.3'
                            mainSteps:
                            - name: SampleStep
                              action: aws:executeScript
                              isEnd: true
                              inputs:
                                Runtime: python3.11
                                Handler: main
                                Script: |
                                  def main(event, context):
                                      print("[sample1] Hello, World!")


                                  if __name__ == "__main__":
                                      main(None, None)