Windows インスタンスでの起動時のコマンドの実行 - Amazon Elastic Compute Cloud
ユーザーデータスクリプトユーザーデータの実行ユーザーデータおよびコンソールユーザーデータと Tools for Windows PowerShell

Windows インスタンスでの起動時のコマンドの実行

Amazon EC2 を使用した Windows インスタンスの起動時にインスタンスに渡すユーザーデータを使用して、インスタンスの起動後に自動設定タスクを実行したり、スクリプトを実行したりできます。インスタンスユーザーデータは、非透過的なデータとして扱われますが、その解釈はインスタンスに依存します。ユーザーデータは、Windows Server 2022 では EC2Launch v2 によって、Windows Server 2016 と 2019 では EC2Launch によって、Windows Server 2012 R2 以前では EC2Config によって処理されます。

UserData テンプレート内の AWS CloudFormation プロパティのアセンブリ例については、「UserData プロパティの Base64 エンコード」および「AccessKey と SecretKey を含む UserData プロパティの Base64 エンコード」を参照してください。

起動時に Linux インスタンスでコマンドを実行する方法については、Linux インスタンス用 Amazon EC2 ユーザーガイドの「Linux インスタンスでの起動時のコマンドの実行」を参照してください。

ライフサイクルフックと連携するコマンドを Auto Scaling 内のインスタンスで実行する例については、「Amazon EC2 Auto Scaling ユーザーガイド」の「チュートリアル: インスタンスのメタデータからターゲットライフサイクル状態を取得するようにユーザーデータを設定する」を参照してください。

ユーザーデータスクリプト

EC2Config または EC2Launch でスクリプトを実行するには、そのスクリプトをユーザーデータに追加するときに特別なタグ内にスクリプトを囲む必要があります。使用するタグは、コマンドをコマンドプロンプトウィンドウ (バッチコマンド) で実行するか、Windows PowerShell を使用するかによって異なります。

バッチスクリプトと Windows PowerShell スクリプトの両方を指定すると、バッチスクリプトが最初に実行され、インスタンスユーザーデータに表示される順序に関係なく、次に Windows PowerShell スクリプトが実行されます。

ユーザーデータスクリプトで AWS API (AWS CLI など) を使用する場合は、インスタンスを起動するときにインスタンスプロファイルを使用する必要があります。インスタンスプロファイルは、API 呼び出しを実行するためにユーザーデータスクリプトが必要とする適切な AWS 認証情報を提供します。詳細については、インスタンスプロファイル を参照してください。IAM ロールに割り当てるアクセス許可は、API で呼び出すサービスによって異なります。詳細については、「Amazon EC2 の IAM ロール」を参照してください。

バッチスクリプトの構文

script タグを使用してバッチ スクリプトを指定します。次の例に示すように、改行を使用してコマンドを区切ります。

<script>
echo Current date and time >> %SystemRoot%\Temp\test.log
echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log
</script>

デフォルトでは、ユーザーデータスクリプトはインスタンスを起動すると一度だけ実行されます。インスタンスを再起動または起動するたびにユーザーデータスクリプトを実行するには、<persist>true</persist> をユーザーデータに追加します。

<script>
echo Current date and time >> %SystemRoot%\Temp\test.log
echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log
</script>
<persist>true</persist>
EC2 ローンチ v2 エージェント

XML ユーザーデータスクリプトを UserData ステージ内の EC2Launch v2 executeScript タスクでデタッチされたプロセスとして実行するには、ユーザーデータに次のタグを追加します。

<detach>true</detach>

注記

デタッチタグは以前の起動エージェントではサポートされていません。

<script>
echo Current date and time >> %SystemRoot%\Temp\test.log
echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log
</script>
<detach>true</detach>

Windows PowerShell スクリプトの構文

AWS Windows AMI には AWS Tools for Windows PowerShell が含まれており、ユーザーデータにこれらのコマンドレットを指定することができます。インスタンスに IAM ロールを関連付けている場合は、コマンドレットに認証情報を指定する必要はありません。インスタンスで実行するアプリケーションは、ロールの認証情報を使用して AWS リソース (Simple Storage Service (Amazon S3) バケットなど) にアクセスします。

