AWS::CloudFormation::Init - AWS CloudFormation

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 スタックのブートストラップ」を参照してください。

Syntax

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

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

注記

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

JSON

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

YAML

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

Amazon EC2 インスタンスの AWS::CloudFormation::Init プロパティを指定するには、 Amazon Linux の例を参照してください。

Configset

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

単一の Configset

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

JSON

"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

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 を指定する場合は、次のようになります。

    cfn-init -c ascending

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

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

    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

"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

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 のみを指定する場合は、次のようになります。

    cfn-init -c test1

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

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

    cfn-init -c test2

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

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

    cfn-init -c default

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

コマンド

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

キー 必要 説明

コマンド

必須

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

env

オプションです。

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

cwd

オプションです。

作業ディレクトリ。

test

オプションです。

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 が終了し、再起動が完了した後に再開されます。すべてのコマンドを待ちたくない場合、この値を 0 に設定します。

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

JSON

"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

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 から取得することもできます。ファイルは辞書式順序でディスクに書き込まれます。次の表ではサポートされるキーの一覧を示します。

キー 説明

content

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

注記

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

ソース

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

encoding

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

有効な値: plain | base64

グループ

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

owner (オーナー)

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

mode

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

認証

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

context

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

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

JSON

"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

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

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

YAML

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

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

JSON

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

YAML

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

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

YAML

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

パッケージ

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

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

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

バージョンの指定

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

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

RPM、yum、Rubygems および Zypper

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

JSON
"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" ] }, "zypper" : { "git" : [] }
YAML
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" zypper: git: []

MSI パッケージ

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

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

サービス

services キーを使用すると、インスタンスが起動されるときに有効化または無効化する必要のあるサービスを定義できます。Linux システムでは、このキーは sysvinit または systemd を使用してサポートされています。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 に設定すると、起動時にサービスが自動的に開始されません。

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

ファイル

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

sources

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

パッケージ

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

commands

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

Linux

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

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

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

  • systemd を使用して sendmail サービスは停止され、無効になります。

JSON
"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"] } } }, "systemd": { "sendmail" : { "enabled" : "false", "ensureRunning" : "false" } } }
YAML
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" systemd: sendmail: enabled: "false" ensureRunning: "false"

サービスで systemd を使用するには、サービスに systemd ユニットファイルが設定されている必要があります。次のユニットファイルにより、systemd はマルチユーザーサービスターゲットの cfn-hup デーモンを開始および停止します。

[Unit] Description=cfn-hup daemon [Service] ExecStart=/usr/bin/cfn-hup -v PIDFile=/var/run/cfn-hup.pid [Install] WantedBy=multi-user.target

この構成は、cfn-hup が /usr/bin/ ディレクトリにインストールされていることを想定しています。ただし、cfn-hup がインストールされている実際の場所は、プラットフォームによって異なる可能性があります。/etc/systemd/system/cfn-hup.service.d/override.conf にオーバーライドファイルを作成することにより、この構成を以下のようにオーバーライドできます。

# In this example, cfn-hup executable is available under /usr/local/bin [Service] ExecStart= ExecStart=/usr/local/bin/cfn-hup -v

Windows

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

JSON
"services" : { "windows" : { "cfn-hup" : { "enabled" : "true", "ensureRunning" : "true", "files" : ["c:\\cfn\\cfn-hup.conf", "c:\\cfn\\hooks.d\\cfn-auto-reloader.conf"] } } }
YAML
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 を作成することができます。

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

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

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

S3 バケット

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

注記

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

例については、「サンプルテンプレート」を参照してください。

JSON
"sources" : { "/etc/myapp" : "https://s3.amazonaws.com/mybucket/myapp.tar.gz" }
YAML
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

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

YAML

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