Windows ベースの CloudFormation スタックのブートストラップ

このトピックでは、Windows スタックをブートストラップする方法と、スタック作成時の問題をトラブルシューティングする方法について説明します。

EC2 インスタンスのユーザーデータ

ユーザーデータは、起動時にスクリプトまたは設定情報を EC2 インスタンスに渡すことができる Amazon EC2 機能です。

Windows EC2 インスタンスの場合:

CloudFormation ヘルパースクリプト

ヘルパースクリプトは、ブートストラッププロセス中にインスタンスを設定するためのユーティリティです。Amazon EC2 ユーザーデータで使用され、強力な設定オプションを提供します。

CloudFormation には、スタックの一部として作成する Amazon EC2 インスタンスでソフトウェアをインストールしたりサービスを開始したりするために使用できる、次の Python ヘルパースクリプトが用意されています。

テンプレートからスクリプトを直接呼び出します。スクリプトは、同じテンプレートで定義されているリソースメタデータと組み合わされて機能します。スクリプトは Amazon EC2 インスタンスでスタック作成プロセス中に実行されます。

詳細については、「AWS CloudFormation テンプレートリファレンスガイド」の「CloudFormation ヘルパースクリプトリファレンス」を参照してください。

Windows スタックのブートストラップの例

次のアクションを実行する Windows Server テンプレートのサンプルスニペットを見てみましょう。

cfn-init のヘルパースクリプトを使用して、テンプレートの AWS::CloudFormation::Init リソースの情報に基づいて、これらの各アクションを実行します。

AWS::CloudFormation::Init セクションは TestInstance と呼ばれ、次の宣言で始まります。

TestInstance:
  Type: AWS::EC2::Instance
  Metadata:
    AWS::CloudFormation::Init:
      configSets:
        default:
          - create_files
          - start_services

この後、AWS::CloudFormation::Init の files セクションが宣言されます。

      create_files:
        files:
          c:\cfn\test.txt:
            content: !Sub |
              Hello from ${AWS::StackName}
          c:\cfn\cfn-hup.conf:
            content: !Sub |
              [main]
              stack=${AWS::StackName}
              region=${AWS::Region}
              interval=2
          c:\cfn\hooks.d\cfn-auto-reloader.conf:
            content: !Sub |
              [cfn-auto-reloader-hook]
              triggers=post.update
              path=Resources.TestInstance.Metadata.AWS::CloudFormation::Init
              action=cfn-init.exe -v -s ${AWS::StackName} -r TestInstance -c default --region ${AWS::Region}

3 つのファイルがここで作成され、サーバーインスタンスの C:\cfn ディレクトリに配置されます。

次に、Windows サービスを設定する start_services セクションです。

      start_services:
        services:
          windows:
            cfn-hup:
              enabled: true
              ensureRunning: true
              files:
                - c:\cfn\cfn-hup.conf
                - c:\cfn\hooks.d\cfn-auto-reloader.conf

このセクションでは、cfn-hup サービスが開始され、設定ファイルが変更されると自動的に再起動します。サービスは CloudFormation メタデータの変更をモニタリングし、更新が検出されると cfn-init を再実行します。

次は Properties セクションです。

TestInstance:
  Type: AWS::EC2::Instance
  CreationPolicy:
    ResourceSignal:
      Timeout: PT20M
  Metadata:
    AWS::CloudFormation::Init:
      # ... metadata configuration ...
  Properties:
    InstanceType: t2.large
    ImageId: '{{resolve:ssm:/aws/service/ami-windows-latest/Windows_Server-2022-English-Full-Base}}'
    SecurityGroupIds:
      - !Ref InstanceSecurityGroup
    KeyName: !Ref KeyPairName
    UserData:
      Fn::Base64: !Sub |
        <powershell>
        cfn-init.exe -v -s ${AWS::StackName} -r TestInstance -c default --region ${AWS::Region}
        cfn-signal.exe -e $lastexitcode --stack ${AWS::StackName} --resource TestInstance --region ${AWS::Region}
        </powershell>

このセクションでは、UserData プロパティに、PowerShell が実行する EC2Launch が含まれています。この部分は <powershell> タグで囲まれています。スクリプトは default configSet を使用して cfn-init を実行し、cfn-signal を使用して終了コードを CloudFormation に報告します。CreationPolicy は、スタックの作成が完了と見なされる前にインスタンスが適切に設定されていることを確認するために使用されます。