<powershell> タグを使用して Windows PowerShell スクリプトを指定します。コマンドは、改行を使って区切ります。<powershell> タグでは、大文字と小文字が区別されます。

例:

<powershell>
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
</powershell>

デフォルトでは、ユーザーデータスクリプトはインスタンスを起動すると一度だけ実行されます。インスタンスを再起動または起動するたびにユーザーデータスクリプトを実行するには、<persist>true</persist> をユーザーデータに追加します。

<powershell>
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
</powershell>
<persist>true</persist>
EC2 ローンチ v2 エージェント

XML ユーザーデータスクリプトを UserData ステージ内の EC2Launch v2 executeScript タスクでデタッチされたプロセスとして実行するには、ユーザーデータに次のタグを追加します。

<detach>true</detach>

注記

デタッチタグは以前の起動エージェントではサポートされていません。

<powershell>
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
</powershell>
<detach>true</detach>

YAML 設定スクリプトの構文

EC2Launch v2 を使用してスクリプトを実行する場合は、YAML 形式を使用できます。EC2Launch v2 の設定タスク、詳細、例を表示するには、「EC2Launch v2 タスクの設定」を参照してください。

executeScript タスクで YAML スクリプトを指定します。

PowerShell スクリプトを実行するための YAML 構文の例 

version: 1.0
tasks:
- task: executeScript
  inputs:
  - frequency: always
    type: powershell
    runAs: localSystem
    content: |-
      $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
      New-Item $file -ItemType file

バッチスクリプトを実行するための YAML 構文の例

version: 1.1
tasks:
- task: executeScript
  inputs:
  - frequency: always
    type: batch
    runAs: localSystem
    content: |-
      echo Current date and time >> %SystemRoot%\Temp\test.log
      echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log

Base64 エンコード

Amazon EC2 API または、ユーザーデータの base64 エンコーディングが実行されないツールを使用している場合、ユーザーデータを手動でエンコードする必要があります。エンコードしない場合、実行する script タグまたは powershell タグが見つからないというエラーが記録されます。Windows PowerShell を使用してエンコードする例を次に示します。

$UserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($Script))

PowerShell を使用してデコードする例を次に示します。

$Script = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($UserData))

base64 エンコードの詳細については、「https://www.ietf.org/rfc/rfc4648.txt」を参照してください。

ユーザーデータの実行

デフォルトでは、すべての AWS Windows AMI で初回起動時のユーザーデータの実行が有効になっています。次にインスタンスが再起動されたときにユーザーデータスクリプトが実行されるように指定できます。また、インスタンスが再起動するたびにユーザーデータスクリプトが実行されるように指定することもできます。

注記

ユーザーデータは、初期起動後にデフォルトで実行するように有効化されていません。インスタンスを再起動または起動したときにユーザーデータが実行できるようにするには、「後続の再起動または起動」を参照してください。

ユーザーデータスクリプトは、ランダムなパスワードが生成されたときにローカル管理者アカウントから実行されます。それ以外の場合、ユーザーデータスクリプトはシステムアカウントから実行されます。

インスタンスの作成

インスタンスユーザーデータ内のスクリプトは、インスタンスの最初の起動時に実行されます。persist タグが見つかった場合は、その後の再起動または開始時にユーザーデータの実行が有効になります。EC2Launch v2、EC2Launch、EC2Config のログファイルには、標準出力ストリームと標準エラーストリームの出力が含まれています。

EC2Launch v2

EC2Launch v2 のログファイルは C:\ProgramData\Amazon\EC2Launch\log\agent.log です。

注記

C:\ProgramData フォルダは非表示になっている場合があります。このフォルダを表示するには、非表示のファイルおよびフォルダを表示する必要があります。

ユーザーデータが実行されると、次の情報が記録されます。

  • Info: Converting user-data to yaml format – ユーザーデータが XML 形式で提供されているか

  • Info: Initializing user-data state – ユーザーデータ実行の開始

  • Info: Frequency is: always – ブートのたびにユーザーデータタスクが実行されているか

  • Info: Frequency is: once – ユーザーデータタスク実行は一度だけか

  • Stage: postReadyUserData execution completed – ユーザーデータの実行の終了

