Greengrass Development Kit CLI 設定ファイル

AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) は、gdk-config.json という名前の設定ファイルから読み込んで、コンポーネントを構築およびパブリッシュします。この設定ファイルは、コンポーネントリポジトリのルートに存在する必要があります。GDK CLI init コマンドを使用して、この設定ファイルでコンポーネントリポジトリを初期化することができます。

トピック

GDK CLI 設定ファイルの形式
GDK CLI 設定ファイルの例

GDK CLI 設定ファイルの形式

コンポーネントの GDK CLI 設定ファイルを定義する場合、次の情報を JSON 形式で指定します。

gdk_version

このコンポーネントとの互換性がある GDK CLI の最小バージョン。この値は、リリースの GDK CLI バージョンの 1 つである必要があります。

component

このコンポーネントの設定。

componentName

author

コンポーネントの作成者またはパブリッシャー。

version

コンポーネントのバージョン。次のいずれかを指定します。

NEXT_PATCH - このオプションを選択すると、コンポーネントをパブリッシュするときに GDK CLI がバージョンを設定します。GDK CLI は AWS IoT Greengrass サービスを照会して、コンポーネントの最新のパブリッシュバージョンを特定します。次に、そのバージョンの後の次のパッチバージョンにバージョンを設定します。コンポーネントをまだパプリッシュしていない場合は、GDK CLI はバージョン1.0.0 を使用します。

このオプションを選択する場合、AWS IoT Greengrass Core ソフトウェアが動作するローカル開発用コンピュータにコンポーネントをデプロイしテストするために、Greengrass CLI を使用することはできません。ローカルデプロイを有効にするには、代わりにセマンティックバージョンを指定する必要があります。
1.0.0 などのセマンティックバージョンです。セマンティックバージョンでは、major.minor.patch の番号付けシステムが使用されます。詳細については、「セマンティックバージョンの仕様」を参照してください。

コンポーネントをデプロイしてテストする Greengrass コアデバイスでコンポーネントを開発する場合は、このオプションを選択します。Greengrass CLI を使用してローカルデプロイを作成する場合は、特定のバージョンでコンポーネントを構築する必要があります。

build

このコンポーネントのソースをアーティファクトに構築するために使用する設定。このオブジェクトには、次の情報が含まれます。

build_system

使用するビルドシステム。次のオプションから選択します。

zip - コンポーネントのフォルダを ZIP ファイルにパッケージ化し、コンポーネントの唯一のアーティファクトとして定義します。次のタイプのコンポーネントには、このオプションを選択します。
- Python や JavaScript などのインタプリタ形式のプログラミング言語を使用するコンポーネント。
- 機械学習モデルやその他のリソースなどの、コード以外のファイルをパッケージ化するコンポーネント。
GDK CLI は、コンポーネントのフォルダをコンポーネントフォルダと同じ名前の zip ファイルに圧縮します。例えば、コンポーネントフォルダの名前が HelloWorld の場合、GDK CLI は HelloWorld.zip という名前の zip ファイルを作成します。

注記
Windows デバイスで GDK CLI バージョン 1.0.0 を使用する場合、コンポーネントフォルダと zip ファイル名には小文字のみを含める必要があります。

GDK CLI がコンポーネントのフォルダを zip ファイルに圧縮する際、次のファイルはスキップされます。
- gdk-config.json ファイル
- recipe ファイル (recipe.json または recipe.yaml)
- ビルドフォルダ (greengrass-build など)
maven - mvn clean package コマンドを実行して、コンポーネントのソースをアーティファクト内にビルドします。Java コンポーネントなどの Maven を使用するコンポーネントの場合は、このオプションを選択します。

Windows デバイスでは、この機能は GDK CLI v1.1.0 以降で利用できます。
gradle - gradle build コマンドを実行して、コンポーネントのソースをアーティファクト内にビルドします。Gradle を使用するコンポーネントの場合は、このオプションを選択します。この機能は GDK CLI v1.1.0 以降で利用できます。

gradle ビルドシステムは、ビルドファイルとして Kotlin DSL をサポートしています。この機能は GDK CLI v1.2.0 以降で利用できます。
gradlew - gradlew コマンドを実行して、コンポーネントのソースをアーティファクト内にビルドします。Gradle Wrapper を使用するコンポーネントの場合は、このオプションを選択します。

この機能は GDK CLI v1.2.0 以降で利用できます。
custom - カスタムコマンドを実行して、コンポーネントのソースを recipe とアーティファクトにビルドします。custom_build_command パラメータでカスタムコマンドを指定します。

