AWS IoT Greengrass コンポーネントレシピのリファレンス - AWS IoT Greengrass

AWS IoT Greengrass コンポーネントレシピのリファレンス

コンポーネントレシピは、コンポーネントの詳細、依存関係、アーティファクト、およびライフサイクルを定義するファイルです。コンポーネントのライフサイクルでは、コンポーネントのインストール、実行、シャットダウンなどのために実行するコマンドを指定します。AWS IoT Greengrass コアは、レシピで定義したライフサイクルを使用して、コンポーネントをインストールして実行します。AWS IoT Greengrass サービスは、コンポーネントをデプロイするときに、コアデバイスにデプロイする依存関係とアーティファクトを特定するためにレシピを使用します。

レシピでは、コンポーネントがサポートしているプラットフォームごとに、固有の依存関係とライフサイクルを定義できます。この機能を使用すれば、要件が異なる複数のプラットフォームを持つデバイスにコンポーネントをデプロイすることができます。また、この機能を使用することで、AWS IoT Greengrass がサポートしていないデバイスにコンポーネントをインストールしないようにすることもできます。

各レシピには、マニフェストのリストが含まれます。各マニフェストは、プラットフォームがそれらの要件を満たすコアデバイスに使用する一連のプラットフォーム要件、ライフサイクル、そしてアーティファクトを指定します。コアデバイスは、デバイスが満たすプラットフォーム要件が含まれる最初のマニフェストを使用します。プラットフォーム要件のないマニフェストを指定すれば、すべてのコアデバイスと一致します。

マニフェストにないグローバルライフサイクルを指定することもできます。グローバルライフサイクルでは、ライフサイクルのサブセクションを識別する選択キーを使用することができます。その後、マニフェスト内でこれらの選択キーを指定することで、マニフェストのライフサイクルに加えて、グローバルライフサイクルのこれらのセクションも使用することができます。コアデバイスは、マニフェストがライフサイクルを定義していない場合にのみ、マニフェストの選択キーを使用します。マニフェストの all 選択を使用すると、選択キーのないグローバルライフサイクルのセクションに一致させることができます。

AWS IoT Greengrass Core ソフトウェアは、コアデバイスと一致するマニフェストを選択した後、使用するライフサイクルステップを識別するために以下を実行します。

  • 選択したマニフェストがライフサイクルを定義している場合、コアデバイスはそのライフサイクルを使用します。

  • 選択したマニフェストがライフサイクルを定義していない場合、コアデバイスはグローバルサイクルを使用します。コアデバイスは、グローバルライフサイクルのどのセクションを使用するかを特定するために以下を実行します。

    • マニフェストが選択キーを定義している場合、コアデバイスはマニフェストの選択キーが含まれるグローバルライフサイクルのセクションを使用します。

    • マニフェストが選択キーを定義していない場合、コアデバイスはマニフェストの選択キーが含まれないグローバルライフサイクルのセクションを使用します。この動作は、all 選択を定義するマニフェストと同じです。

重要

コアデバイスは、コンポーネントをインストールするにあたり、マニフェストのプラットフォーム要件を少なくとも 1 つ満たす必要があります。コアデバイスに一致するマニフェストがない場合、AWS IoT Greengrass Core ソフトウェアはコンポーネントをインストールせず、デプロイは失敗します。

レシピは JSON または YAML 形式で定義できます。レシピの例セクションには、各形式のレシピが含まれています。

レシピの形式

コンポーネントのレシピを定義するときには、レシピドキュメントで次の情報を指定します。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

コンポーネントのバージョン。

注記

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 はプラットフォームの osarchitecture からわかりやすい名前を作成します。

Platform

(オプション) このマニフェストが適用されるプラットフォームを定義するオブジェクト。すべてのプラットフォームに適用されるマニフェストを定義する場合は、このパラメータを省略します。

このオブジェクトは、コアデバイスが動作するプラットフォームに関するキーと値のペアを指定します。このコンポーネントをデプロイすると、AWS IoT Greengrass Core ソフトウェアは、これらのキーと値のペアをコアデバイス上のプラットフォーム属性と比較します。AWS IoT Greengrass Core ソフトウェアが常に osarchitecture を定義し、追加の属性を定義する場合もあります。Greengrass nucleus コンポーネントをデプロイするときに、コアデバイスのカスタムプラットフォーム属性を指定することができます。詳細については、「Greengrass nucleus コンポーネント」の「プラットフォームの上書きパラメータ」を参照してください。

キーと値のペアごとに、次のいずれかの値を指定できます。

  • linux または windows などの正確な値。正確な値は、数字または文字で始まっている必要があります。

  • *: これはすべての値と一致します。値が存在しない場合でも一致します。

  • /windows|linux/ などの Java スタイルの正規表現。正規表現は、スラッシュ文字 (/) で開始し終了する必要があります。たとえば、正規表現 /.+/ は空白以外のすべての値と一致します。

