メニュー
AWS CloudFormation
ユーザーガイド (API Version 2010-05-15)

AWS::CloudFormation::Init

AWS::CloudFormation::Init タイプを使用して、cfn-init ヘルパースクリプト用のメタデータを Amazon EC2 インスタンスに取り込みます。テンプレートが cfn-init スクリプトを呼び出す場合、スクリプトは AWS::CloudFormation::Init メタデータキーをルートとするリソースメタデータを検索します。cfn-init の詳細については、「cfn-init」を参照してください。

cfn-init は、Linux システムのすべてのメタデータの種類をサポートしています。以降のセクションで説明されている条件付きで、Windows のメタデータの種類もサポートしています。

AWS::CloudFormation::Init と cfn-init ヘルパースクリプトの使用例については、「AWS CloudFormation による Amazon EC2 へのアプリケーションのデプロイ」を参照してください。

cfn-init を使用して Windows スタックを作成する方法の例については、「AWS CloudFormation の Windows スタックのブートストラップ」を参照してください。

構文

設定は、いくつかのセクションに分かれています。以下のテンプレートスニペットは、テンプレート内の Amazon EC2 インスタンスリソースに cfn-init 用のメタデータをアタッチする方法を示しています。

メタデータは、設定キーに編成されます。これを configset にグループ化することができます。テンプレートで cfn-init を呼び出すときに、configset を指定できます。configset を指定しない場合、cfn-init は config という設定キーを探します。

注記

cfn-init ヘルパースクリプトは、次の手順でこれらの設定セクションを処理します。パッケージ、グループ、ユーザー、ソース、ファイル、コマンド、そしてサービスの順です。別の順番にする場合は、セクションを別の設定キーに分割し、設定キーが処理される順序を指定する configset を使用します。

JSON

Copy
"Resources": { "MyInstance": { "Type": "AWS::EC2::Instance", "Metadata" : { "AWS::CloudFormation::Init" : { "config" : { "packages" : { : }, "groups" : { : }, "users" : { : }, "sources" : { : }, "files" : { : }, "commands" : { : }, "services" : { : } } } }, "Properties": { : } } }

YAML

Copy
Resources: MyInstance: Type: "AWS::EC2::Instance" Metadata: AWS::CloudFormation::Init: config: packages: : groups: : users: : sources: : files: : commands: : services: : Properties: :

Configset

複数の設定キーを作成し、特定の順序で cfn-init によって処理されるようにする場合は、目的の順序で設定キーが含まれている configset を作成します。

単一の Configset

次のテンプレートスニペットは、ascendingdescending という configset を作成します。それぞれに、2 つの設定キーが含まれます。

JSON

Copy
"AWS::CloudFormation::Init" : { "configSets" : { "ascending" : [ "config1" , "config2" ], "descending" : [ "config2" , "config1" ] }, "config1" : { "commands" : { "test" : { "command" : "echo \"$CFNTEST\" > test.txt", "env" : { "CFNTEST" : "I come from config1." }, "cwd" : "~" } } }, "config2" : { "commands" : { "test" : { "command" : "echo \"$CFNTEST\" > test.txt", "env" : { "CFNTEST" : "I come from config2" }, "cwd" : "~" } } } }

YAML

Copy
AWS::CloudFormation::Init: configSets: ascending: - "config1" - "config2" descending: - "config2" - "config1" config1: commands: test: command: "echo \"$CFNTEST\" > test.txt" env: CFNTEST: "I come from config1." cwd: "~" config2: commands: test: command: "echo \"$CFNTEST\" > test.txt" env: CFNTEST: "I come from config2" cwd: "~"

関連した cfn-init の呼び出し

次の例は、前の例の configset を参照する cfn-init を呼び出します。例に示した呼び出しは、わかりやすくするために簡略化されています。完全な構文については、「cfn-init」を参照してください。

  • cfn-init への呼び出しが ascending configset を指定する場合は、次のようになります。

    Copy
    cfn-init -c ascending

    スクリプトは config1 を処理してから config2 を処理し、test.txt ファイルに含まれるテキストは I come from config2 になります。

  • cfn-init への呼び出しが descending configset を指定する場合は、次のようになります。

    Copy
    cfn-init -c descending

    スクリプトは config2 を処理してから config1 を処理し、test.txt ファイルに含まれるテキストは I come from config1 になります。

