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

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

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

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

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

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

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

重要

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

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

レシピの検証

Greengrass は、YAMLコンポーネントバージョンの作成時に JSONまたはコンポーネントレシピを検証します。この recipe 検証は、デプロイの問題の可能性を防ぐために、 JSONまたは YAML コンポーネント 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 は、コンポーネント installs. AWS IoT Greengrass waits 時にコンポーネントの依存関係をインストールし、コンポーネントを起動する前に依存関係を開始します。各オブジェクトには、次の情報が含まれます:

VersionRequirement

この依存関係との互換性のあるコンポーネントバージョンを定義する npm スタイルのセマンティックバージョン制約。1 つのバージョンまたはバージョンの範囲を指定できます。詳細については、「npm セマンティックバージョン計算ツール」を参照してください。

DependencyType

(オプション) 依存関係のタイプ。次のオプションから選択します。

SOFT - 依存関係が状態を変化させても、コンポーネントは再起動しません。
HARD - 依存関係が状態を変化させると、コンポーネントは再起動します。

デフォルトは HARD です。

ComponentType

(オプション) コンポーネントのタイプ。

注記

コンポーネントを作成するときに、recipe. AWS IoT Greengrass sets でコンポーネントタイプを指定することはお勧めしません。

タイプは、次のいずれかになります。

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 AWSと直接インターフェイスする Java で記述された提供のコンポーネントを対象としているため、コンポーネントレシピでこのオプションを使用することはお勧めしません。どのパブリックコンポーネントがプラグインなのかの詳細については、「AWS が提供したコンポーネント」を参照してください。
aws.greengrass.nucleus - nucleus コンポーネント。詳細については、「Greengrass nucleus」を参照してください。

コンポーネントレシピでこのオプションを使用することは推奨しません。これは、Greengrass nucleus コンポーネントを対象としたもので、 AWS IoT Greengrass Core ソフトウェアの最低限の機能のみが提供されるからです。

レシピからコンポーネントを作成する場合は aws.greengrass.generic、Lambda 関数からコンポーネントを作成する場合は aws.greengrass.lambda がデフォルトです。

詳細については、「コンポーネントタイプ」を参照してください。

ComponentSource

（オプション) コンポーネントが実行する Lambda 関数ARNの。

Lambda 関数からコンポーネントを作成するときに、recipe. AWS IoT Greengrass sets でコンポーネントソースを指定することはお勧めしません。詳細については、「AWS Lambda 関数を実行する」を参照してください。

Manifests

オブジェクトのリストで、各オブジェクトがコンポーネントのライフサイクル、パラメータ、およびプラットフォームに対する要件を定義しています。コアデバイスが複数のマニフェストのプラットフォーム要件に一致する場合、はコアデバイスが一致する最初のマニフェスト AWS IoT Greengrass を使用します。コアデバイスが正しいマニフェストを確実に使用するように、まずはより厳格なプラットフォーム要件を持つマニフェストを定義してください。すべてのプラットフォームに適用されるマニフェストは、リストの最後のマニフェストである必要があります。

重要

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

Name

(オプション) このマニフェストが定義するプラットフォームのわかりやすい名前。

このパラメータを省略すると、はプラットフォームosとから名前 AWS IoT Greengrass を作成します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 ソフトウェアは、このコンポーネントを実行するように設定したシステムユーザーとしてではなく、このライフサイクルスクリプトをルートとして実行します。デフォルトは 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 スクリプトが成功コードで終了すると、コンポーネントは STOPPING 状態に入ります。shutdown スクリプトを指定すると実行されます。指定しない場合、コンポーネントは FINISHED状態になります。

このコンポーネントに依存するコンポーネントは、このライフサイクルステップが実行されたときに開始されます。依存コンポーネントが使用するサービスなどのバックグラウンドプロセスを実行するには、代わりに startup ライフサイクルステップを使用します。

run ライフサイクルによりコンポーネントをデプロイすると、そのライフサイクルスクリプトが実行された直後から、デプロイが完了したコアデバイスを報告できるようになります。その結果、run ライフサイクルスクリプトが実行後すぐに失敗した場合でも、そのデプロイを正常に完了することができます。デプロイステータスを、コンポーネントの開始スクリプトの結果に依存させたい場合は、代わりに startup ライフサイクルステップを使用します。