custom_build_command

(オプション) カスタムビルドシステムに対して実行するカスタムビルドコマンド。build_system の custom を指定する場合は、このパラメータを指定する必要があります。

重要

このコマンドは、コンポーネントフォルダ内の次のフォルダに recipe とアーティファクトを作成する必要があります。GDK CLI は、コンポーネントビルドコマンドを実行したときにこれらのフォルダを作成します。

recipe フォルダ: greengrass-build/recipes
アーティファクトフォルダ: greengrass-build/artifacts/componentName/componentVersion

ComponentName をコンポーネント名に置き換えて、ComponentVersion をコンポーネントバージョンまたはNEXT_PATCH に置き換えます。

1 つの文字列または文字列のリストを指定できます。各文字列が、コマンド内の単語になります。例えば、C++ コンポーネントのカスタムビルドコマンドを実行するには、cmake --build build --config Release または ["cmake", "--build", "build", "--config", "Release"] を指定する可能性があります。

カスタムビルドシステムの例を表示するには、「GitHub の aws.greengrass.labs.LocalWebServer community component」を参照してください。

options

(オプション) コンポーネントのビルドプロセス中に使用される追加の設定オプション。

この機能は GDK CLI v1.2.0 以降で利用できます。

excludes

zip ファイルを構築するときにコンポーネントディレクトリから除外するファイルを定義するグロブパターンのリスト。build_system が zip の場合にのみ有効です。

注記