複数の Configset

複数の configset を作成し、これらを cfn-init スクリプトで呼び出すことができます。各 configset には、設定キーや他の configset への参照のリストを含めることができます。たとえば、次のテンプレートスニペットは 3 個の configset を作成します。最初の configset (test1) には、1 という名前の設定キーが含まれます。2 つ目の configset (test2) には、test1 configset への参照と、2 という名前の設定キーが含まれています。3 つ目の configset (デフォルト) には、configset test2 への参照が含まれています。

JSON

Copy
"AWS::CloudFormation::Init" : { "configSets" : { "test1" : [ "1" ], "test2" : [ { "ConfigSet" : "test1" }, "2" ], "default" : [ { "ConfigSet" : "test2" } ] }, "1" : { "commands" : { "test" : { "command" : "echo \"$MAGIC\" > test.txt", "env" : { "MAGIC" : "I come from the environment!" }, "cwd" : "~" } } }, "2" : { "commands" : { "test" : { "command" : "echo \"$MAGIC\" >> test.txt", "env" : { "MAGIC" : "I am test 2!" }, "cwd" : "~" } } } }

YAML

Copy
AWS::CloudFormation::Init: 1: commands: test: command: "echo \"$MAGIC\" > test.txt" env: MAGIC: "I come from the environment!" cwd: "~" 2: commands: test: command: "echo \"$MAGIC\" >> test.txt" env: MAGIC: "I am test 2!" cwd: "~" configSets: test1: - "1" test2: - ConfigSet: "test1" - "2" default: - ConfigSet: "test2"

関連した cfn-init の呼び出し

以下の cfn-init への呼び出しは、前のテンプレートスニペットで宣言されている configset を参照します。例に示した呼び出しは、わかりやすくするために簡略化されています。完全な構文については、「cfn-init」を参照してください。

  • test1 のみを指定する場合は、次のようになります。

    Copy
    cfn-init -c test1

    cfn-init は設定キー 1 のみを処理します。

  • test2 のみを指定する場合は、次のようになります。

    Copy
    cfn-init -c test2

    cfn-init は設定キー 1 を処理し、その後、設定キー 2 を処理します。

  • default configset を指定する (または configset をまったく指定しない) 場合は、次のようになります。

    Copy
    cfn-init -c default

    configset test2 を指定した場合と同じ動作になります。

コマンド

commands キーを使用すると、EC2 インスタンスでコマンドを実行できます。コマンドは、名前のアルファベット順に処理されます。

キー 説明

コマンド

必須実行するコマンドを指定する配列または文字列です。配列を使用する場合、スペース文字をエスケープしたり、コマンドパラメーターを引用符で囲んだりする必要はありません。配列を使用して複数のコマンドを指定しないでください。

env

オプション。コマンドの環境変数を設定します。このプロパティは、既存の環境に追加するのではなく、既存の環境を上書きします。

cwd

オプション。作業ディレクトリです。

テスト

オプション。command キーに指定されているコマンドが cfn-init で実行されるかどうかを決定するテストコマンドです。テストが成功すると、cloud-init はコマンドを実行します。 cfn-init スクリプトは、Bash や cmd.exe などのコマンドインタープリタ内でテストを実行します。テストの合否は、インタープリタが返す終了コードによって決まります。

Linux の場合、テストを成功するためには、テストコマンドが終了コード 0 を返す必要があります。 Windows の場合、テストコマンドで %ERRORLEVEL% が 0 として返される必要があります。

ignoreErrors

オプション。コマンドキーに含まれているコマンドが失敗した (非ゼロ値を返した) 場合に cfn-init を実行し続けるかどうかを指定するブール値です。コマンドが失敗しても cfn-init の実行を続ける場合は、true に設定します。コマンドが失敗したら cfn-init の実行を停止する場合は、false に設定します。デフォルト値は false です。