注記

1 つの startup または run ライフサイクルのみを定義できます。

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

Script

実行するスクリプト。

RequiresPrivilege

Skipif

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 を使用します。UpdateState IPC オペレーションを使用して、コンポーネントのステータスを RUNNINGに設定するか、コンポーネントが終了しないスクリプトを開始するERROREDときにに設定します。例えば、で MySQL プロセスを開始するstartupステップを定義できます/etc/init.d/mysqld start。

このライフサイクルステップが実行されると、コンポーネントは STARTING 状態に入ります。startup スクリプトが成功コードで終了すると、コンポーネントは RUNNING 状態に入ります。その後、依存コンポーネントを開始することができます。

startup ライフサイクルによりコンポーネントをデプロイすると、そのライフサイクルスクリプトが終了したか、もしくは状態を報告した後に、コアデバイスがデプロイの完了を報告できるようになります。言い換えると、すべてのコンポーネントの起動スクリプトが終了したか、あるいは状態を報告するまで、デプロイのステータスは IN_PROGRESS のままです

注記

1 つの startup または run ライフサイクルのみを定義できます。

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

Script

実行するスクリプト。

RequiresPrivilege

Skipif

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

(オプション) コンポーネントのシャットダウン時に実行するスクリプトを定義するオブジェクトまたは文字列。シャットダウンライフサイクルを使用して、コンポーネントが STOPPING状態にあるときに実行するコードを実行します。シャットダウンライフサイクルは、 startupまたは runスクリプトによって開始されるプロセスを停止するために使用できます。

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

shutdown スクリプトは、コンポーネントが STOPPING状態になった後に実行されます。スクリプトが正常に完了すると、コンポーネントは FINISHED状態になります。

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

Script

実行するスクリプト。

RequiresPrivilege

Skipif

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

Skipif

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 ソフトウェアがデプロイにブートストラップステップがあるすべてのコンポーネントのブートストラップステップを完了すると、ソフトウェアが再起動します。

重要

Core ソフトウェアまたは AWS IoT Greengrass コアデバイスを再起動するには、 Core AWS IoT Greengrass ソフトウェアをシステムサービスとして設定する必要があります。 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

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://amzn-s3-demo-bucket/path/to/my_script.py。
抽出されたアーカイブ – artifacts:decompressedPath recipe 変数を使用して、抽出されたアーカイブアーティファクトを含むフォルダへのパスを取得します。 AWS IoT Greengrass Core ソフトウェアは、各アーカイブをアーカイブと同じ名前のフォルダに抽出します。例えば、レシピ{artifacts:decompressedPath}/my_archive/my_script.pyでを指定して、を持つアーカイブアーティファクトmy_script.pyの URI へのパスを取得しますs3://amzn-s3-demo-bucket/path/to/my_archive.zip。

注記

ローカルコアデバイスでアーカイブアーティファクトを使用してコンポーネントを開発する場合、そのアーティファクトURIのがない可能性があります。アーティファクトを抽出するUnarchiveオプションを使用してコンポーネントをテストするには、ファイル名URIがアーカイブアーティファクトファイルの名前と一致するを指定します。アーカイブアーティファクトをアップロードするURI予定のを指定するか、新しいプレースホルダーを指定できますURI。例えば、ローカルデプロイ時に my_archive.zip アーティファクトを抽出する場合には、s3://amzn-s3-demo-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 recipe 変数を使用して、このフォルダを含むフォルダへのパスを取得できます。

デフォルトは NONE です。

Permission

(オプション) このアーティファクトファイルに設定するアクセス許可を定義するオブジェクト。読み取り許可と実行許可を設定できます。

注記

AWS IoT Greengrass Core ソフトウェアではコンポーネントがアーティファクトフォルダ内のアーティファクトファイルを編集できないため、書き込みアクセス許可を設定することはできません。コンポーネント内のアーティファクトファイルを編集するには、別の場所にコピーするか、新しいアーティファクトファイルをパブリッシュしてデプロイします。

