ユーザーデータ入力を使用して EC2 インスタンスを起動するときにコマンドを実行する

Amazon EC2 インスタンスの起動時に、インスタンスの起動後に自動設定タスクを実行したり、スクリプトを実行したりするのに使用するインスタンスにユーザーデータを渡すことができます。

より複雑なオートメーションのシナリオに興味がある場合、CloudFormation を検討してください。詳細については、「AWS CloudFormation ユーザーガイド」の「CloudFormation を使用して Amazon EC2 でアプリケーションのデプロイ」を参照してください。

Linux インスタンスでは、シェルスクリプトと cloud-init ディレクティブという 2 つのタイプのユーザーデータを Amazon EC2 に渡すことができます。また、このデータは、プレーンテキスト、ファイル (コマンドラインツールを使用してインスタンスを起動する場合に便利です)、または base64 でエンコードされたテキスト (API コール向け) で、インスタンス起動ウィザードに渡すこともできます。

Windows インスタンスでは、起動エージェントがユーザーデータスクリプトを処理します。

AWS マネジメントコンソール のユーザーデータ

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

Launch Wizard を使用して起動時にインスタンスのユーザーデータを指定する

EC2 コンソールで Launch Wizard を使用してインスタンスを起動するときに、ユーザーデータを指定できます。起動時にユーザーデータを指定するには、インスタンスを起動する手順に従います。[User data] (ユーザーデータ) フィールドは、インスタンス起動ウィザードの 高度な詳細 セクションにあります。PowerShell スクリプトを [ユーザーデータ]  フィールドに入力し、インスタンスの起動手順を完了します。

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

詳細については、「Launch Wizard を使用して起動時にインスタンスのユーザーデータを指定する」を参照してください。AWS CLI を使用するの Linux の例については、「ユーザーデータと AWS CLI」を参照してください。Windows PowerShell用ツール を使用する Windows の例については、「ユーザーデータと Windows PowerShell用ツール」を参照してください。

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

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

Amazon EC2 が Linux インスタンスのユーザーデータを処理する方法

次の例は、ユーザーデータを使用して、インスタンスの起動時に LAMP サーバーをセットアップするコマンドを実行します。各例では、次のタスクが実行されます。

前提条件

このトピックの例では、

ユーザーデータとシェルスクリプト

シェルスクリプトに慣れている場合は、この方法が最も簡単で完全に起動時に指示を送信する方法です。起動時にこれらのタスクを追加すると、インスタンスの起動にかかる時間が増えます。タスクが完了するまでさらに数分待ち、それからユーザースクリプトが正常に完了したことをテストしてください。

ユーザーデータのシェルスクリプトは、#! の記号と、スクリプトを読み取るインタープリタのパス (通常は /bin/bash)) から始める必要があります。シェルスクリプトの概要については、GNU オペレーティングシステムのウェブサイトにある「Bash Reference Manual」を参照してください。

ユーザーデータとして入力されたスクリプトはルートユーザーとして実行されます。そのため、スクリプトでは sudo コマンドを使用しないでください。作成したファイルはすべてルートユーザーの所有になることを忘れないでください。ルート以外のユーザーにファイルアクセスを与える場合、スクリプトで許可を適宜変更する必要があります。また、スクリプトはインタラクティブに実行されないため、ユーザーフィードバックを必要とするコマンド (yum update フラグのない -y など) を含めることはできません。

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

cloud-init 出力ログファイルでコンソール出力がキャプチャされるため、インスタンスが意図したように動作しない場合でも、起動後、簡単にスクリプトをデバッグすることができます。ログファイルを表示するには、インスタンスに接続し、/var/log/cloud-init-output.log を開きます。

ユーザーデータスクリプトを処理すると、/var/lib/cloud/instances/instance-id/ にコピーされ、実行されます。実行後にスクリプトを削除することはできません。必ず /var/lib/cloud/instances/instance-id/ のユーザーデータスクリプトを削除してから、インスタンスに AMI を作成してください。それ以外の場合、スクリプトはこの AMI から起動されたインスタンスのこのディレクトリに存在します。