EC2Launch

EC2Launch のログファイルは C:\ProgramData\Amazon\EC2-Windows\Launch\Log\UserdataExecution.log です。

C:\ProgramData フォルダは非表示になっている場合があります。このフォルダを表示するには、非表示のファイルおよびフォルダを表示する必要があります。

ユーザーデータが実行されると、次の情報が記録されます。

  • Userdata execution begins – ユーザーデータ実行の開始

  • <persist> tag was provided: true – 永続タグが見つかったか

  • Running userdata on every boot – 永続タグが見つかったか

  • <powershell> tag was provided.. running powershell content – PowerShell タグが見つかったか

  • <script> tag was provided.. running script content – スクリプトタグが見つかったか

  • Message: The output from user scripts – 実行されたユーザーデータスクリプトがあり、その出力が記録されたか

EC2Config

EC2Config のログファイルは C:\Program Files\Amazon\Ec2ConfigService\Logs\Ec2Config.log です。ユーザーデータが実行されると、次の情報が記録されます。

  • Ec2HandleUserData: Message: Start running user scripts – ユーザーデータ実行の開始

  • Ec2HandleUserData: Message: Re-enabled userdata execution – 永続タグが見つかったか

  • Ec2HandleUserData: Message: Could not find <persist> and </persist> – 永続タグが見つからなかったのか

  • Ec2HandleUserData: Message: The output from user scripts – 実行されたユーザーデータスクリプトがあり、その出力が記録されたか

後続の再起動または起動

インスタンスユーザーデータを更新すると、ユーザーデータスクリプトは、インスタンスの再起動または起動時に自動的に実行されません。ただし、ユーザーデータの実行を有効にして、インスタンスを再起動または起動するか、インスタンスを再起動または起動するたびにユーザーデータスクリプトを 1 回実行することができます。

[Shutdown with Sysprep (Sysprep でシャットダウン)] オプションを選択すると、以降のインスタンスの起動時や再起動時にユーザーデータの実行を有効にしなくても、次回の起動時や再起動時にユーザーデータスクリプトが実行されます。ユーザーデータスクリプトは、以降の再起動時や起動時に実行されません。

EC2Launch v2 でユーザデータの実行を有効にするには (プレビュー AMI)

  • 初回起動時にユーザーデータのタスクを実行するには、frequency を once に設定します。

  • 起動するたびにユーザーデータのタスクを実行するには、frequency を always に設定します。

EC2Launch でユーザーデータの実行を有効にするには (Windows Server 2016 以降)

  1. Windows インスタンスに接続します。

  2. PowerShell コマンドウィンドウを開き、次のコマンドを入力します。

    C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeInstance.ps1 –Schedule

  3. Windows インスタンスから切断します。次にインスタンスを起動するときに更新されたスクリプトを実行するには、インスタンスを停止してユーザーデータを更新します。詳細については、インスタンスユーザーデータの表示と更新 を参照してください。

EC2Config でユーザーデータの実行を有効にするには (Windows Server 2012 R2 以前)

  1. Windows インスタンスに接続します。

  2. C:\Program Files\Amazon\Ec2ConfigService\Ec2ConfigServiceSetting.exe を開く。

  3. [ユーザーデータ] で、[Enable UserData execution for next service start (次のサービス開始でユーザーデータの実行を有効にする)] を選択します。

  4. Windows インスタンスから切断します。次にインスタンスを起動するときに更新されたスクリプトを実行するには、インスタンスを停止してユーザーデータを更新します。詳細については、インスタンスユーザーデータの表示と更新 を参照してください。

ユーザーデータおよびコンソール

インスタンスの起動時のインスタンスユーザーデータを指定できます。インスタンスのルートボリュームが EBS ボリュームの場合は、インスタンスを停止してユーザーデータを更新することもできます。

起動時にインスタンスユーザーデータを指定する