アーティファクトを解凍するアーカイブとして定義すると、 AWS IoT Greengrass Core ソフトウェアはアーカイブから解凍するファイルにこれらのアクセス許可を設定します。 AWS IoT Greengrass Core ソフトウェアは、フォルダのアクセス許可を Readおよび ALLのに設定しますExecute。これにより、コンポーネントはフォルダ内の解凍されたファイルを表示できるようになります。アーカイブからの個々のファイルにアクセス許可を設定する場合は、インストールライフサイクルスクリプトでアクセス許可を設定することができます。

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

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 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: either onpath executable or exists file
      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 は、コンポーネントのライフサイクル定義でのみこの recipe 変数をサポートします。

このレシピ変数には、次の入力があります。

component_dependency_name - (オプション) クエリを実行するコンポーネント依存関係の名前。このレシピが定義するコンポーネントを照会する場合は、このセグメントを省略します。直接的な依存関係のみを指定できます。
json_pointer – 評価する設定値へのJSONポインタ。JSON ポインタはスラッシュで始まります/。ネストされたコンポーネント設定の値を識別するには、フォワードスラッシュ (/) を使用して、設定の各レベルのキーを区切ります。数字をキーとして使用して、リスト内のインデックスを指定できます。詳細については、JSON「ポインタ仕様」を参照してください。

AWS IoT Greengrass Core は、 YAML 形式のレシピにJSONポインタを使用します。

JSON ポインタは次のノードタイプを参照できます。

値 node. AWS IoT Greengrass Core は、recipe 変数を値の文字列表現に置き換えます。Null 値は文字列の null に置き換えられます。
オブジェクト node. AWS IoT Greengrass Core は、recipe 変数をそのオブジェクトのシリアル化されたJSON文字列表現に置き換えます。
node. AWS IoT Greengrass Core は recipe 変数を置き換えません。

例えば、{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 解凍します。この変数を使用して、コンポーネントのライフサイクルで実行するスクリプトの場所などを特定できます。

各アーティファクトは、解凍されたパス内のフォルダに解凍されます。フォルダの名前はアーティファクトと同じ名前から拡張子を引いたものになります。例えば、という名前のZIPアーティファクトは {artifacts:decompressedPath}/modelsフォルダにmodels.zip解凍されます。

このレシピ変数には、次の入力があります。

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 コンポーネントレシピ

次のレシピは、Python スクリプトを実行する Hello World コンポーネントについて説明しています。このコンポーネントはすべてのプラットフォームをサポートしており、 AWS IoT Greengrass が Python スクリプトに引数としてわたす Message パラメータを受け入れます。これは、入門チュートリアルの Hello World コンポーネントのためのレシピです。

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

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

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

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

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"
        },
        "Setenv": {
          "environment_variable1": "variable_value1",
          "environment_variable2": "variable_value2"
        }
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/hello_world.zip",
          "Unarchive": "ZIP"
        },
        {
          "URI": "s3://amzn-s3-demo-bucket/hello_world_linux.py"
        }
      ]
    },
    {
      "Lifecycle": {
        "install": {
          "Skipif": "onpath git",
          "Script": "sudo apt-get install git",
          "RequiresPrivilege": "true"
        }
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-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
      Setenv:
        environment_variable1: variable_value1
        environment_variable2: variable_value2
    Artifacts:
      - URI: 's3://amzn-s3-demo-bucket/hello_world.zip'
        Unarchive: ZIP
      - URI: 's3://amzn-s3-demo-bucket/hello_world_linux.py'
  - Lifecycle:
      install:
        Skipif: onpath git
        Script: sudo apt-get install git
        RequiresPrivilege: 'true'
    Artifacts:
      - URI: 's3://amzn-s3-demo-bucket/hello_world.py'

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

Docker コンテナの実行

環境変数

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

重要

トピック

レシピの検証

レシピの形式

ヒント

注記

注記

注記

重要

ヒント

注記

注記

注記

注記

重要

注記

重要

注記

注記

注記

ヒント

例 トップレベルの選択キーを使用したグローバルライフサイクルの例

例 末尾レベルの選択キーを使用したグローバルライフサイクルの例

例 複数のレベルの選択キーを使用したグローバルライフサイクルの例

レシピ変数

注記

レシピの例

トピック

Hello World コンポーネントレシピ

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

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

例トップレベルの選択キーを使用したグローバルライフサイクルの例

例末尾レベルの選択キーを使用したグローバルライフサイクルの例

例複数のレベルの選択キーを使用したグローバルライフサイクルの例