翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
AWS IoT Greengrass コンポーネントレシピのリファレンス
コンポーネントレシピは、コンポーネントの詳細、依存関係、アーティファクト、およびライフサイクルを定義するファイルです。コンポーネントのライフサイクルでは、コンポーネントのインストール、実行、シャットダウンなどのために実行するコマンドを指定します。AWS IoT Greengrass コアは、レシピで定義したライフサイクルを使用して、コンポーネントをインストールして実行します。AWS IoT Greengrass サービスは、コンポーネントをデプロイするときに、コアデバイスにデプロイする依存関係とアーティファクトを特定するためにレシピを使用します。
レシピでは、コンポーネントがサポートしているプラットフォームごとに、固有の依存関係とライフサイクルを定義できます。この機能を使用すれば、要件が異なる複数のプラットフォームを持つデバイスにコンポーネントをデプロイすることができます。また、この機能を使用することで、AWS IoT Greengrass がサポートしていないデバイスにコンポーネントをインストールしないようにすることもできます。
各レシピには、マニフェストのリストが含まれます。各マニフェストは、プラットフォームがそれらの要件を満たすコアデバイスに使用する一連のプラットフォーム要件、ライフサイクル、そしてアーティファクトを指定します。コアデバイスは、デバイスが満たすプラットフォーム要件が含まれる最初のマニフェストを使用します。プラットフォーム要件のないマニフェストを指定すれば、すべてのコアデバイスと一致します。
マニフェストにないグローバルライフサイクルを指定することもできます。グローバルライフサイクルでは、ライフサイクルのサブセクションを識別する選択キーを使用することができます。その後、マニフェスト内でこれらの選択キーを指定することで、マニフェストのライフサイクルに加えて、グローバルライフサイクルのこれらのセクションも使用することができます。コアデバイスは、マニフェストがライフサイクルを定義していない場合にのみ、マニフェストの選択キーを使用します。マニフェストの all
選択を使用すると、選択キーのないグローバルライフサイクルのセクションに一致させることができます。
AWS IoT Greengrass Core ソフトウェアは、コアデバイスと一致するマニフェストを選択した後、使用するライフサイクルステップを識別するために以下を実行します。
-
選択したマニフェストがライフサイクルを定義している場合、コアデバイスはそのライフサイクルを使用します。
-
選択したマニフェストがライフサイクルを定義していない場合、コアデバイスはグローバルサイクルを使用します。コアデバイスは、グローバルライフサイクルのどのセクションを使用するかを特定するために以下を実行します。
-
マニフェストが選択キーを定義している場合、コアデバイスはマニフェストの選択キーが含まれるグローバルライフサイクルのセクションを使用します。
-
マニフェストが選択キーを定義していない場合、コアデバイスはマニフェストの選択キーが含まれないグローバルライフサイクルのセクションを使用します。この動作は、
all
選択を定義するマニフェストと同じです。
-
重要
コアデバイスは、コンポーネントをインストールするにあたり、マニフェストのプラットフォーム要件を少なくとも 1 つ満たす必要があります。コアデバイスに一致するマニフェストがない場合、AWS IoT Greengrass Core ソフトウェアはコンポーネントをインストールせず、デプロイは失敗します。
レシピは JSON
レシピの検証
Greengrass は、コンポーネントバージョンの作成時に JSON または YAML コンポーネントレシピを検証します。この recipe 検証では、JSON または YAML コンポーネント recipe に一般的なエラーがないかをチェックして、潜在的なデプロイの問題を防ぎます。検証では、レシピに一般的なエラー (カンマ、中括弧、フィールドの欠落など) がないかチェックし、レシピの形式が適切であることを確認します。
recipe 検証エラーメッセージが表示された場合は、欠落しているカンマ、中括弧、またはフィールドがないか recipe を確認してください。recipe 形式 を確認して、フィールドが欠落していないことを確認します。
レシピの形式
コンポーネントのレシピを定義するときには、レシピドキュメントで次の情報を指定します。YAML と JSON 形式のレシピにも同じ構造が適用されます。
RecipeFormatVersion
-
レシピのテンプレートバージョン。次のオプションを選択します。
-
2020-01-25
-
ComponentName
-
このレシピが定義するコンポーネントの名前。コンポーネントの名前は、各リージョンの AWS アカウント で一意である必要があります。
ヒント
-
逆ドメイン名の形式にすれば、社内での名前のコリジョンを回避することができます。例えば、会社が
example.com
を所有しており、太陽エネルギープロジェクトに取り組んでいる場合は、Hello World コンポーネントの名前をcom.example.solar.HelloWorld
にすることができます。こうすることで、会社内のコンポーネント名のコリジョンを回避できます。 -
コンポーネント名に
aws.greengrass
プレフィックスを使用することは避けてください。AWS IoT Greengrass は提供するパブリックコンポーネントでこのプレフィックスを使用します。パブリックコンポーネントと同じ名前を選択すると、パブリックコンポーネントがあなたのコンポーネントに置き換えられます。そうすると、AWS IoT Greengrass がそのパブリックコンポーネントに依存するコンポーネントをデプロイするときに、パブリックコンポーネントの代わりにあなたのコンポーネントを提供してしまいます。この機能を使用すると、パブリックコンポーネントの動作を上書きできますが、パブリックコンポーネントの上書きを意図していない場合には、他のコンポーネントも破損させてしまう可能性があります。
-
ComponentVersion
-
コンポーネントのバージョン。メジャー、マイナー、パッチ値の最大値は 99999 です。
注記
AWS IoT Greengrass はコンポーネントのセマンティックバージョンを使用します。セマンティックバージョンは、major.minor.patch といった番号システムに準拠します。例えば、バージョン
1.0.0
は、コンポーネントの最初のメジャーリリースを表しています。詳細については、「セマンティックバージョンの仕様」を参照してください。 ComponentDescription
-
(オプション) コンポーネントの説明。
ComponentPublisher
-
コンポーネントのパブリッシャーまたは作成者。
ComponentConfiguration
-
(オプション) コンポーネントの設定またはパラメータを定義するオブジェクト。デフォルト設定を定義しておけば、コンポーネントをデプロイするときに、コンポーネントに提供する設定オブジェクトを指定することができます。コンポーネント設定は、ネストされたパラメータと構造をサポートします。このオブジェクトには、次の情報が含まれます。
DefaultConfiguration
-
コンポーネントのデフォルト設定を定義するオブジェクト。このオブジェクトの構造を定義します。
注記
AWS IoT Greengrass は設定値に JSON を使用します。JSON は数値タイプを指定しますが、整数と浮動小数点数を区別しません。その結果、AWS IoT Greengrass で設定値が浮動小数点数に変換されることがあります。コンポーネントが正しいデータタイプを使用することを確認するには、数値の設定値を文字列として定義することをお勧めします。次に、整数または浮動小数点としてコンポーネントでパースします。これにより、設定値が設定とコアデバイスに対して同じタイプであることを保証します。
ComponentDependencies
-
(オプション) コンポーネントのコンポーネント依存関係を定義するオブジェクトのディクショナリ。各オブジェクトのキーは、コンポーネントの依存関係の名前を識別します。AWS IoT Greengrass はコンポーネントをインストールするときに、コンポーネントの依存関係をインストールします。AWS IoT Greengrass はコンポーネントを起動する前に、依存関係が開始されるまで待機します。各オブジェクトには、次の情報が含まれます:
VersionRequirement
-
この依存関係との互換性のあるコンポーネントバージョンを定義する npm スタイルのセマンティックバージョン制約。1 つのバージョンまたはバージョンの範囲を指定できます。詳細については、「npm セマンティックバージョン計算ツール
」を参照してください。 DependencyType
-
(オプション) 依存関係のタイプ。次のオプションから選択します。
-
SOFT
- 依存関係が状態を変化させても、コンポーネントは再起動しません。 -
HARD
- 依存関係が状態を変化させると、コンポーネントは再起動します。
デフォルトは
HARD
です。 -
ComponentType
-
(オプション) コンポーネントのタイプ。
注記
レシピでコンポーネントタイプを指定することは推奨しません。AWS IoT Greengrass がコンポーネントを作成するときにタイプを設定します。
タイプは、次のいずれかになります。
-
aws.greengrass.generic
- コンポーネントはコマンドを実行するか、アーティファクトを提供します。 -
aws.greengrass.lambda
– コンポーネントは Lambda ランチャーコンポーネントを使用して、 Lambda 関数を実行します。ComponentSource
パラメータは、このコンポーネントが実行する Lambda 関数の ARN を指定します。このオプションは推奨しません。Lambda 関数からコンポーネントを作成するときに、AWS IoT Greengrass によって設定されるからです。詳細については、「AWS Lambda 関数を実行する」を参照してください。
-
aws.greengrass.plugin
– コンポーネントは Greengrass nucleus と同じ Java 仮想マシン (JVM) で実行されます。プラグインコンポーネントをデプロイするか再起動すると、Greengrass nucleus が再起動します。プラグインコンポーネントは Greengrass nucleus と同じログファイルを使用します。詳細については、「AWS IoT Greengrass ログのモニタリング」を参照してください。
コンポーネントレシピでこのオプションを使用することは推奨しません。これは、Greengrass nucleus と直接やり取りする Java で書かれた AWS から提供されたコンポーネントを意図したものだからです。どのパブリックコンポーネントがプラグインなのかの詳細については、「AWS が提供したコンポーネント」を参照してください。
-
aws.greengrass.nucleus
- nucleus コンポーネント。詳細については、「Greengrass nucleus」を参照してください。コンポーネントレシピでこのオプションを使用することは推奨しません。これは、Greengrass nucleus コンポーネントを対象としたもので、AWS IoT Greengrass Core ソフトウェアの最低限の機能のみが提供されるからです。
レシピからコンポーネントを作成する場合は
aws.greengrass.generic
、Lambda 関数からコンポーネントを作成する場合はaws.greengrass.lambda
がデフォルトです。詳細については、「コンポーネントタイプ」を参照してください。
-
ComponentSource
-
(オプション) コンポーネントが実行する Lambda 関数の ARN。
レシピでコンポーネントソースを指定することは推奨しません。Lambda 関数からコンポーネントを作成するときに、AWS IoT Greengrass がこのパラメータを設定します。詳細については、「AWS Lambda 関数を実行する」を参照してください。
-
Manifests
-
オブジェクトのリストで、各オブジェクトがコンポーネントのライフサイクル、パラメータ、およびプラットフォームに対する要件を定義しています。コアデバイスが複数のマニフェストのプラットフォーム要件と一致する場合、AWS IoT Greengrass は、コアデバイスが一致する最初のマニフェストを使用します。コアデバイスが正しいマニフェストを確実に使用するように、まずはより厳格なプラットフォーム要件を持つマニフェストを定義してください。すべてのプラットフォームに適用されるマニフェストは、リストの最後のマニフェストである必要があります。
重要
コアデバイスは、コンポーネントをインストールするにあたり、マニフェストのプラットフォーム要件を少なくとも 1 つ満たす必要があります。コアデバイスに一致するマニフェストがない場合、AWS IoT Greengrass Core ソフトウェアはコンポーネントをインストールせず、デプロイは失敗します。
各オブジェクトには、次の情報が含まれます:
Name
-
(オプション) このマニフェストが定義するプラットフォームのわかりやすい名前。
このパラメータを省略すると、AWS IoT Greengrass はプラットフォームの
os
とarchitecture
からわかりやすい名前を作成します。 -
Platform
-
(オプション) このマニフェストが適用されるプラットフォームを定義するオブジェクト。すべてのプラットフォームに適用されるマニフェストを定義する場合は、このパラメータを省略します。
このオブジェクトは、コアデバイスが動作するプラットフォームに関するキーと値のペアを指定します。このコンポーネントをデプロイすると、AWS IoT Greengrass Core ソフトウェアは、これらのキーと値のペアをコアデバイス上のプラットフォーム属性と比較します。AWS IoT Greengrass Core ソフトウェアが常に
os
とarchitecture
を定義し、追加の属性を定義する場合もあります。Greengrass nucleus コンポーネントをデプロイするときに、コアデバイスのカスタムプラットフォーム属性を指定することができます。詳細については、「Greengrass nucleus コンポーネント」の「プラットフォームの上書きパラメータ」を参照してください。キーと値のペアごとに、次のいずれかの値を指定できます。
-
linux
またはwindows
などの正確な値。正確な値は、数字または文字で始まっている必要があります。 -
*
: これはすべての値と一致します。値が存在しない場合でも一致します。 -
/windows|linux/
などの Java スタイルの正規表現。正規表現は、スラッシュ文字 (/
) で開始し終了する必要があります。たとえば、正規表現/.+/
は空白以外のすべての値と一致します。
このオブジェクトには、次の情報が含まれます。
os
-
(オプション) このマニフェストがサポートするプラットフォームのオペレーティングシステムの名前。一般的なプラットフォームには次の値が含まれます。
-
linux
-
windows
-
darwin
(macOS)
-
architecture
-
(オプション) このマニフェストがサポートするプラットフォームのプロセッサアーキテクチャ。一般的なアーキテクチャには次の値が含まれます。
-
amd64
-
arm
-
aarch64
-
x86
-
architecture.detail
-
(オプション) このマニフェストがサポートするプラットフォームのプロセッサアーキテクチャの詳細。一般的なアーキテクチャの詳細には次の値が含まれます。
-
arm61
-
arm71
-
arm81
-
key
-
(オプション) このマニフェストに対して定義するプラットフォーム属性。
key
をプラットフォーム属性の名前に置き換えます。AWS IoT Greengrass Core ソフトウェアは、このプラットフォーム属性を Greengrass nucleus コンポーネント設定で指定したキーと値のペアと照合します。詳細については、「Greengrass nucleus コンポーネント」の「プラットフォームの上書きパラメータ」を参照してください。ヒント
逆ドメイン名の形式にすれば、社内での名前のコリジョンを回避することができます。例えば、会社が
example.com
を所有していて、ラジオプロジェクトで作業している場合には、カスタムプラットフォーム属性にcom.example.radio.RadioModule
という名前を付けることができます。こうすることで、会社内のプラットフォーム属性名のコリジョンを回避できます。たとえば、
com.example.radio.RadioModule
というプラットフォーム属性を定義して、コアデバイスで利用可能な無線モジュールに基づいて、異なるマニフェストを指定することができます。各マニフェストには、異なるハードウェア設定に適用する異なるアーティファクトを含めることができるため、コアデバイスにデプロイするソフトウェアセットを最小限に抑えることができます。
-
-
Lifecycle
-
このマニフェストが定義するプラットフォームに、コンポーネントをインストールして実行する方法を定義するオブジェクトまたは文字列。すべてのプラットフォームに適用されるグローバルライフサイクルを定義することもできます。コアデバイスは、使用するマニフェストでライフサイクルが指定されていない場合にのみ、グローバルライフサイクルを使用します。
注記
このライフサイクルはマニフェスト内で定義します。ここで指定するライフサイクルステップは、このマニフェストが定義するプラットフォームにのみ適用されます。すべてのプラットフォームに適用されるグローバルライフサイクルを定義することもできます。
このオブジェクトまたは文字列には、次の情報が含まれます。
-
Setenv
-
(オプション) すべてのライフサイクルスクリプトに提供する、環境変数のディクショナリ。これらの環境変数は、各ライフサイクルスクリプトの
Setenv
で上書きすることができます。 -
install
-
(オプション) コンポーネントのインストール時に実行するスクリプトを定義するオブジェクトまたは文字列。AWS IoT Greengrass Core ソフトウェアは、ソフトウェアが起動するたびに、このライフサイクルステップを実行します。
install
スクリプトが成功コードで終了すると、コンポーネントはINSTALLED
状態に入ります。このオブジェクトまたは文字列には、次の情報が含まれます。
Script
-
実行するスクリプト。
RequiresPrivilege
-
(オプション) ルート権限でスクリプトを実行できます。このオプションを
true
に設定すると、AWS IoT Greengrass Core ソフトウェアは、このコンポーネントを実行するように設定したシステムユーザーとしてではなく、root としてこのライフサイクルスクリプトを実行します。デフォルトはfalse
です。 Skipif
-
(オプション) スクリプトを実行するかどうかを決定するためのチェック。実行可能ファイルがパス上にあるかどうか、あるいはファイルが存在するかどうかを確認するように定義できます。出力が True の場合、AWS IoT Greengrass Core ソフトウェアはこのステップをスキップします。次のいずれかの値を選択します。
-
onpath
- システムパス上に runnable があるかどうかをチェックします。例えば、Python 3 が利用可能な場合には、runnable
onpath python3
を使用してこのライフサイクルステップをスキップします。 -
exists
- ファイルが存在するかどうかをチェックします。たとえば、file
/tmp/my-configuration.db
が存在する場合には、exists /tmp/my-configuration.db
を使用してこのライフサイクルステップをスキップします。
-
Timeout
-
(オプション) AWS IoT Greengrass Core ソフトウェアがプロセスを終了する前に、スクリプトが実行できる最大時間 (秒単位)。
デフォルト: 120 秒
Setenv
-
(オプション) スクリプトに提供する環境変数のディクショナリ。これらの環境変数は、
Lifecycle.Setenv
で指定した変数を上書きします。
-
run
-
(オプション) コンポーネントの開始時に実行するスクリプトを定義するオブジェクトまたは文字列。
このライフサイクルステップが実行されると、コンポーネントは
RUNNING
状態に入ります。run
スクリプトが成功コードで終了すると、コンポーネントはSTOPPING
状態に入ります。shutdown
スクリプトが指定されている場合は、スクリプトが実行され、指定されていない場合、コンポーネントはFINISHED
状態になります。このコンポーネントに依存するコンポーネントは、このライフサイクルステップが実行されたときに開始されます。依存コンポーネントが使用するサービスなどのバックグラウンドプロセスを実行するには、代わりに
startup
ライフサイクルステップを使用します。run
ライフサイクルによりコンポーネントをデプロイすると、そのライフサイクルスクリプトが実行された直後から、デプロイが完了したコアデバイスを報告できるようになります。その結果、run
ライフサイクルスクリプトが実行後すぐに失敗した場合でも、そのデプロイを正常に完了することができます。デプロイステータスを、コンポーネントの開始スクリプトの結果に依存させたい場合は、代わりにstartup
ライフサイクルステップを使用します。注記
1 つの
startup
またはrun
ライフサイクルのみを定義できます。このオブジェクトまたは文字列には、次の情報が含まれます。
Script
-
実行するスクリプト。
RequiresPrivilege
-
(オプション) ルート権限でスクリプトを実行できます。このオプションを
true
に設定すると、AWS IoT Greengrass Core ソフトウェアは、このコンポーネントを実行するように設定したシステムユーザーとしてではなく、root としてこのライフサイクルスクリプトを実行します。デフォルトはfalse
です。 Skipif
-
(オプション) スクリプトを実行するかどうかを決定するためのチェック。実行可能ファイルがパス上にあるかどうか、あるいはファイルが存在するかどうかを確認するように定義できます。出力が True の場合、AWS IoT Greengrass Core ソフトウェアはこのステップをスキップします。次のいずれかの値を選択します。
-
onpath
- システムパス上に runnable があるかどうかをチェックします。例えば、Python 3 が利用可能な場合には、runnable
onpath python3
を使用してこのライフサイクルステップをスキップします。 -
exists
- ファイルが存在するかどうかをチェックします。たとえば、file
/tmp/my-configuration.db
が存在する場合には、exists /tmp/my-configuration.db
を使用してこのライフサイクルステップをスキップします。
-
Timeout
-
(オプション) AWS IoT Greengrass Core ソフトウェアがプロセスを終了する前に、スクリプトが実行できる最大時間 (秒単位)。
デフォルトでは、このライフサイクルステップはタイムアウトしません。このタイムアウトを省略すると、
run
スクリプトが終了するまで実行されます。 Setenv
-
(オプション) スクリプトに提供する環境変数のディクショナリ。これらの環境変数は、
Lifecycle.Setenv
で指定した変数を上書きします。
-
startup
-
(オプション) コンポーネントの開始時に実行するバックグラウンドプロセスを定義するオブジェクトまたは文字列。
依存関係のあるコンポーネントを起動する前に、正常に終了させる、あるいはコンポーネントのステータスを
RUNNING
に更新するコマンドを実行するには、startup
を使用します。UpdateState IPC オペレーションを使用して、コンポーネントが終了しないスクリプトを開始するERRORED
ときに、コンポーネントのステータスをRUNNING
または に設定します。例えば、/etc/init.d/mysqld start
で MySQL プロセスを開始するstartup
ステップを定義することができます。このライフサイクルステップが実行されると、コンポーネントは
STARTING
状態に入ります。startup
スクリプトが成功コードで終了すると、コンポーネントはRUNNING
状態に入ります。その後、依存コンポーネントを開始することができます。startup
ライフサイクルによりコンポーネントをデプロイすると、そのライフサイクルスクリプトが終了したか、もしくは状態を報告した後に、コアデバイスがデプロイの完了を報告できるようになります。言い換えると、すべてのコンポーネントの起動スクリプトが終了したか、あるいは状態を報告するまで、デプロイのステータスはIN_PROGRESS
のままです注記
1 つの
startup
またはrun
ライフサイクルのみを定義できます。このオブジェクトまたは文字列には、次の情報が含まれます。
Script
-
実行するスクリプト。
RequiresPrivilege
-
(オプション) ルート権限でスクリプトを実行できます。このオプションを
true
に設定すると、AWS IoT Greengrass Core ソフトウェアは、このコンポーネントを実行するように設定したシステムユーザーとしてではなく、root としてこのライフサイクルスクリプトを実行します。デフォルトはfalse
です。 Skipif
-
(オプション) スクリプトを実行するかどうかを決定するためのチェック。実行可能ファイルがパス上にあるかどうか、あるいはファイルが存在するかどうかを確認するように定義できます。出力が True の場合、AWS IoT Greengrass Core ソフトウェアはこのステップをスキップします。次のいずれかの値を選択します。
-
onpath
- システムパス上に runnable があるかどうかをチェックします。例えば、Python 3 が利用可能な場合には、runnable
onpath python3
を使用してこのライフサイクルステップをスキップします。 -
exists
- ファイルが存在するかどうかをチェックします。たとえば、file
/tmp/my-configuration.db
が存在する場合には、exists /tmp/my-configuration.db
を使用してこのライフサイクルステップをスキップします。
-
Timeout
-
(オプション) AWS IoT Greengrass Core ソフトウェアがプロセスを終了する前に、スクリプトが実行できる最大時間 (秒単位)。
デフォルト: 120 秒
Setenv
-
(オプション) スクリプトに提供する環境変数のディクショナリ。これらの環境変数は、
Lifecycle.Setenv
で指定した変数を上書きします。
-
shutdown
-
(オプション) コンポーネントのシャットダウン時に実行するスクリプトを定義するオブジェクトまたは文字列。シャットダウンライフサイクルを使用して、コンポーネントが
STOPPING
状態にあるときに実行するコードを実行します。シャットダウンライフサイクルは、startup
またはrun
スクリプトによって開始されたプロセスを停止するために使用できます。startup
でバックグラウンドプロセスを開始した場合は、コンポーネントがシャットダウンするときにはshutdown
ステップを使用してそのプロセスを停止します。例えば、/etc/init.d/mysqld stop
で MySQL プロセスを停止するshutdown
ステップを定義することができます。shutdown
スクリプトは、コンポーネントがSTOPPING
状態になった後に実行されます。スクリプトが正常に完了すると、コンポーネントはFINISHED
状態になります。このオブジェクトまたは文字列には、次の情報が含まれます。
Script
-
実行するスクリプト。
RequiresPrivilege
-
(オプション) ルート権限でスクリプトを実行できます。このオプションを
true
に設定すると、AWS IoT Greengrass Core ソフトウェアは、このコンポーネントを実行するように設定したシステムユーザーとしてではなく、root としてこのライフサイクルスクリプトを実行します。デフォルトはfalse
です。 Skipif
-
(オプション) スクリプトを実行するかどうかを決定するためのチェック。実行可能ファイルがパス上にあるかどうか、あるいはファイルが存在するかどうかを確認するように定義できます。出力が True の場合、AWS IoT Greengrass Core ソフトウェアはこのステップをスキップします。次のいずれかの値を選択します。
-
onpath
- システムパス上に runnable があるかどうかをチェックします。例えば、Python 3 が利用可能な場合には、runnable
onpath python3
を使用してこのライフサイクルステップをスキップします。 -
exists
- ファイルが存在するかどうかをチェックします。たとえば、file
/tmp/my-configuration.db
が存在する場合には、exists /tmp/my-configuration.db
を使用してこのライフサイクルステップをスキップします。
-
Timeout
-
(オプション) AWS IoT Greengrass Core ソフトウェアがプロセスを終了する前に、スクリプトが実行できる最大時間 (秒単位)。
デフォルト: 15 秒。
Setenv
-
(オプション) スクリプトに提供する環境変数のディクショナリ。これらの環境変数は、
Lifecycle.Setenv
で指定した変数を上書きします。
-
recover
-
(オプション) コンポーネントにエラーが発生したときに実行するスクリプトを定義するオブジェクトまたは文字列。
この手順は、コンポーネントが
ERRORED
状態になったときに実行されます。コンポーネントが正常に回復しないで 3 回ERRORED
になると、コンポーネントはBROKEN
状態に変わります。BROKEN
コンポーネントを修復するには、もう一度デプロイする必要があります。このオブジェクトまたは文字列には、次の情報が含まれます。
Script
-
実行するスクリプト。
RequiresPrivilege
-
(オプション) ルート権限でスクリプトを実行できます。このオプションを
true
に設定すると、AWS IoT Greengrass Core ソフトウェアは、このコンポーネントを実行するように設定したシステムユーザーとしてではなく、root としてこのライフサイクルスクリプトを実行します。デフォルトはfalse
です。 Skipif
-
(オプション) スクリプトを実行するかどうかを決定するためのチェック。実行可能ファイルがパス上にあるかどうか、あるいはファイルが存在するかどうかを確認するように定義できます。出力が True の場合、AWS IoT Greengrass Core ソフトウェアはこのステップをスキップします。次のいずれかの値を選択します。
-
onpath
- システムパス上に runnable があるかどうかをチェックします。例えば、Python 3 が利用可能な場合には、runnable
onpath python3
を使用してこのライフサイクルステップをスキップします。 -
exists
- ファイルが存在するかどうかをチェックします。たとえば、file
/tmp/my-configuration.db
が存在する場合には、exists /tmp/my-configuration.db
を使用してこのライフサイクルステップをスキップします。
-
Timeout
-
(オプション) AWS IoT Greengrass Core ソフトウェアがプロセスを終了する前に、スクリプトが実行できる最大時間 (秒単位)。
デフォルト: 60 秒
Setenv
-
(オプション) スクリプトに提供する環境変数のディクショナリ。これらの環境変数は、
Lifecycle.Setenv
で指定した変数を上書きします。
-
bootstrap
-
(オプション) AWS IoT Greengrass Core ソフトウェアまたはコアデバイスの再起動が必要となるスクリプトを定義するオブジェクトまたは文字列。これにより、オペレーティングシステムの更新やランタイムの更新などをインストールした後に再起動するコンポーネントを開発することができます。
注記
AWS IoT Greengrass Core ソフトウェアまたはデバイスを再起動する必要のない更新や依存関係をインストールする場合は、インストールライフサイクルを使用します。
このライフサイクルステップは、AWS IoT Greengrass Core ソフトウェアがコンポーネントをデプロイするときに、以下のケースの場合にインストールライフサイクルステップの前に実行されます。
-
コンポーネントがコアデバイスに初めてデプロイされる場合。
-
コンポーネントのバージョンが変更される場合。
-
コンポーネント設定が更新されたことで、ブートストラップスクリプトが変更される場合。
AWS IoT Greengrass Core ソフトウェアが、デプロイにブートストラップステップが含まれるすべてのコンポーネントのブートストラップステップを完了すると、ソフトウェアは再起動します。
重要
AWS IoT Greengrass Core ソフトウェアまたはコアデバイスを再起動するには、AWS IoT Greengrass Core ソフトウェアをシステムサービスとして設定する必要があります。AWS IoT Greengrass Core ソフトウェアをシステムサービスとして設定しなかった場合、ソフトウェアは再起動しません。詳細については、「Greengrass nucleus をシステムサービスとして設定する」を参照してください。
このオブジェクトまたは文字列には、次の情報が含まれます。
BootstrapOnRollback
-
注記
この機能を有効にする
BootstrapOnRollback
と、 は、失敗したターゲットデプロイの一部としてブートストラップライフサイクルステップを完了または実行しようとしたコンポーネントに対してのみ実行されます。この機能は、Greengrass nucleus バージョン 2.12.0 以降で使用できます。(オプション) ロールバックデプロイの一部として、ブートストラップライフサイクルステップを実行できます。このオプションを に設定すると
true
、ロールバックデプロイ内で定義されたブートストラップライフサイクルステップが実行されます。デプロイが失敗すると、ロールバックデプロイ中に以前のバージョンのコンポーネントブートストラップライフサイクルが再度実行されます。デフォルトは
false
です。 Script
-
実行するスクリプト。このスクリプトの終了コードは、再起動の指示を定義しています。次の終了コードを使用します。
-
0
- AWS IoT Greengrass Core ソフトウェアまたはコアデバイスを再起動します。AWS IoT Greengrass Core ソフトウェアは、すべてのコンポーネントのブートストラップ後に再起動します。 -
100
- AWS IoT Greengrass Core ソフトウェアの再起動をリクエストします。 -
101
- コアデバイスの再起動をリクエストします。
終了コード 100~199 は特別動作向けに予約済みです。その他の終了コードは、スクリプトエラーを表します。
-
RequiresPrivilege
-
(オプション) ルート権限でスクリプトを実行できます。このオプションを
true
に設定すると、AWS IoT Greengrass Core ソフトウェアは、このコンポーネントを実行するように設定したシステムユーザーとしてではなく、root としてこのライフサイクルスクリプトを実行します。デフォルトはfalse
です。 Timeout
-
(オプション) AWS IoT Greengrass Core ソフトウェアがプロセスを終了する前に、スクリプトが実行できる最大時間 (秒単位)。
デフォルト: 120 秒
Setenv
-
(オプション) スクリプトに提供する環境変数のディクショナリ。これらの環境変数は、
Lifecycle.Setenv
で指定した変数を上書きします。
-
-
-
Selections
-
(オプション) このマニフェストに対して実行するグローバルライフサイクルのセクションを指定する選択キーのリスト。グローバルライフサイクルでは、任意のレベルで選択キーを使用してライフサイクルステップを定義し、ライフサイクルのサブセクションを選択することができます その後、コアデバイスは、このマニフェストの選択キーと一致するセクションを使用します。詳細については、「グローバルライフサイクルの例」を参照してください。
重要
コアデバイスは、このマニフェストがライフサイクルを指定していない場合にのみ、グローバルライフサイクルを使用します。
all
選択キーを指定して、選択キーを持たないグローバルライフサイクルのセクションを実行することができます。 -
Artifacts
-
(オプション) このマニフェストが定義するプラットフォーム上のコンポーネントのバイナリアーティファクトを定義するオブジェクトのリスト。例えば、コードまたはイメージをアーティファクトとして定義できます。
コンポーネントがデプロイされると、AWS IoT Greengrass Core ソフトウェアはコアデバイス上のフォルダにアーティファクトをダウンロードします。アーティファクトは、ソフトウェアがダウンロードした後に抽出するアーカイブファイルとして定義することもできます。
レシピ変数を使用すれば、コアデバイス上のアーティファクトがインストールされているフォルダへのパスを取得することができます。
-
通常のファイル - artifacts:path レシピ変数を使用して、アーティファクトが含まれるフォルダへのパスを取得します。例えば、レシピで
{artifacts:path}/my_script.py
を指定すれば、URIs3://
を持つアーティファクトへのパスを取得できます。DOC-EXAMPLE-BUCKET
/path/to/my_script.py -
抽出されたアーカイブ - artifacts:decompressedPath レシピ変数を使用して、抽出されたアーカイブアーティファクトが含まれるフォルダへのパスを取得します。AWS IoT Greengrass Core ソフトウェアは、各アーカイブをアーカイブと同じ名前のフォルダに抽出します。例えば、レシピで
{artifacts:decompressedPath}/my_archive/my_script.py
を指定すれば、URIs3://
を持つアーカイブアーティファクト内にあるDOC-EXAMPLE-BUCKET
/path/to/my_archive.zipmy_script.py
へのパスを取得できます。
注記
ローカルコアデバイス上でアーカイブアーティファクトを持つコンポーネントを開発する場合、そのアーティファクトの URI がない可能性があります。アーティファクトを抽出する
Unarchive
オプションを使用してコンポーネントをテストするには、ファイル名がアーカイブアーティファクトファイルの名前と一致する URI を指定します。アーカイブアーティファクトのアップロード先となる予定の URI を指定することも、新しいプレースホルダ URI を指定することもできます。例えば、ローカルデプロイ時にmy_archive.zip
アーティファクトを抽出する場合には、s3://
を指定できます。DOC-EXAMPLE-BUCKET
/my_archive.zip各オブジェクトには、次の情報が含まれます:
URI
-
S3 バケット内のアーティファクトの URI。AWS IoT Greengrass Core ソフトウェアは、コンポーネントのインストール時にこの URI からアーティファクトをフェッチしますが、アーティファクトがデバイスにすでに存在する場合はフェッチしません。各アーティファクトには、各マニフェスト内に一意のファイル名がある必要があります。
Unarchive
-
(オプション) 解凍するアーカイブのタイプ。次のオプションから選択します。
-
NONE
- ファイルは解凍するアーカイブではありません。AWS IoT Greengrass Core ソフトウェアによって、コアデバイス上のフォルダにアーティファクトがインストールされます。artifacts:path レシピ変数を使用して、このフォルダへのパスを取得することができます。 -
ZIP
- ファイルは ZIP アーカイブです。AWS IoT Greengrass Core ソフトウェアは、アーカイブをアーカイブと同じ名前のフォルダに抽出します。artifacts:decompressedPath レシピ変数を使用して、このフォルダが含まれるフォルダへのパスを取得することができます。
デフォルトは
NONE
です。 -
-
Permission
-
(オプション) このアーティファクトファイルに設定するアクセス許可を定義するオブジェクト。読み取り許可と実行許可を設定できます。
注記
書き込み許可は設定できません。これは、AWS IoT Greengrass Core ソフトウェアが、アーティファクトフォルダ内のアーティファクトファイルをコンポーネントが編集することを許可していないからです。コンポーネント内のアーティファクトファイルを編集するには、別の場所にコピーするか、新しいアーティファクトファイルをパブリッシュしてデプロイします。
アーチファクトを解凍するアーカイブとして定義すると、AWS IoT Greengrass Core ソフトウェアは、アーカイブから解凍するファイルに対してこれらのアクセス許可を設定します。AWS IoT Greengrass Core ソフトウェアは、フォルダのアクセス権限を
Read
およびExecute
に対してALL
に設定します。これにより、コンポーネントはフォルダ内の解凍されたファイルを表示できるようになります。アーカイブからの個々のファイルにアクセス許可を設定する場合は、インストールライフサイクルスクリプトでアクセス許可を設定することができます。このオブジェクトには、次の情報が含まれます。
Read
-
(オプション) このアーティファクトファイルに設定する読み取りアクセス許可。このコンポーネントに依存するコンポーネントなどの他のコンポーネントがこのアーティファクトにアクセスできるようにするには、
ALL
を指定します。次のオプションから選択します。-
NONE
- ファイルは読み取れません。 -
OWNER
- このコンポーネントを実行するように設定したシステムユーザーがファイルを読み取ることができます。 -
ALL
- このファイルはすべてのユーザーが読み取ることができます。
デフォルトは
OWNER
です。 -
Execute
-
(オプション) このアーティファクトファイルに設定する実行アクセス許可。
Execute
アクセス許可は、Read
アクセス許可を意味します。例えば、Execute
に対してALL
を指定すると、すべてのユーザーがこのアーティファクトファイルを読み取り、実行できるようになります。次のオプションから選択します。
-
NONE
- ファイルは実行できません。 -
OWNER
- このコンポーネントを実行するように設定したシステムユーザーがファイルを実行することができます。 -
ALL
- このファイルはすべてのユーザーが実行することができます。
デフォルトは
NONE
です。 -
Digest
-
(読み取り専用) アーティファクトの暗号化ダイジェストハッシュ。コンポーネントを作成するときには、AWS IoT Greengrass はハッシュアルゴリズムを使用して、アーティファクトファイルのハッシュを計算します。その後、コンポーネントをデプロイするときに、Greengrass nucleus がダウンロードされたアーティファクトのハッシュを計算し、このダイジェストとハッシュを比較することでインストール前にアーティファクトを検証します。ハッシュがダイジェストと一致しない場合、デプロイは失敗します。
このパラメータを設定すると、AWS IoT Greengrass はコンポーネントの作成時に設定した値を置き換えます。
Algorithm
-
(読み取り専用) アーティファクトのダイジェストハッシュを計算するために AWS IoT Greengrass が使用するハッシュアルゴリズム。
このパラメータを設定すると、AWS IoT Greengrass はコンポーネントの作成時に設定した値を置き換えます。
-
-
Lifecycle
-
コンポーネントをインストールして実行する方法を定義するオブジェクト。コアデバイスは、使用するマニフェストでライフサイクルが指定されていない場合にのみ、グローバルライフサイクルを使用します。
注記
このライフサイクルはマニフェスト外で定義します。マニフェストと一致するプラットフォームに適用されるマニフェストのライフサイクルを定義することもできます。
グローバルライフサイクルでは、各マニフェストで指定した特定の選択キーに対して実行するライフサイクルを指定することができます。選択キーは、各マニフェストに対して実行するグローバルライフサイクルのセクションを識別する文字列です。
選択キーがないセクションのデフォルトは、
all
選択キーです。つまり、マニフェストでall
選択キーを指定することで、選択キーがないグローバルライフサイクルのセクションを実行することができることになります。グローバルライフサイクルでall
選択キーを指定する必要はありませんマニフェストでライフサイクルまたは選択キーが定義されていない場合、コアデバイスはデフォルトで
all
選択を使用します。つまりこの場合、コアデバイスは、選択キーを使用しないグローバルライフサイクルのセクションを使用することになります。このオブジェクトには、マニフェストのライフサイクルと同じ情報が含まれていますが、任意のレベルで選択キーを指定することで、ライフサイクルのサブセクションを選択することができます。
ヒント
選択キーとライフサイクルキーが競合することがないように、各選択キーには小文字のみを使用することを推奨します。ライフサイクルキーは大文字で始まります。
例 トップレベルの選択キーを使用したグローバルライフサイクルの例
Lifecycle: key1: install: Skipif: either onpath
executable
or existsfile
Script: command1 key2: install: Script: command2 all: install: Script: command3例 末尾レベルの選択キーを使用したグローバルライフサイクルの例
Lifecycle: install: Script: key1: command1 key2: command2 all: command3
例 複数のレベルの選択キーを使用したグローバルライフサイクルの例
Lifecycle: key1: install: Skipif: either onpath
executable
or existsfile
Script: command1 key2: install: Script: command2 all: install: Script: key3: command3 key4: command4 all: command5
レシピ変数
レシピ変数は、現在のコンポーネントと nucleus の情報を公開し、レシピで使用できるようにします。例えば、レシピ変数を使用して、ライフサイクルスクリプトで実行するアプリケーションにコンポーネント設定パラメータを渡すことができます。
レシピ変数は、以下のコンポーネントレシピの各セクションで使用できます。
-
ライフサイクル定義。
-
Greengrass nucleus v2.6.0 以降を使用し、 設定オプションを に設定した場合のコンポーネントinterpolateComponentConfiguration設定定義
true
。レシピ変数は、コンポーネント設定の更新をデプロイする際にも、使用することが可能です。
レシピ変数は {recipe_variable}
構文を使用します。中括弧はレシピ変数を示しています。
AWS IoT Greengrass は次のレシピ変数をサポートしています。
component_dependency_name
:configuration:json_pointer
-
このレシピが定義するコンポーネント、またはこのコンポーネントが依存するコンポーネントの設定パラメータの値。
この変数を使用して、コンポーネントのライフサイクルで実行するスクリプトにパラメータを提供することができます。
注記
AWS IoT Greengrass は、コンポーネントのライフサイクル定義でのみ、このレシピ変数をサポートします。
このレシピ変数には、次の入力があります。
-
component_dependency_name
- (オプション) クエリを実行するコンポーネント依存関係の名前。このレシピが定義するコンポーネントを照会する場合は、このセグメントを省略します。直接的な依存関係のみを指定できます。 -
json_pointer
- 評価する設定値への JSON ポインタ。JSON ポインタはフォワードスラッシュ (/
) で始まります。ネストされたコンポーネント設定の値を識別するには、フォワードスラッシュ (/
) を使用して、設定の各レベルのキーを区切ります。数字をキーとして使用して、リスト内のインデックスを指定できます。詳細については、「JSON ポインタの仕様」を参照してください。 AWS IoT Greengrass Core は YAML 形式のレシピに JSON ポインタを使用します。
JSON ポインタは次のノードタイプを参照できます。
-
値ノード。AWS IoT GreengrassCore は、レシピ変数を値の文字列表現に置き換えます。Null 値は文字列の
null
に置き換えられます。 -
オブジェクトノード。AWS IoT GreengrassCore は、レシピ変数をそのオブジェクトのシリアル化された JSON 文字列表現に置き換えます。
-
ノードなし。AWS IoT GreengrassCore はレシピ変数を置き換えません。
例えば、
{configuration:/Message}
レシピ変数は、コンポーネント設定のMessage
キーの値を取得します。{com.example.MyComponentDependency:configuration:/server/port}
レシピ変数は、コンポーネント依存関係のserver
設定オブジェクトにあるport
の値を取得します。 -
-
component_dependency_name
:artifacts:path -
このレシピが定義するコンポーネント、またはこのコンポーネントが依存するコンポーネントのアーティファクトのルートパス。
コンポーネントがインストールされると、AWS IoT Greengrass はコンポーネントのアーティファクトを、この変数が公開するフォルダにコピーします。この変数を使用して、コンポーネントのライフサイクルで実行するスクリプトの場所などを特定できます。
このパスのフォルダは読み取り専用です。アーティファクトファイルを変更するには、ファイルを現在の作業ディレクトリなどの別の場所にコピーします (
$PWD
または.
)。その後、その場所でファイルを変更します。コンポーネントの依存関係からアーティファクトを読み取るか実行するには、そのアーティファクトの
Read
またはExecute
のアクセス許可がALL
である必要があります。詳細については、コンポーネントレシピで定義した「アーティファクトアクセス許可」を参照してください。このレシピ変数には、次の入力があります。
-
component_dependency_name
- (オプション) クエリを実行するコンポーネント依存関係の名前。このレシピが定義するコンポーネントを照会する場合は、このセグメントを省略します。直接的な依存関係のみを指定できます。
-
-
component_dependency_name
:artifacts:decompressedPath -
このレシピが定義するコンポーネント、またはこのコンポーネントが依存するコンポーネントの解凍されたアーカイブアーティファクトのルートパス。
コンポーネントがインストールされると、AWS IoT Greengrass はコンポーネントのアーカイブアーティファクトを、この変数が公開するフォルダにコピーします。この変数を使用して、コンポーネントのライフサイクルで実行するスクリプトの場所などを特定できます。
各アーティファクトは、解凍されたパス内のフォルダに解凍されます。フォルダの名前はアーティファクトと同じ名前から拡張子を引いたものになります。例えば、
models.zip
という名前の ZIP アーティファクトは、{artifacts:decompressedPath}/models
フォルダに解凍されます。このパスのフォルダは読み取り専用です。アーティファクトファイルを変更するには、ファイルを現在の作業ディレクトリなどの別の場所にコピーします (
$PWD
または.
)。その後、その場所でファイルを変更します。コンポーネントの依存関係からアーティファクトを読み取るか実行するには、そのアーティファクトの
Read
またはExecute
のアクセス許可がALL
である必要があります。詳細については、コンポーネントレシピで定義した「アーティファクトアクセス許可」を参照してください。このレシピ変数には、次の入力があります。
-
component_dependency_name
- (オプション) クエリを実行するコンポーネント依存関係の名前。このレシピが定義するコンポーネントを照会する場合は、このセグメントを省略します。直接的な依存関係のみを指定できます。
-
-
component_dependency_name
:work:path -
この機能は、Greengrass nucleus コンポーネントの v2.0.4 以降に利用できます。
このレシピが定義するコンポーネント、またはこのコンポーネントが依存するコンポーネントのワークパス。このレシピ変数の値は、コンポーネントのコンテキストから実行されたときの
$PWD
環境変数と pwdコマンドの出力と同じです。 このレシピ変数を使用して、コンポーネントと依存関係間でファイルを共有できます。
このパスのフォルダは、このレシピが定義するコンポーネントと、同じユーザーおよびグループとして実行される他のコンポーネントが、読み取り書き込むことができます。
このレシピ変数には、次の入力があります。
-
component_dependency_name
- (オプション) クエリを実行するコンポーネント依存関係の名前。このレシピが定義するコンポーネントを照会する場合は、このセグメントを省略します。直接的な依存関係のみを指定できます。
-
kernel:rootPath
-
AWS IoT Greengrass Core のルートパス。
iot:thingName
-
この機能は、Greengrass nucleus コンポーネントの v2.3.0 以降に利用できます。
コアデバイスの AWS IoT モノの名前。
レシピの例
コンポーネントのレシピを作成する際には、次のレシピ例を参照してください。
AWS IoT Greengrass は Greengrass ソフトウェアカタログと呼ばれる Greengrass コンポーネントのインデックスをキュレーションします。このカタログは、Greengrass コミュニティによって開発された Greengrass コンポーネントを追跡します。このカタログから、コンポーネントをダウンロード、変更、デプロイして Greengrass アプリケーションを作成できます。詳細については、「コミュニティコンポーネント」を参照してください。
Hello World コンポーネントレシピ
次のレシピは、Python スクリプトを実行する Hello World コンポーネントについて説明しています。このコンポーネントはすべてのプラットフォームをサポートしており、AWS IoT Greengrass が Python スクリプトに引数としてわたす Message
パラメータを受け入れます。これは、入門チュートリアルの Hello World コンポーネントのためのレシピです。
Python ランタイムコンポーネントの例
次のレシピは、Python をインストールするコンポーネントについて説明しています。このコンポーネントは 64 ビット Linux デバイスをサポートします。
複数のフィールドを指定するコンポーネントレシピ
次のコンポーネントレシピでは、複数のレシピフィールドを使用します。