ImageId プロパティは、Systems Manager パラメータストアのパブリックパラメータを使用して、最新の Windows Server 2022 AMI ID を自動的に取得します。このアプローチにより、リージョン固有の AMI マッピングが不要になり、常に最新の AMI を取得できます。Systems Manager パラメータを AMI ID に使用することは、最新の AMI リファレンスを維持するためのベストプラクティスです。インスタンスに接続する場合は、SecurityGroupIds プロパティが RDP アクセスを許可するセキュリティグループを参照していることを確認してください。

CreationPolicy はリソースプロパティの一部として宣言され、タイムアウト期間を指定します。インスタンス設定が完了すると、ユーザーデータ内の cfn-signal コマンドがシグナルを送信します。

TestInstance:
  Type: AWS::EC2::Instance
  CreationPolicy:
    ResourceSignal:
      Timeout: PT20M
  Properties:
    # ... other properties ...

ブートストラッピングプロセスは最小限で、ファイルの作成とサービスの開始のみを行うため、CreationPolicy はタイムアウトするまで 20 分 (PT20M) 待機します。タイムアウトは ISO 8601 期間形式を使用して指定します。Windows インスタンスの起動には通常 Linux インスタンスよりも時間がかかるため、徹底的にテストしてニーズに最適なタイムアウト値を判断してください。

すべて問題がなければ、CreationPolicy は正常に完了し、パブリック IP アドレスを使用して Windows Server インスタンスにアクセスできます。スタックの作成が完了すると、インスタンス ID と IP アドレスが CloudFormation コンソールの [出力] タブに表示されます。

Outputs:
  InstanceId:
    Value: !Ref TestInstance
    Description: Instance ID of the Windows Server
  PublicIP:
    Value: !GetAtt TestInstance.PublicIp
    Description: Public IP address of the Windows Server

RDP 経由でインスタンスに接続し、ファイル C:\cfn\test.txt が存在し、予想されるコンテンツが含まれていることを確認することで、ブートストラッピングが正しく機能したことを手動で確認することもできます。Windows インスタンスへの接続の詳細については、「Amazon EC2 ユーザーガイド」の「Connect to your Windows instance using RDP」を参照してください。

Windows ファイルパスのバックスラッシュをエスケープする

CloudFormation テンプレートで Windows パスを参照するときは、使用しているテンプレート形式に従ってバックスラッシュ (\) を適切にエスケープするようにしてください。

Windows のサービスを管理する

Linux サービスと同じように Windows サービスを管理しますが、sysvinit の代わりに、windows キーを使用します。次の例では、cfn-hup サービスを開始し、それを Automatic に設定します。c:\cfn\cfn-hup.conf または c:\cfn\hooks.d\cfn-auto-reloader.conf 設定ファイルを cfn-init が変更する場合は、サービスを再起動します。

        services:
          windows:
            cfn-hup:
              enabled: true
              ensureRunning: true
              files:
                - c:\cfn\cfn-hup.conf
                - c:\cfn\hooks.d\cfn-auto-reloader.conf

サービスを参照する名前 (表示名ではない) を使用して、同じ方法で他の Windows サービスを管理できます。

スタック作成の問題のトラブルシューティング

スタックの作成に失敗する場合、デフォルトでは失敗時にロールバックが実行されます。不必要な課金を避けられるため、通常はこのデフォルト設定が適切ですが、スタック作成が失敗する原因をデバッグすることは難しくなります。

CloudFormation コンソールでスタックを作成または更新するときにこの動作をオフにするには、[スタックの失敗オプション] で [正常にプロビジョニングされたリソースの保持] オプションを選択します。詳細については、「リソースのプロビジョニング時における失敗への対応方法を選択する」を参照してください。これにより、インスタンスにログインし、ログファイルを確認できるようになり、スタートアップスクリプト実行時に発生した問題を特定できます。

調査対象の重要なログは次のとおりです。

その他のログについては、「Amazon EC2 ユーザーガイド」の次のトピックを参照してください。

ブートストラッピングの問題のトラブルシューティングの詳細については、「Windows インスタンスがある CloudFormation スタックでブートストラップしないヘルパースクリプトをトラブルシューティングするにはどうすればよいですか?」を参照してください。