waitAfterCompletion

オプション。Windows システムの場合のみ。コマンドによって再起動が行われる場合に、コマンド終了後にどのぐらい待機するかを指定します (秒単位)。デフォルト値は 60 秒です。値を "forever" にすると、cfn-init が終了し、再起動が完了した後に再開されます。

次の例では、~/test.txt ファイルが存在しない場合に、スニペットが echo コマンドを呼び出します。

JSON

Copy
"commands" : { "test" : { "command" : "echo \"$MAGIC\" > test.txt", "env" : { "MAGIC" : "I come from the environment!" }, "cwd" : "~", "test" : "test ! -e ~/test.txt", "ignoreErrors" : "false" }, "test2" : { "command" : "echo \"$MAGIC2\" > test2.txt", "env" : { "MAGIC2" : "I come from the environment!" }, "cwd" : "~", "test" : "test ! -e ~/test2.txt", "ignoreErrors" : "false" } }

YAML

Copy
commands: test: command: "echo \"$MAGIC\" > test.txt" env: MAGIC: "I come from the environment!" cwd: "~" test: "test ! -e ~/test.txt" ignoreErrors: "false" test2: command: "echo \"$MAGIC2\" > test2.txt" env: MAGIC2: "I come from the environment!" cwd: "~" test: "test ! -e ~/test2.txt" ignoreErrors: "false"

ファイル

files キーを使用すると、EC2 インスタンス上にファイルを作成できます。内容は、テンプレートにおいてインラインで指定することも、URL から取得することもできます。ファイルは辞書式順序でディスクに書き込まれます。次の表ではサポートされるキーの一覧を示します。

キー 説明

コンテンツ

文字列または適切な書式の JSON オブジェクトです。コンテンツとして JSON オブジェクトを使用すると、JSON はディスク上のファイルに書き込まれます。JSON オブジェクトがディスクに書き込まれる前に、Fn::GetAtt や Ref などの組み込み関数が評価されます。シンボリックリンクを作成する場合には、コンテンツとしてシンボリックリンクターゲットを指定します。

注記

シンボリックリンクを作成すると、ヘルパースクリプトによってターゲットファイルのアクセス許可が変更されます。現在、ターゲットファイルのアクセス許可を変更することなくシンボリックリンクを作成することはできません。

source

ファイルの読み込み元の URL です。このオプションと content キーを一緒に指定することはできません。

encoding

エンコード形式です。内容が文字列の場合にのみ使用します。source を使用している場合、エンコードは適用されません。

有効な値: plain | base64

グループ

このファイルの所有グループの名前です。Windows システムではサポートされていません。

owner

このファイルの所有ユーザーの名前です。Windows システムではサポートされていません。

mode

このファイルのモードを表す 6 桁の 8 進値です。Windows システムではサポートされていません。最初の 3 桁はシンボリックリンクに使用し、最後の 3 桁は権限の設定に使用します。シンボリックリンクを作成するには、120xxx を指定します (xxx はターゲットファイルのアクセス許可を定義します)。ファイルのアクセス許可を指定するには、「000644」のように後半 3 桁の数字を使用します。

認証

使用する認証方法の名前です。これはデフォルトの認証を無効にします。AWS::CloudFormation::Authentication リソースで定義する認証方法を選択するために、このプロパティを使用できます。

context

Mustache テンプレートとして処理されるファイルのコンテキストを指定します。このキーを使用するには、aws-cfn-bootstrap 1.3-11 以降と pystache がインストールされている必要があります。

以下の例では、インストールの一部として setup.mysql というファイルを作成します。

JSON

Copy
"files" : { "/tmp/setup.mysql" : { "content" : { "Fn::Join" : ["", [ "CREATE DATABASE ", { "Ref" : "DBName" }, ";\n", "CREATE USER '", { "Ref" : "DBUsername" }, "'@'localhost' IDENTIFIED BY '", { "Ref" : "DBPassword" }, "';\n", "GRANT ALL ON ", { "Ref" : "DBName" }, ".* TO '", { "Ref" : "DBUsername" }, "'@'localhost';\n", "FLUSH PRIVILEGES;\n" ]]}, "mode" : "000644", "owner" : "root", "group" : "root" } }