GDK CLI バージョン 1.4.0 以前では、除外リストのエントリに一致するファイルは、コンポーネントのすべてのサブディレクトリから除外されます。GDK CLI バージョン 1.5.0 以降で同じ動作を実現するには、除外リストの既存のエントリに **/ を付加します。例えば、*.txt はディレクトリのみからテキストファイルを除外し、**/*.txt はすべてのディレクトリとサブディレクトリからテキストファイルを除外します。

GDK CLI バージョン 1.5.0 以降では、excludes が GDK 設定ファイルで定義されていると、コンポーネントビルド中に警告が表示されることがあります。この警告を無効にするには、環境変数 GDK_EXCLUDES_WARN_IGNORE を true に設定します。

GDK CLI は、常に zip ファイルから以下のファイルを除外します。

gdk-config.json ファイル
recipe ファイル (recipe.json または recipe.yaml)
ビルドフォルダ (greengrass-build など)

次のファイルはデフォルトで除外されます。ただし、これらのファイルのうち、どのファイルを除外するかは、excludes オプションで制御することができます。

接頭辞「test」で始まる任意のフォルダ (test*)
全ての非表示のファイル
node_modules フォルダ

excludes オプションを指定すると、GDK CLI は excludes オプションで設定したファイルのみを除外します。excludes オプションを指定しない場合、GDK CLI は前述のデフォルトのファイルとフォルダを除外します。

zip_name

構築プロセス中に zip アーティファクトを作成する際に使用する zip ファイル名。build_system が zip の場合にのみ有効です。build_system が空の場合、コンポーネント名が zip ファイル名として使用されます。

publish

このコンポーネントを AWS IoT Greengrass サービスにパブリッシュするために使用する設定。

GDK CLI v1.1.0 以降を使用する場合、--bucket 引数を指定して、GDK CLI がコンポーネントのアーティファクトをアップロードする S3 バケットを指定します。この引数を指定しない場合、GDK CLI は名前が bucket-region-accountId である S3 バケットにアップロードします。ここでは、gdk-config.json で指定する値は bucket と region であり、accountId は AWS アカウント ID です。GDK CLI は、バケットが存在しない場合に作成します。

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

bucket

コンポーネントのアーティファクトをホストするために使用する S3 バケット名。

region

GDK CLI がこのコンポーネントをパブリッシュする場所となる AWS リージョン。

GDK CLI v1.3.0 以降を使用している場合、このプロパティはオプションです。

options

(オプション) コンポーネントのバージョン作成時に使用される追加の設定オプション。

この機能は GDK CLI v1.2.0 以降で利用できます。

file_upload_args: ファイルをバケットにアップロードする際に Amazon S3 に送信される、引数 (メタデータや暗号化メカニズムなど) を含む JSON 構造。許可される引数のリストについては、Boto3 ドキュメントの「S3Transfer」クラスを参照してください。

test-e2e

(オプション) コンポーネントのエンドツーエンドのテスト中に使用する設定。この機能は GDK CLI v1.3.0 以降で利用できます。

build

build_system – 使用するビルドシステム。デフォルトのオプションは maven です。次のオプションから選択します。

maven – mvn package コマンドを実行してテストモジュールを構築します。Maven を使用するテストモジュールを構築するには、このオプションを選択します。
gradle – gradle build コマンドを実行してテストモジュールを構築します。Gradle を使用するテストモジュールについては、このオプションを選択します。

gtf_version

(オプション) Greengrass Testing Framework (GTF) を使用して GDK プロジェクトを初期化する際に、エンドツーエンドのテストモジュールの依存関係として使用する GTF のバージョン。この値は、リリースの GTF バージョンの 1 つである必要があります。デフォルトは GTF バージョン 1.1.0 です。

gtf_options

(オプション) コンポーネントのエンドツーエンドのテスト中に使用される追加の設定オプション。

次のリストには、GTF バージョン 1.1.0 で使用できるオプションが含まれています。

additional-plugins – (オプション) 追加の Cucumber プラグイン
aws-region – AWS のサービスの特定のリージョンレベルのエンドポイントをターゲットにします。デフォルトは、AWS SDK が検出するものです。
credentials-path – オプションの AWS プロファイル認証情報のパス。デフォルトは、ホスト環境で検出された認証情報です。
credentials-path-rotation – AWS 認証情報のオプションのローテーション期間。デフォルトで 15 分または PT15M に設定されます。
csr-path – デバイス証明書の生成に使用される CSR のパス。
device-mode – テスト対象のターゲットデバイス。デフォルトはローカルデバイスです。
env-stage – Greengrass のデプロイ環境をターゲットに設定します。デフォルトは本番です。
existing-device-cert-arn – Greengrass のデバイス証明書として使用する既存の証明書の ARN。
feature-path – 追加の機能ファイルを含むファイルまたはディレクトリ。デフォルトでは、追加の機能ファイルは使用されません。
gg-cli-version – Greengrass CLI のバージョンをオーバーライドします。デフォルトは ggc.version にある値です。
gg-component-bucket – Greengrass コンポーネントを格納する既存の Amazon S3 バケットの名前。
gg-component-overrides – Greengrass コンポーネントのオーバーライドのリスト。
gg-persist – テスト実行後に保持されるテスト要素のリスト。デフォルトでは、何も保持しないよう設定されています。許容される値は、aws.resources、installed.software、および generated.files です。
gg-runtime – テストがテストリソースとどのようにインタラクションするかに影響する値のリスト。これらの値は gg.persist パラメータよりも優先されます。デフォルトが空の場合、インストールされている Greengrass ランタイムを含む、すべてのテストリソースがテストケースによって管理されると想定されます。許容される値は、aws.resources、installed.software、および generated.files です。
ggc-archive – アーカイブされた Greengrass nucleus コンポーネントへのパス。
ggc-install-root – Greengrass nucleus コンポーネントをインストールするディレクトリ。デフォルトは test.temp.path とテスト実行フォルダです。
ggc-log-level – テスト実行の Greengrass nucleus ログレベルを設定します。デフォルトは「INFO」です。
ggc-tes-rolename – AWS のサービスにアクセスするために AWS IoT Greengrass Core が引き受ける IAM ロール。指定された名前のロールが存在しない場合は、ロールとデフォルトのアクセスポリシーが作成されます。
ggc-trusted-plugins – Greengrass に追加する必要がある、信頼されたプラグインのパス (ホスト上) のカンマ区切りリスト。DUT 自体のパスを指定するには、パスの前に「dut:」というプレフィックスを付けます。
ggc-user-name – Greengrass nucleus の user:group posixUser の値。デフォルトは、ログインしている現在のユーザー名です。
ggc-version – 実行中の Greengrass nucleus コンポーネントのバージョンをオーバーライドします。デフォルトは ggc.archive にある値です。
log-level – テスト実行のログレベル。デフォルトは「INFO」です。
parallel-config – JSON 文字列としてのバッチインデックスとバッチ数のセット。バッチインデックスのデフォルト値は 0、バッチ数は 1 です。
proxy-url – この URL を介してトラフィックをルーティングするようにすべてのテストを設定します。
tags – 機能タグのみを実行します。「&」を使用して組み合わせることができます
test-id-prefix – AWS リソース名とタグを含むすべてのテスト固有のリソースに適用される共通のプレフィックス。デフォルトは「gg」プレフィックスです。
test-log-path – テスト実行全体の結果を含むディレクトリ。デフォルトは「testResults」です。
test-results-json – 結果として得られる Cucumber JSON レポートがディスクに書き込まれた状態で生成されるかどうかを決定するフラグ。デフォルトは true です。
test-results-log – コンソール出力がディスクに書き込まれた状態で生成されるかどうかを決定するフラグ。デフォルトは false です。
test-results-xml – 結果として得られる JUnit XML レポートがディスクに書き込まれた状態で生成されるかどうかを決定するフラグ。デフォルトは true です。
test-temp-path – ローカルテストアーティファクトを生成するディレクトリ。デフォルトは、gg-testing というプレフィックスが付いたランダムな一時ディレクトリです。
timeout-multiplier – すべてのテストタイムアウトに提供される乗数。デフォルトは 1.0 です。

GDK CLI 設定ファイルの例

次の GDK CLI 設定ファイルの例を参照し、Greengrass コンポーネント環境の設定に役立ててください。

Hello World (Python)

次の GDK CLI 設定ファイルは、Python スクリプトを実行する Hello World コンポーネントをサポートしています。この設定ファイルでは、zip ビルドシステムを使用して、GDK CLI がアーティファクトとしてアップロードする ZIP ファイルにコンポーネントの Python スクリプトをパッケージ化しています。


{
  "component": {
    "com.example.PythonHelloWorld": {
      "author": "Amazon",
      "version": "NEXT_PATCH",
      "build": {
        "build_system" : "zip",
        "options": {
           "excludes": [".*"]
        }
      },
      "publish": {
        "bucket": "greengrass-component-artifacts",
        "region": "us-west-2",
        "options": {
           "file_upload_args": {
              "Metadata": {
                 "some-key": "some-value"
              }
           }
        }
      }
    },
  "test-e2e":{
    "build":{
        "build_system": "maven"
    },
    "gtf_version": "1.1.0",
    "gtf_options": { 
         "tags": "Sample"
     }
  },
  "gdk_version": "1.6.1"
  }
}

Hello World (Java)

次の GDK CLI 設定ファイルは、Java アプリケーションを実行する Hello World コンポーネントをサポートしています。この設定ファイルでは、maven ビルドシステムを使用して、GDK CLI がアーティファクトとしてアップロードする JAAR ファイルにコンポーネントの Java ソースコードをパッケージ化しています。


{
  "component": {
    "com.example.JavaHelloWorld": {
      "author": "Amazon",
      "version": "NEXT_PATCH",
      "build": {
        "build_system" : "maven"
      },
      "publish": {
        "bucket": "greengrass-component-artifacts",
        "region": "us-west-2",
        "options": {
           "file_upload_args": {
              "Metadata": {
                 "some-key": "some-value"
              }
           }
        }
      }
  },
  "test-e2e":{
    "build":{
        "build_system": "maven"
    },
    "gtf_version": "1.1.0",
    "gtf_options": { 
         "tags": "Sample"
     }
  },
  "gdk_version": "1.6.1"
  }
}

コミュニティコンポーネント

Greengrass ソフトウェアカタログの複数のコミュニティコンポーネントで GDK CLI を使用しています。GDK CLI 設定ファイルは、これらのコンポーネントのリポジトリで確認できます。

コミュニティコンポーネントの GDK CLI 設定ファイルを表示するには

次のコマンドを実行して、GDK CLI を使用するコミュニティコンポーネントをリスト表示します。


gdk component list --repository

レスポンスには、GDK CLI を使用する各コミュニティコンポーネントの GitHub リポジトリの名前がリストアップされます。各リポジトリは awslabs 組織にあります。


[2022-02-22 17:27:31] INFO - Listing all the available component repositories from Greengrass Software Catalog.
[2022-02-22 17:27:31] INFO - Found '6' component repositories to display.
1. aws-greengrass-labs-database-influxdb
2. aws-greengrass-labs-telemetry-influxdbpublisher
3. aws-greengrass-labs-dashboard-grafana
4. aws-greengrass-labs-dashboard-influxdb-grafana
5. aws-greengrass-labs-local-web-server
6. aws-greengrass-labs-lookoutvision-gstreamer

次の URL でコミュニティコンポーネントの GitHub リポジトリを開きます。community-component-name を、前のステップのコミュニティコンポーネント名に置き換えます。
```
https://github.com/awslabs/community-component-name
```

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

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

ドキュメントの表記規則

test-e2e

Greengrass コマンドラインインターフェイス