このオブジェクトには、次の情報が含まれます。

os

(オプション) このマニフェストがサポートするプラットフォームのオペレーティングシステムの名前。一般的なプラットフォームには次の値が含まれます。

  • linux

  • windows

  • darwin (macOS)

architecture

(オプション) このマニフェストがサポートするプラットフォームのプロセッサアーキテクチャ。一般的なアーキテクチャには次の値が含まれます。

  • amd64

  • arm

  • aarch64

  • x86

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 - システムパス上に runnable があるかどうかをチェックします。例えば、Python 3 が利用可能な場合には、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 スクリプトが成功コードで終了すると、コンポーネントは 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 - システムパス上に runnable があるかどうかをチェックします。例えば、Python 3 が利用可能な場合には、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 を使用します。終了していないスクリプトをコンポーネントが開始した場合に、そのコンポーネントのステータスを RUNNING または ERRORED にセットするには、UpdateState IPC オペレーションを使用します。例えば、/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 - システムパス上に runnable があるかどうかをチェックします。例えば、Python 3 が利用可能な場合には、onpath python3 を使用してこのライフサイクルステップをスキップします。

  • exists file - ファイルが存在するかどうかをチェックします。たとえば、/tmp/my-configuration.db が存在する場合には、exists /tmp/my-configuration.db を使用してこのライフサイクルステップをスキップします。

Timeout

(オプション) AWS IoT Greengrass Core ソフトウェアがプロセスを終了する前に、スクリプトが実行できる最大時間 (秒単位)。

デフォルト: 120 秒

Setenv

(オプション) スクリプトに提供する環境変数のディクショナリ。これらの環境変数は、Lifecycle.Setenv で指定した変数を上書きします。

Shutdown

(オプション) コンポーネントのシャットダウン時に実行するスクリプトを定義するオブジェクトまたは文字列。

Startup でバックグラウンドプロセスを開始した場合は、コンポーネントがシャットダウンするときには Shutdown ステップを使用してそのプロセスを停止します。例えば、/etc/init.d/mysqld stop で MySQL プロセスを停止する Shutdown ステップを定義することができます。

このライフサイクルステップが実行されると、コンポーネントは STOPPING 状態に入ります。

このオブジェクトまたは文字列には、次の情報が含まれます。

Script

実行するスクリプト。

RequiresPrivilege

(オプション) ルート権限でスクリプトを実行できます。このオプションを true に設定すると、AWS IoT Greengrass Core ソフトウェアは、このコンポーネントを実行するように設定したシステムユーザーとしてではなく、root としてこのライフサイクルスクリプトを実行します。デフォルトは false です。

Skipif

(オプション) スクリプトを実行するかどうかを決定するためのチェック。実行可能ファイルがパス上にあるかどうか、あるいはファイルが存在するかどうかを確認するように定義できます。出力が True の場合、AWS IoT Greengrass Core ソフトウェアはこのステップをスキップします。次から選択します。

  • onpath runnable - システムパス上に runnable があるかどうかをチェックします。例えば、Python 3 が利用可能な場合には、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 - システムパス上に runnable があるかどうかをチェックします。例えば、Python 3 が利用可能な場合には、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 をシステムサービスとして設定する」を参照してください。

このオブジェクトまたは文字列には、次の情報が含まれます。

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 を指定すれば、URI s3://DOC-EXAMPLE-BUCKET/path/to/my_script.py を持つアーティファクトへのパスを取得できます。

  • 抽出されたアーカイブ - artifacts:decompressedPath レシピ変数を使用して、抽出されたアーカイブアーティファクトが含まれるフォルダへのパスを取得します。AWS IoT Greengrass Core ソフトウェアは、各アーカイブをアーカイブと同じ名前のフォルダに抽出します。例えば、レシピで {artifacts:decompressedPath}/my_archive/my_script.py を指定すれば、URI s3://DOC-EXAMPLE-BUCKET/path/to/my_archive.zip を持つアーカイブアーティファクト内にある my_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: onpath executable | exists file Script: command1 key2: Install: Script: command2 all: Install: Script: command3
例 末尾レベルの選択キーを使用したグローバルライフサイクルの例
Lifecycle: Install: Script: key1: command1 key2: command2 all: command3
例 複数のレベルの選択キーを使用したグローバルライフサイクルの例
Lifecycle: key1: Install: Skipif: onpath executable | exists file Script: command1 key2: Install: Script: command2 all: Install: Script: key3: command3 key4: command4 all: command5

レシピ変数

レシピ変数は、現在のコンポーネントと nucleus の情報を公開し、レシピで使用できるようにします。例えば、レシピ変数を使用して、ライフサイクルスクリプトで実行するアプリケーションにコンポーネント設定パラメータを渡すことができます。