YAML

Copy
files: /tmp/setup.mysql: content: !Sub | CREATE DATABASE ${DBName}; CREATE USER '${DBUsername}'@'localhost' IDENTIFIED BY '${DBPassword}'; GRANT ALL ON ${DBName}.* TO '${DBUsername}'@'localhost'; FLUSH PRIVILEGES; mode: "000644" owner: "root" group: "root"

完全なテンプレートは、https://s3.amazonaws.com/cloudformation-templates-us-east-1/Drupal_Single_Instance.template です。

次のサンプルスニペットでは、既存のファイル /tmp/myfile2.txt をポイントするシンボリックリンク /tmp/myfile1.txt を作成します。ターゲットファイル /tmp/myfile1.txt のアクセス許可は、モード値 644 によって定義されます。

JSON

Copy
"files" : { "/tmp/myfile2.txt" : { "content" : "/tmp/myfile1.txt", "mode" : "120644" } }

YAML

Copy
files: /tmp/myfile2.txt: content: "/tmp/myfile1.txt" mode: "120644"

Mustache テンプレートは、設定ファイルを作成するために主に使用されます。たとえば、Fn::Join を使用する代わりに、S3 バケットに設定ファイルを保存して、テンプレートから Refs と GetAtts を挿入できます。以下の例では、/tmp/test9.txt に "Content for test9" が出力されます。

JSON

Copy
"files" : { "/tmp/test9.txt" : { "content" : "Content for {{name}}", "context" : { "name" : "test9" } } }

YAML

Copy
files: /tmp/test9.txt: content: "Content for {{name}}" context: name: "test9"

Mustache テンプレートを使用する場合、次の点に注意してください。

  • ファイルが処理されるには、コンテキストキーが存在する必要があります。

  • コンテキストキーは、キーと値のマッピングである必要がありますが、入れ子にすることができます。

  • コンテンツキーを使用してインラインコンテンツを含むファイルを処理し、ソースキーを使用してリモートファイルを処理できます。

  • Mustache サポートは、pystache のバージョンによって決まります。バージョン 0.5.2 は、Mustache 1.1.2 仕様をサポートします。

グループ

groups キーを使用すると、Linux/UNIX グループを作成して、グループ ID を割り当てることができます。groups キーは Windows システムではサポートされません。

グループを作成するには、新しいグループ名をオプションのグループ ID に関連付ける新しいキーと値のペアを追加します。groups キーでは、1 つまたは複数のグループ名を指定できます。次の表では使用できるキーの一覧を示します。

キー 説明

gid

グループ ID 番号です。

グループ ID を指定し、同じ名前のグループが既に存在する場合、グループの作成は失敗します。指定したグループ ID が別のグループに割り当てられている場合、OS はグループの作成を拒否することがあります。

例: { "gid" : "23" }

次の例では、groupOne という名前のグループをグループ ID なしで指定し、groupTwo という名前のグループをグループ ID 値 45 で指定しています。

JSON

Copy
"groups" : { "groupOne" : {}, "groupTwo" : { "gid" : "45" } }

YAML

Copy
groups: groupOne: {} groupTwo: gid: "45"

パッケージ

パッケージキーを使用して、パッケージ済みのアプリケーションとコンポーネントをダウンロードしてインストールできます。Windows システムでは、パッケージキーは MSI インストーラのみをサポートします。

サポートされるパッケージ形式

cfn-init スクリプトで現在サポートされているパッケージ形式は、apt、msi、python、rpm、rubygems、および yum です。パッケージは、rpm、yum/apt、rubygems および python の順序で処理されます。rubygems と python の間に順序はなく、各パッケージマネージャ内のパッケージのインストール順序に保証はありません。

バージョンの指定

各パッケージマネージャ内では、各パッケージはパッケージ名およびバージョンのリストとして指定されます。バージョンは、文字列、バージョンのリスト、あるいは空の文字列またはリストのいずれでもかまいません。空の文字列またはリストは、最新バージョンを指定することを示します。rpm マネージャの場合、バージョンはディスク上のファイルへのパスまたは URL として指定します。