インスタンスのユーザーデータを更新する

インスタンスのユーザーデータを更新するには、まずインスタンスを停止する必要があります。インスタンスが実行されている場合は、ユーザーデータを表示できますが、変更することはできません。

ユーザーデータと cloud-init ディレクティブ

cloud-init パッケージは、新しい Amazon Linux インスタンスが起動したときに、特定の側面を設定します。具体的には、お客様のプライベートキーでログインできるように、ec2-user の .ssh/authorized_keys ファイルを設定します。Amazon Linux インスタンスに対して cloud-init パッケージが実行する設定タスクの詳細については、次のドキュメントを参照してください。

構文は異なりますが、渡されたスクリプトと同じ方法で cloud-init ユーザーディレクティブを起動時のインスタンスに渡すことができます。cloud-init の詳細については、https://cloudinit.readthedocs.org/en/latest/index.html を参照してください。

起動時にこれらのタスクを追加すると、インスタンスの起動にかかる時間が増えます。タスクが完了するまでさらに数分待ち、それからユーザーデータディレクティブが完了したことをテストしてください。

ユーザーデータと AWS CLI

AWS CLI を使用して、インスタンスのユーザーデータを指定、変更、表示することができます。インスタンスのメタデータを使用して、インスタンスからユーザーデータを表示する方法については、EC2 インスタンスのインスタンスメタデータにアクセスするを参照してください。

Windows では、AWS Tools for Windows PowerShell を使用する代わりに AWS CLI を使用できます。詳細については、「ユーザーデータと Windows PowerShell用ツール」を参照してください。

例: ユーザーデータは、起動時に指定します。

インスタンスの起動時にユーザーデータを指定するには、run-instances コマンドと --user-data パラメータを使用します。run-instances で、AWS CLI はユーザーデータの base64 エンコードを実行します。

次の例は、コマンドラインで文字列としてスクリプトを指定する方法を示しています。

aws ec2 run-instances --image-id ami-abcd1234 --count 1 --instance-type m3.medium \
    --key-name my-key-pair --subnet-id subnet-abcd1234 --security-group-ids sg-abcd1234 \
    --user-data echo user data

次の例は、テキストファイルを使用してスクリプトを指定する方法を示しています。ファイルを指定するには、必ず file:// プレフィクスを使用してください。

aws ec2 run-instances --image-id ami-abcd1234 --count 1 --instance-type m3.medium \
    --key-name my-key-pair --subnet-id subnet-abcd1234 --security-group-ids sg-abcd1234 \
    --user-data file://my_script.txt

シェルスクリプトを使用したテキストファイルの例を次に示します。

#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on

例: 停止しているインスタンスのユーザーデータを変更する

停止したインスタンスのユーザーデータは、modify-instance-attribute コマンドを使用して変更できます。modify-instance-attribute では、AWS CLI はユーザーデータの base64 エンコードを実行しません。

--attribute および --value パラメータを使用して、エンコードされたテキストファイルを使用してユーザーデータを指定します。ファイルを指定するには、必ず file:// プレフィクスを使用してください。

aws ec2 modify-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData --value file://my_script_base64.txt

例: 停止しているインスタンスのユーザーデータをクリアする

既存のユーザーデータを削除するには、次の modify-instance-attribute コマンドを使用します。

aws ec2 modify-instance-attribute --instance-id i-1234567890abcdef0 --user-data Value=

例: ユーザーデータの表示

インスタンスのユーザーデータを取得するには、describe-instance-attribute コマンドを使用します。describe-instance-attribute では、AWS CLI はユーザーデータの base64 デコードを実行しません。

aws ec2 describe-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData

ユーザーデータが base64 でエンコードされた出力例を次に示します。