インスタンスを起動するための手順に従います。[User data] (ユーザーデータ) フィールドは、インスタンス起動ウィザードの 高度な詳細 セクションにあります。PowerShell スクリプトを [ユーザーデータ]  フィールドに入力し、インスタンスの起動手順を完了します。

次の [ユーザーデータ] フィールドのスクリーンショットのスクリプト例では、ファイル名に現在の日付と時刻を使用して、Windows 一時フォルダーにファイルを作成します。<persist>true</persist> を含めると、インスタンスを再起動または起動するたびにスクリプトが実行されます。[ユーザーデータはすでに base64 でエンコードされています] チェックボックスをオフのままにすると、Amazon EC2 コンソールが base64 エンコードを実行します。

Advance Details ユーザーデータテキストフィールド。

インスタンスユーザーデータの表示と更新

任意のインスタンスのインスタンスユーザーデータを表示し、停止したインスタンスのインスタンスユーザーデータを更新できます。

コンソールを使用してインスタンスユーザーデータを更新するには

  1. Amazon EC2 コンソール (https://console.aws.amazon.com/ec2/) を開きます。

  2. ナビゲーションペインで、[インスタンス] を選択します。

  3. インスタンスを選択し、[Actions (アクション)]、[Instance state (インスタンスの状態)]、[Stop instance (インスタンスの停止)] の順に選択します。

    警告

    インスタンスを停止すると、インスタンスストアボリューム上のデータは消去されます。インスタンスストアボリュームのデータを保持するには、データを永続的ストレージに必ずバックアップします。

  4. 確認を求められたら、[Stop] を選択します。インスタンスが停止するまで、数分かかる場合があります。

  5. インスタンスが選択された状態のまま、[Actions (アクション)]、[Instance settings (インスタンス設定)]、[Edit user data (ユーザーデータの編集)] の順に選択します。インスタンスの実行中はユーザーデータを変更できませんが、表示することはできます。

  6. [Edit user data (ユーザーデータの編集)] ダイアログボックスで、ユーザーデータを更新し、[Save (保存)] を選択します。インスタンスを再起動または起動するたびにユーザーデータスクリプトを実行するには、次の例に示すように <persist>true</persist> をユーザーデータに追加します。

    [Edit User Data] (ユーザデータの編集) ダイアログボックス。

  7. インスタンスを起動します。後続の再起動または開始のためにユーザーデータの実行を有効にした場合、更新されたユーザーデータスクリプトはインスタンスの開始プロセスの一部として実行されます。

ユーザーデータと Tools for Windows PowerShell

Tools for Windows PowerShell を使用して、インスタンスのユーザーデータを指定、変更、表示することができます。インスタンスのメタデータを使用して、インスタンスからユーザーデータを表示する方法については、「インスタンスユーザーデータを取得する」を参照してください。ユーザーデータと AWS CLI の詳細については、Amazon EC2 Linux インスタンス用ユーザーガイドの「ユーザーデータと AWS CLI」を参照してください。

例: 起動時にインスタンスユーザーデータを指定する

インスタンスユーザーデータを含むテキストファイルを作成します。インスタンスを再起動または起動するたびにユーザーデータスクリプトを実行するには、次の例に示すように <persist>true</persist> をユーザーデータに追加します。

<powershell>
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
</powershell>
<persist>true</persist>

インスタンスの起動時にインスタンスユーザーデータを指定するには、New-EC2Instance コマンドを使用します。このコマンドは、ユーザーデータの base64 エンコードを実行しません。次のコマンドを使用して、script.txt という名前のテキストファイルにユーザーデータをエンコードします。

PS C:\> $Script = Get-Content -Raw script.txt
PS C:\> $UserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($Script))

-UserData パラメータを使用して、ユーザーデータを New-EC2Instance コマンドに渡します。

PS C:\> New-EC2Instance -ImageId ami-abcd1234 -MinCount 1 -MaxCount 1 -InstanceType m3.medium \
-KeyName my-key-pair -SubnetId subnet-12345678 -SecurityGroupIds sg-1a2b3c4d \
-UserData $UserData
例: 停止したインスタンスのインスタンスユーザーデータを更新する