レシピ変数は、以下のコンポーネントレシピの各セクションで使用できます。

レシピ変数は {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 コンポーネントのためのレシピです。

JSON
{ "RecipeFormatVersion": "2020-01-25", "ComponentName": "com.example.HelloWorld", "ComponentVersion": "1.0.0", "ComponentDescription": "My first AWS IoT Greengrass component.", "ComponentPublisher": "Amazon", "ComponentConfiguration": { "DefaultConfiguration": { "Message": "world" } }, "Manifests": [ { "Platform": { "os": "linux" }, "Lifecycle": { "Run": "python3 -u {artifacts:path}/hello_world.py \"{configuration:/Message}\"" } }, { "Platform": { "os": "windows" }, "Lifecycle": { "Run": "py -3 -u {artifacts:path}/hello_world.py \"{configuration:/Message}\"" } } ] }
YAML
--- RecipeFormatVersion: '2020-01-25' ComponentName: com.example.HelloWorld ComponentVersion: '1.0.0' ComponentDescription: My first AWS IoT Greengrass component. ComponentPublisher: Amazon ComponentConfiguration: DefaultConfiguration: Message: world Manifests: - Platform: os: linux Lifecycle: Run: | python3 -u {artifacts:path}/hello_world.py "{configuration:/Message}" - Platform: os: windows Lifecycle: Run: | py -3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"

Python ランタイムコンポーネントの例

次のレシピは、Python をインストールするコンポーネントについて説明しています。このコンポーネントは 64 ビット Linux デバイスをサポートします。

JSON
{ "RecipeFormatVersion": "2020-01-25", "ComponentName": "com.example.PythonRuntime", "ComponentDescription": "Installs Python 3.7", "ComponentPublisher": "Amazon", "ComponentVersion": "3.7.0", "Manifests": [ { "Platform": { "os": "linux", "architecture": "amd64" }, "Lifecycle": { "Install": "apt-get update\napt-get install python3.7" } } ] }
YAML
--- RecipeFormatVersion: '2020-01-25' ComponentName: com.example.PythonRuntime ComponentDescription: Installs Python 3.7 ComponentPublisher: Amazon ComponentVersion: '3.7.0' Manifests: - Platform: os: linux architecture: amd64 Lifecycle: Install: | apt-get update apt-get install python3.7

複数のフィールドを指定するコンポーネントレシピ

次のコンポーネントレシピでは、複数のレシピフィールドを使用します。

JSON
{ "RecipeFormatVersion": "2020-01-25", "ComponentName": "com.example.FooService", "ComponentDescription": "Complete recipe for AWS IoT Greengrass components", "ComponentPublisher": "Amazon", "ComponentVersion": "1.0.0", "ComponentConfiguration": { "DefaultConfiguration": { "TestParam": "TestValue" } }, "ComponentDependencies": { "BarService": { "VersionRequirement": "^1.1.0", "DependencyType": "SOFT" }, "BazService": { "VersionRequirement": "^2.0.0" } }, "Manifests": [ { "Platform": { "os": "linux", "architecture": "amd64" }, "Lifecycle": { "Install": { "Skipif": "onpath git", "Script": "sudo apt-get install git" } }, "Artifacts": [ { "URI": "s3://DOC-EXAMPLE-BUCKET/hello_world.zip", "Unarchive": "ZIP" }, { "URI": "s3://DOC-EXAMPLE-BUCKET/hello_world_linux.py" } ] }, { "Lifecycle": { "Install": { "Skipif": "onpath git", "Script": "sudo apt-get install git", "RequiresPrivilege": "true" } }, "Artifacts": [ { "URI": "s3://DOC-EXAMPLE-BUCKET/hello_world.py" } ] } ] }
YAML
--- RecipeFormatVersion: '2020-01-25' ComponentName: com.example.FooService ComponentDescription: Complete recipe for AWS IoT Greengrass components ComponentPublisher: Amazon ComponentVersion: '1.0.0' ComponentConfiguration: DefaultConfiguration: TestParam: TestValue ComponentDependencies: BarService: VersionRequirement: ^1.1.0 DependencyType: SOFT BazService: VersionRequirement: ^2.0.0 Manifests: - Platform: os: linux architecture: amd64 Lifecycle: Install: Skipif: onpath git Script: sudo apt-get install git Artifacts: - URI: s3://DOC-EXAMPLE-BUCKET/hello_world.zip Unarchive: ZIP - URI: s3://DOC-EXAMPLE-BUCKET/hello_world_linux.py - Lifecycle: Install: Skipif: onpath git Script: sudo apt-get install git RequiresPrivilege: true Artifacts: - URI: s3://DOC-EXAMPLE-BUCKET/hello_world.py