{
    "UserData": {
        "Value": "IyEvYmluL2Jhc2gKeXVtIHVwZGF0ZSAteQpzZXJ2aWNlIGh0dHBkIHN0YXJ0CmNoa2NvbmZpZyBodHRwZCBvbg=="
    },
    "InstanceId": "i-1234567890abcdef0"
}

以下は出力の例です。

#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on

シェルスクリプトと cloud-init ディレクティブを組み合わせる

デフォルトでは、ユーザーデータに含めることができるコンテンツタイプは一度に 1 つだけです。ただし、MIME マルチパートファイルの中で text/cloud-config と text/x-shellscript のコンテンツタイプを使用して、ユーザーデータにシェルスクリプトと cloud-init ディレクティブの両方を含めることは可能です。

以下に、MIME マルチパートの形式を示します。

Content-Type: multipart/mixed; boundary="//"
MIME-Version: 1.0
	
--//
Content-Type: text/cloud-config; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="cloud-config.txt"
	
#cloud-config
cloud-init directives
	
--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"
	
#!/bin/bash
shell script commands
--//--

例えば、次のユーザーデータには cloud-init ディレクティブと bash シェルスクリプトが含まれています。cloud-init ディレクティブはファイル /test-cloudinit/cloud-init.txtを作成し、そのファイルに Created by cloud-init を書き込みます。bash シェルスクリプトはファイル /test-userscript/userscript.txtを作成し、そのファイルに Created by bash shell script を書き込みます。

Content-Type: multipart/mixed; boundary="//"
MIME-Version: 1.0
	
--//
Content-Type: text/cloud-config; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="cloud-config.txt"
	
#cloud-config
runcmd:
- [ mkdir, /test-cloudinit ]
write_files:
- path: /test-cloudinit/cloud-init.txt
content: Created by cloud-init
	
--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"
	
#!/bin/bash
mkdir test-userscript
touch /test-userscript/userscript.txt
echo "Created by bash shell script" >> /test-userscript/userscript.txt
--//--

Amazon EC2 が Windows インスタンスのユーザーデータを処理する方法

Windows インスタンスでは、起動エージェントはユーザーデータに関連するタスクを実行します。詳細については次を参照してください:

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

ライフサイクルフックと連携する 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 タグを使用してバッチ スクリプトを指定します。次の例に示すように、改行を使用してコマンドを区切ります。

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

true

EC2 ローンチ v2 エージェント

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

true

Windows PowerShell スクリプトの構文

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

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

例えば、次のようになります。

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

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

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

true

タグを使用して、1 つ以上の PowerShell 引数を指定できます。引数が渡されない場合、EC2Launch と EC2Launch v2 はデフォルトで次の引数を追加します: -ExecutionPolicy Unrestricted

例:

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

-ExecutionPolicy Unrestricted -NoProfile -NonInteractive

EC2 ローンチ v2 エージェント

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

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

true

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を参照してください。

圧縮ユーザーデータ

EC2Launch v2 は、IMDS が課す上限の 16 KB を超えるユーザーデータを送信する方法として、zip 形式のユーザーデータをサポートしています。この機能を使用するには、ユーザーデータスクリプトを .zip アーカイブに圧縮してから、EC2 インスタンスに渡します。EC2Launch v2 が圧縮されたユーザーデータを検出すると、圧縮されたユーザーデータスクリプトを自動的に解凍して実行します。

標準ユーザーデータと同様に、Amazon EC2 API、またはユーザーデータの base64 エンコーディングを実行しないツールを使用している場合は、圧縮されたユーザーデータを手動でエンコードする必要があります。ユーザーデータのサイズ制限と base64 エンコーディングの詳細については、「EC2 インスタンスのインスタンスメタデータにアクセスする」を参照してください。

ユーザーデータの実行

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

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

インスタンス起動スクリプト

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

EC2Launch v2

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

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

EC2Launch

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

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

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