パッケージのバージョンを指定した場合は、それより新しいバージョンのパッケージがインスタンスに既にインストールされていたとしても、指定されたバージョンのインストールが試みられます。パッケージマネージャには、複数のバージョンをサポートするものと、サポートしないものがあります。詳細については、パッケージマネージャのドキュメントを調べてください。バージョンを指定せず、あるバージョンのパッケージが既にインストールされている場合は、cfn-init スクリプトは新しいバージョンをインストールせず、ユーザーが既存のバージョンを維持して使用することを望んでいるものと想定します。

RPM、yum、および Rubygems

次の例では、rpm のバージョン URL を指定し、yum から最新のバージョンを要求し、rubygems から chef のバージョン 0.10.2 を要求しています。

JSON
Copy
"rpm" : { "epel" : "http://download.fedoraproject.org/pub/epel/5/i386/epel-release-5-4.noarch.rpm" }, "yum" : { "httpd" : [], "php" : [], "wordpress" : [] }, "rubygems" : { "chef" : [ "0.10.2" ] }
YAML
Copy
rpm: epel: "http://download.fedoraproject.org/pub/epel/5/i386/epel-release-5-4.noarch.rpm" yum: httpd: [] php: [] wordpress: [] rubygems: chef: - "0.10.2"

MSI パッケージ

次のスニペットは、MSI パッケージの URL を指定します。

JSON
Copy
"msi" : { "awscli" : "https://s3.amazonaws.com/aws-cli/AWSCLI64.msi" }
YAML
Copy
msi: awscli: "https://s3.amazonaws.com/aws-cli/AWSCLI64.msi"

サービス

services キーを使用すると、インスタンスが起動されるときに有効化または無効化する必要のあるサービスを定義できます。Linux システムでは、このキーは sysvinit を使用してサポートされています。Windows システムでは、Windows サービスマネージャーを使用してサポートされています。

また、services キーではソース、パッケージ、ファイルへの依存関係も指定でき、インストールされているファイルのために再起動が必要になった場合に、cfn-init がサービスの再起動を処理します。たとえば、Apache HTTP Server パッケージをダウンロードする場合は、スタックの作成プロセス中にパッケージインストールが自動的に Apache HTTP Server を起動します。ただし、Apache HTTP Server 設定がスタック作成プロセスの後の方で更新されると、その更新は Apache サーバーが再起動されなければ有効になりません。Apache HTTP サービスが必ず再起動されるようにするために services キーを使用できます。

次の表ではサポートされるキーの一覧を示します。

キー 説明

ensureRunning

true に設定すると、cfn-init が終了した後でサービスが実行されます。

false に設定すると、cfn-init が終了した後でサービスが実行されません。

このキーを省略すると、サービスの状態は変更されません。

有効

true に設定すると、起動時にサービスが自動的に開始されます。

false に設定すると、起動時にサービスが自動的に開始されません。

このキーを省略すると、このプロパティは変更されません。

files

ファイルのリストです。cfn-init がファイルブロックによっていずれかを直接変更する場合、このサービスは再起動されます。

sources

ディレクトリのリストです。cfn-init がこれらのディレクトリの 1 つにアーカイブを展開する場合、このサービスは再起動されます。

packages

パッケージ名のリストに対するパッケージマネージャのマップです。cfn-init がこれらのパッケージの 1 つをインストールまたは更新する場合、このサービスは再起動されます。

commands

コマンド名のリストです。cfn-init が指定したコマンドを実行する場合、このサービスは再開されます。

Linux

次に示す Linux スニペットは次のようにサービスを設定します。

  • nginx サービスは、/etc/nginx/nginx.conf または /var/www/html が cfn-init によって変更される場合、再起動されます。

  • php-fastcgi サービスは、cfn-init が yum を使用して php または spawn-fcgi をインストールまたは更新する場合、再起動されます。

  • sendmail サービスは停止され、無効になります。

