# Windows ベースの CloudFormation スタックのブートストラップ
<a name="cfn-windows-stacks-bootstrapping"></a>

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

**Topics**
+ [EC2 インスタンスのユーザーデータ](#cfn-windows-bootstrapping-user-data)
+ [CloudFormation ヘルパースクリプト](#cfn-windows-bootstrapping-helper-scripts)
+ [Windows スタックのブートストラップの例](#cfn-windows-bootstrapping-example)
+ [Windows ファイルパスのバックスラッシュをエスケープする](#cfn-windows-stacks-escape-backslashes)
+ [Windows のサービスを管理する](#cfn-windows-stacks-manage-windows-services)
+ [スタック作成の問題のトラブルシューティング](#cfn-windows-stacks-troubleshooting)

## EC2 インスタンスのユーザーデータ
<a name="cfn-windows-bootstrapping-user-data"></a>

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

Windows EC2 インスタンスの場合:
+ バッチスクリプト (`<script>` タグを使用) または PowerShell スクリプト (`<powershell>` タグを使用) を使用できます。
+ スクリプトの実行は EC2Launch によって処理されます。

**重要**  
CloudFormation で使用する独自の Windows AMI を作成する場合は、EC2Launch v2 が正しく設定されていることを確認してください。スタック作成時に Windows インスタンスを適切に初期化および設定するには、CloudFormation のブートストラップツールに EC2Launch v2 が必要です。詳細については、『Amazon EC2 ユーザーガイド』の「[EC2 Windows インスタンスの起動時に EC2Launch v2 エージェントを使用してタスクを実行する](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-v2.html)」を参照してください。  
AWS Windows AMI の詳細については、「[AWSWindows AMI リファレンス](https://docs.aws.amazon.com/ec2/latest/windows-ami-reference/windows-amis.html)」を参照してください。

## CloudFormation ヘルパースクリプト
<a name="cfn-windows-bootstrapping-helper-scripts"></a>

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

CloudFormation には、スタックの一部として作成する Amazon EC2 インスタンスでソフトウェアをインストールしたりサービスを開始したりするために使用できる、次の Python ヘルパースクリプトが用意されています。
+  `cfn-init` – リソースメタデータの取得と解釈、パッケージのインストール、ファイルの作成、およびサービスの開始で使用します。
+  `cfn-signal` – `CreationPolicy` でシグナルを送信するために使用し、前提となるリソースやアプリケーションの準備ができたときに、スタックの他のリソースを同期できるようにします。
+  `cfn-get-metadata` – 特定のキーへのリソースまたはパスのメタデータを取得するために使用します。
+  `cfn-hup` – メタデータへの更新を確認し、変更が検出されたときにカスタムフックを実行するために使用します。

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

詳細については、「*CloudFormation テンプレートリファレンスガイド*」の「[CloudFormation ヘルパースクリプトリファレンス](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/cfn-helper-scripts-reference.html)」を参照してください。

## Windows スタックのブートストラップの例
<a name="cfn-windows-bootstrapping-example"></a>

次のアクションを実行する Windows Server テンプレートのサンプルスニペットを見てみましょう。
+ `TestInstance` という名前の EC2 インスタンスを Windows Server 2022 AMI から起動します。
+ `cfn-init` が動作していることを確認するためのシンプルなテストファイルを作成します。
+ `cfn-hup` を継続的な設定管理のために設定します。
+ `CreationPolicy` を使用して、インスタンスが正常に完了したというシグナルを送信するようにします。

`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` ディレクトリに配置されます。
+ `test.txt` は、`cfn-init` が正しく動作していることを検証するシンプルなテストファイルであり、動的コンテンツを含むファイルを作成できます。
+ `cfn-hup.conf` は、`cfn-hup` 用の設定ファイルで、チェック間隔は 2 分間です。
+ `cfn-auto-reloader.conf`、`AWS::CloudFormation::Init` のメタデータが変更されるときに `cfn-hup` が更新 (`cfn-init` の呼び出し) を開始するために使用するフックの設定ファイル。

次に、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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connecting_to_windows_instance.html)」を参照してください。

## Windows ファイルパスのバックスラッシュをエスケープする
<a name="cfn-windows-stacks-escape-backslashes"></a>

CloudFormation テンプレートで Windows パスを参照するときは、使用しているテンプレート形式に従ってバックスラッシュ (`\`) を適切にエスケープするようにしてください。
+ JSON テンプレートでは、JSON はバックスラッシュをエスケープ文字として扱うため、Windows ファイルパスにダブルバックスラッシュを使用する必要があります。最初のバックスラッシュは 2 番目のバックスラッシュをエスケープするため、単一のリテラルバックスラッシュとして解釈されます。

  ```
  "commands" : {
    "1-extract" : {
      "command" : "C:\\SharePoint\\SharePointFoundation2010.exe /extract:C:\\SharePoint\\SPF2010 /quiet /log:C:\\SharePoint\\SharePointFoundation2010-extract.log"
    }
  }
  ```
+ YAML テンプレートの場合、通常、1 つのバックスラッシュで十分です。

  ```
  commands:
    1-extract:
      command: C:\SharePoint\SharePointFoundation2010.exe /extract:C:\SharePoint\SPF2010 /quiet /log:C:\SharePoint\SharePointFoundation2010-extract.log
  ```

## Windows のサービスを管理する
<a name="cfn-windows-stacks-manage-windows-services"></a>

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 サービスを管理できます。

## スタック作成の問題のトラブルシューティング
<a name="cfn-windows-stacks-troubleshooting"></a>

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

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

調査対象の重要なログは次のとおりです。
+ `%ProgramData%\Amazon\EC2Launch\log\agent.log` にある EC2 構成ログ
+ `C:\cfn\log\cfn-init.log` の **cfn-init** ログ (特定の障害ポイントの終了コードとエラーメッセージを確認する)

その他のログについては、「Amazon EC2 ユーザーガイド」の次のトピックを参照してください。
+ [EC2Launch ディレクトリ構造](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-service.html#UsingConfigXML_WinAMI)
+ [EC2Launch v2 ディレクトリ構造](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-v2.html#ec2launch-v2-directory)

ブートストラッピングの問題のトラブルシューティングの詳細については、「[Windows インスタンスがある CloudFormation スタックでブートストラップしないヘルパースクリプトをトラブルシューティングするにはどうすればよいですか?](https://repost.aws/knowledge-center/cloudformation-helper-scripts-windows)」を参照してください。