停止したインスタンスのユーザーデータは、Edit-EC2InstanceAttribute コマンドを使用して変更できます。

新しいスクリプトを使用してテキストファイルを作成します。次のコマンドを使用して、new-script.txt という名前のテキストファイルにユーザーデータをエンコードします。

PS C:\> $NewScript = Get-Content -Raw new-script.txt
PS C:\> $NewUserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($NewScript))

-UserData および -Value パラメータを使用して、ユーザーデータを指定します。

PS C:\> Edit-EC2InstanceAttribute -InstanceId i-1234567890abcdef0 -Attribute userData -Value $NewUserData
例: インスタンスユーザーデータを表示する

インスタンスのユーザーデータを取得するには、Get-EC2InstanceAttribute コマンドを使用します。

PS C:\> (Get-EC2InstanceAttribute -InstanceId i-1234567890abcdef0 -Attribute userData).UserData

出力例を次に示します。ユーザーデータはエンコードされていることに注意してください。

PHBvd2Vyc2hlbGw+DQpSZW5hbWUtQ29tcHV0ZXIgLU5ld05hbWUgdXNlci1kYXRhLXRlc3QNCjwvcG93ZXJzaGVsbD4=

次のコマンドを使用して、エンコードされたユーザーデータを変数に格納し、それをデコードします。

PS C:\> $UserData_encoded = (Get-EC2InstanceAttribute -InstanceId i-1234567890abcdef0 -Attribute userData).UserData
PS C:\> [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($UserData_encoded))

出力例を次に示します。

<powershell>
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
</powershell>
<persist>true</persist>
例: タグ値と合うようにインスタンスの名前を変更する

Get-EC2Tag コマンドを使用してタグ値を読み出し、タグ値と一致するように最初の起動時にインスタンスの名前を変更して、再起動することができます。タグ情報は API コールで取得されるため、このコマンドを適切に実行するには、ec2:DescribeTags アクセス許可が付与されているロールがインスタンスにアタッチされている必要があります。IAM ロールを使用した設定のアクセス許可の詳細については、「IAM ロールをインスタンスにアタッチする」を参照してください。

注記

このスクリプトは、2008 より前のバージョンの Windows Server ではエラーになります。

<powershell>
$instanceId = (invoke-webrequest http://169.254.169.254/latest/meta-data/instance-id -UseBasicParsing).content
$nameValue = (get-ec2tag -filter @{Name="resource-id";Value=$instanceid},@{Name="key";Value="Name"}).Value
$pattern = "^(?![0-9]{1,15}$)[a-zA-Z0-9-]{1,15}$"
#Verify Name Value satisfies best practices for Windows hostnames
If ($nameValue -match $pattern) 
    {Try
        {Rename-Computer -NewName $nameValue -Restart -ErrorAction Stop} 
    Catch
        {$ErrorMessage = $_.Exception.Message
        Write-Output "Rename failed: $ErrorMessage"}}
Else
    {Throw "Provided name not a valid hostname. Please ensure Name value is between 1 and 15 characters in length and contains only alphanumeric or hyphen characters"}
</powershell>

インスタンスメタデータからタグにアクセスするようにインスタンスが設定されている場合は、インスタンスメタデータ内のタグを使用してインスタンスの名前を変更することもできます。

注記

このスクリプトは、2008 より前のバージョンの Windows Server ではエラーになります。

<powershell>
$nameValue = Get-EC2InstanceMetadata -Path /tags/instance/Name
$pattern = "^(?![0-9]{1,15}$)[a-zA-Z0-9-]{1,15}$"
#Verify Name Value satisfies best practices for Windows hostnames
If ($nameValue -match $pattern) 
    {Try
        {Rename-Computer -NewName $nameValue -Restart -ErrorAction Stop} 
    Catch
        {$ErrorMessage = $_.Exception.Message
        Write-Output "Rename failed: $ErrorMessage"}}
Else
    {Throw "Provided name not a valid hostname. Please ensure Name value is between 1 and 15 characters in length and contains only alphanumeric or hyphen characters"}
</powershell>