JSON
Copy
"services" : { "sysvinit" : { "nginx" : { "enabled" : "true", "ensureRunning" : "true", "files" : ["/etc/nginx/nginx.conf"], "sources" : ["/var/www/html"] }, "php-fastcgi" : { "enabled" : "true", "ensureRunning" : "true", "packages" : { "yum" : ["php", "spawn-fcgi"] } }, "sendmail" : { "enabled" : "false", "ensureRunning" : "false" } } }
YAML
Copy
services: sysvinit: nginx: enabled: "true" ensureRunning: "true" files: - "/etc/nginx/nginx.conf" sources: - "/var/www/html" php-fastcgi: enabled: "true" ensureRunning: "true" packages: yum: - "php" - "spawn-fcgi" sendmail: enabled: "false" ensureRunning: "false"

Windows

次の Windows スニペットは、cfn-hup サービスを開始し、それを自動に設定します。指定された設定ファイルを cfn-init が変更する場合は、サービスを再起動します。

JSON
Copy
"services" : { "windows" : { "cfn-hup" : { "enabled" : "true", "ensureRunning" : "true", "files" : ["c:\\cfn\\cfn-hup.conf", "c:\\cfn\\hooks.d\\cfn-auto-reloader.conf"] } } }
YAML
Copy
services: windows: cfn-hup: enabled: "true" ensureRunning: "true" files: - "c:\\cfn\\cfn-hup.conf" - "c:\\cfn\\hooks.d\\cfn-auto-reloader.conf"

sources

sources キーを使用すると、アーカイブファイルをダウンロードし、EC2 インスタンス上のターゲットディレクトリに解凍できます。このキーは Linux と Windows の両方のシステムで完全にサポートされています。

サポートされる形式

サポートされる形式は、tar、tar+gzip、tar+bz2、zip です。

GitHub

ソース管理システムとして GitHub を使用する場合は、cfn-init とソースパッケージメカニズムを使用して、アプリケーションの特定のバージョンを取得します。GitHub では次のように URL を通じて特定のバージョンから zip または tar を作成することができます。

Copy
https://github.com/<your directory>/(zipball|tarball)/<version>

たとえば、次のスニペットはバージョン master.tar ファイルとして取り出します。

JSON
Copy
"sources" : { "/etc/puppet" : "https://github.com/user1/cfn-demo/tarball/master" }
YAML
Copy
sources: /etc/puppet: "https://github.com/user1/cfn-demo/tarball/master"

S3 バケット

次の例では、.zip ファイルを Amazon S3 バケットからダウンロードし、/etc/myapp に解凍しています。

注記

ソースの認証情報を使用できます。ただし、ソースブロックに認証キーを格納することはできません。代わりに、S3AccessCreds ブロックにバケットキーを含めます。例については、サンプルテンプレートを参照してください。Amazon S3 認証情報の詳細については、「AWS::CloudFormation::Authentication」を参照してください。

JSON
Copy
"sources" : { "/etc/myapp" : "https://s3.amazonaws.com/mybucket/myapp.tar.gz" }
YAML
Copy
sources: /etc/myapp: "https://s3.amazonaws.com/mybucket/myapp.tar.gz"

ユーザー

users キーを使用すると、Linux/UNIX ユーザーを EC2 インスタンス上に作成できます。users キーは Windows システムではサポートされません。

次の表ではサポートされるキーの一覧を示します。

キー 説明

uid

ユーザー ID です。異なるユーザー ID で同じユーザー名が存在した場合、作成処理は失敗します。ユーザー ID が既存のユーザーに既に割り当てあれている場合、オペレーティングシステムは作成要求を拒否することがあります。

グループ

グループ名のリストです。ユーザーはリスト内の各グループに追加されます。

homeDir

ユーザーのホームディレクトリです。

ユーザーは、/sbin/nologin のシェルで非対話形式のシステムユーザーとして作成されます。これは設計によるものであり、変更できません。

JSON

Copy
"users" : { "myUser" : { "groups" : ["groupOne", "groupTwo"], "uid" : "50", "homeDir" : "/tmp" } }

YAML

Copy
users: myUser: groups: - "groupOne" - "groupTwo" uid: "50" homeDir: "/tmp"