Skip to content
@aws/nx-plugin
Blog

Greengrass Component

greengrass#componentジェネレーターは、既存のPythonまたはTypeScriptプロジェクトにAWS IoT Greengrass v2コンポーネントを追加します。レシピ、エントリーポイント、Pythonコンポーネント用のユニットテスト、およびコアデバイス用にコンポーネントをパッケージ化するNxターゲットを作成します。デフォルトのinfraでは、コンポーネントバージョンを公開し、アーティファクトリポジトリを所有し、デプロイメントを記述する再利用可能なCDKコンストラクトまたはTerraformモジュールも提供します。これらのビルディングブロックを独自のインフラストラクチャコードで構成します。ジェネレーターは、デバイス、フリート、またはデプロイメントを単独で作成することはありません。

ホストプロジェクトは既に存在している必要があります。まずpy#projectまたはts#projectで作成してください。

使用方法

Section titled “使用方法”

コンポーネントの生成

Section titled “コンポーネントの生成”

このジェネレーターを実行@aws/nx-plugin:greengrass#component

pnpm nx g @aws/nx-plugin:greengrass#component --project=telemetry --name=pulse --language=python
コマンドを組み立てる12

必須

必須

変更されるファイルを確認するためにドライランを実行することもできます

スクリプトやドキュメントではlanguageを明示的に渡してください。省略された場合、ジェネレーターは選択されたプロジェクト内のtsconfig.jsonからtypescriptを、またはpyproject.tomlからpythonを推測します。両方のファイルを持つプロジェクトは--languageを渡す必要があります。どちらのファイルも持たないプロジェクトはサポートされていません。

ipcは両方の言語でデフォルトでfalseです。Greengrass IPCアクセスを追加するには--ipc=trueを、無効のままにするには--ipc=falseを渡してください。

レシピのComponentPublisherはワークスペースのnpmスコープをデフォルトとします。別の値を設定するには--publisherを渡してください。aws-nx-plugin.config.mtsにはGreengrassパブリッシャー設定はありません。

iac: terraformの場合、このジェネレーターを実行する前にterraform#projectでTerraformアプリケーションを作成してください。Greengrassジェネレーターは、そのアプリケーションにawsccプロバイダー設定を追加します。後でTerraformアプリケーションを作成する場合は、プロバイダーを追加できるようにgreengrass#componentを再実行してください。

--projectは非修飾プロジェクト名を受け入れます。生成されたプロジェクトは名前空間修飾されているため、nx runには完全な名前が必要です。Pythonプロジェクトの場合は<scope>.telemetry、TypeScriptプロジェクトの場合は@<scope>/telemetryです。以下の例では、その名前を<project>と記述し、npmスコープがmy-scopeのワークスペースで--name=infraで生成されたインフラストラクチャプロジェクトを@my-scope/infraと記述します。

ハードウェアとオペレーティングシステム

Section titled “ハードウェアとオペレーティングシステム”

platformは、ボード名ではなく、コアデバイスのオペレーティングシステムとCPUアーキテクチャを選択します。現在のターゲットは、glibcを使用した64ビットLinuxです。

デバイスジェネレーターターゲットステータス
Linux PC、産業用ゲートウェイ、またはEC2 x86_64インスタンスlinux-amd64サポート済み。EC2コアで検証済み
64ビットCPUと64ビットLinuxを搭載したRaspberry Pi、または別のLinux ARM64ゲートウェイlinux-arm64パッケージングはサポート済み。Raspberry Piハードウェアは未検証
上記の両方を含むフリートlinux-amd64-arm64アーキテクチャ固有のマニフェストを持つ1つのコンポーネントバージョン
32ビットLinux / ARMv7を実行しているRaspberry Piなしこのジェネレーターではサポートされていませんが、クラシックGreengrassヌクレウスはARMv7をサポートしています
Raspberry Pi Pico、ESP32、または別のマイクロコントローラーなしコアデバイスのIoTクライアントまたは周辺機器として使用

Raspberry Piでは、uname -mとgetconf LONG_BITの両方を確認してください。このパスにはaarch64と64が必要です。32ビットユーザースペースを実行している64ビットプロセッサは、ARM64デプロイメントターゲットではありません。デバイスには、生成されたレシピで指定されたPythonインタープリター、またはTypeScript用のNode.js、およびGreengrassヌクレウスの前提条件も必要です。Python依存関係のベンダリングはmanylinux_2_28をターゲットとしているため、glibc 2.28以降を使用してください。GPIOライブラリとカスタムネイティブ依存関係は、選択されたプラットフォーム用の互換性のあるバイナリを提供する必要があります。ジェネレーターはこれらの周辺機器をプロビジョニングしません。

生成されたPythonレシピは、インタープリターをホストプロジェクトのrequires-pythonフロア（例：python3.14）に固定します。コンポーネントを実行する各コアデバイスにそのインタープリターをインストールしてください。TypeScriptコンポーネントには、コアデバイスにNode.jsが必要です。

linux-amd64-arm64の場合、レシピにはアーキテクチャごとに1つのマニフェストが含まれます。Greengrassは、Platformがコアデバイスと一致する最初のマニフェストを選択するため、各マニフェストのアーティファクトと環境設定をそのアーキテクチャとペアにしてください。

ESP32ファームウェアは、これらのPythonおよびTypeScriptコンポーネントとは別に実行されます。AWS IoT CoreにMQTTメッセージを送信するか、クライアントデバイスサポートを使用してローカルGreengrassコアに接続できます。ローカルルートには、ブローカー、クライアント認証、MQTTブリッジ設定が必要です。このジェネレーターは、これらやファームウェアをスキャフォールドしません。ARMv7、Windows、musl Linux、およびその他のCPUアーキテクチャには、追加のパッケージングとランタイム作業が必要です。レシピのアーキテクチャラベルを変更するだけでは不十分です。

オプション

Section titled “オプション”
ジェネレーターオプション12 オプション
project必須string

既存の Python または TypeScript ホストプロジェクト

name必須string

コンポーネント名

platformenumデフォルト: linux-arm64

コアデバイスのプラットフォーム。

linux-amd64linux-arm64linux-amd64-arm64
infraenumデフォルト: component-version

component-version は再利用可能な Greengrass コンポーネントインフラストラクチャを提供します。none はローカル開発のみをサポートします。

component-versionnone
iacenumデフォルト: inherit

IaC プロバイダー。インフラストラクチャが要求された場合にのみ解決されます。

inheritcdkterraform
languageenum

コンポーネントの言語。ホストがサポートする言語マーカーを正確に1つだけ持つ場合のみ省略可能。

typescriptpython
componentNamestring

レシピの ComponentName。デフォルトでは、ワークスペースの npm スコープとコンポーネント名から派生した逆ドメイン名。

componentVersionstringデフォルト: 1.0.0

レシピの ComponentVersion。CDK はデプロイ時に NEXT_* を解決します。Terraform は明示的なセマンティックバージョンが必要です。infra=none の場合、NEXT_* はそのまま書き込まれます。

publisherstring

レシピの ComponentPublisher。デフォルトではワークスペースの npm スコープ。

ipcbooleanデフォルト: false

Greengrass IPC クライアントを接続するかどうか。両言語ともデフォルトは false。

gdkConfigbooleanデフォルト: false

GDK CLI を手動で使用するための gdk-config.json を生成します。GDK は NEXT_PATCH をサポートしますが、NEXT_MINOR や NEXT_MAJOR はサポートしません。

preferInstallDependenciesbooleanデフォルト: true

ジェネレーター実行後に依存関係のインストールを優先するかどうか。

ジェネレーター出力

Section titled “ジェネレーター出力”
language = python
  • Directorygreengrass
    • Directorypulse
      • recipe.yaml コンポーネントレシピ
      • main.py コンポーネントエントリーポイント
  • Directorytests
    • Directorygreengrass
      • test_pulse.py パスでmain.pyをロードするユニットテスト

pulse-vendorターゲットは、uv pip install --only-binary :all:を使用して、選択されたデバイスプラットフォーム用にプロジェクトの依存関係をベンダリングします。platform: linux-amd64-arm64の場合、アーキテクチャごとに1回ベンダリングし、レシピはアーキテクチャごとに1つのマニフェストを保持します。

language = typescript
  • Directorygreengrass
    • Directorypulse
      • recipe.yaml コンポーネントレシピ
  • Directorysrc
    • Directorygreengrass
      • Directorypulse
        • main.ts コンポーネントエントリーポイント

プロジェクトのbundleターゲットは、パッケージング前にエントリーポイントをバンドルします。ipc: trueの場合、pulse-vendorターゲットは選択されたアーキテクチャ用のaws-crtネイティブアドオンもステージングします。

レシピ、エントリーポイント、およびPythonの場合はテストは、最初の実行から自分のものです。再実行しても書き換えられることはありません。ターゲット、メタデータ、依存関係宣言はフレームワーク管理であり、実行ごとに収束します。packages/common/scripts/src/greengrass/の下の共有パッケージングスクリプトは一度作成されます。そのディレクトリを削除してジェネレーターを再実行すると、更新されます。

ターゲットはケバブケースのコンポーネント名を使用します。

ターゲット目的
<component>-vendorPython依存関係、またはIPCが有効な場合はTypeScript CRTアドオンをベンダリング
<component>-artifactdist/<project-root>/greengrass/<component>/greengrass-build/の下に解決されたレシピとデプロイ可能なアーカイブを書き込み
<component>-deploy-localコアデバイス上でgreengrass-cliを通じてローカルデプロイメントを作成し、安定したコンポーネント状態を待機
<component>-logsコアデバイス上のコンポーネントログをテール

<component>-artifactはホストプロジェクトのbuildおよびassembleターゲットの依存関係であるため、通常のビルドでアーティファクトが生成されます。

インフラストラクチャ

Section titled “インフラストラクチャ”
infra = component-version

このジェネレーターは、選択した iac に基づいてインフラストラクチャをコードとして提供するため、関連する CDK コンストラクトまたは Terraform モジュールを含む packages/common にプロジェクトを作成します。

共通のインフラストラクチャコードプロジェクトは、次のように構成されています：

  • Directorypackages/common/constructs
    • Directorysrc
      • Directoryapp/ プロジェクト/ジェネレーター固有のインフラストラクチャ用のコンストラクト
        • …
      • Directorycore/ app 内のコンストラクトによって再利用される汎用コンストラクト
        • …
      • index.ts app からコンストラクトをエクスポートするエントリーポイント
    • project.json プロジェクトのビルドターゲットと設定

デフォルトのinfra: component-versionは、欠落している場合に以下のGreengrassコアファイルと、コンポーネントごとに1つのアプリラッパーを追加します。既存のコアファイルは保持されるため、ローカル編集は後の実行でも残ります。デバイス、シンググループ、またはデプロイメントは作成しません。

  • Directorypackages/common/constructs/src
    • Directorycore/greengrass
      • artifact-bucket.ts GreengrassArtifactBucket: grantReadToを持つ保持された、バージョン管理された、TLSのみのリポジトリ
      • component-version.ts GreengrassComponentVersion: アーティファクトをアップロードしてバージョンを公開
      • deployment.ts GreengrassDeployment: デプロイメント、オプションのシンググループ、およびaddComponent
      • next-version.ts NEXT_PATCH、NEXT_MINOR、NEXT_MAJORのデプロイ時リゾルバー
      • recipe.ts シンス時のレシピ読み取りとアーティファクトURI置換
    • Directoryapp/greengrass
      • pulse.ts Pulse、このコンポーネントのビルド出力に固定されたGreengrassComponentVersion

共有コンストラクトプロジェクトのbuildおよびassembleターゲットはホストプロジェクトに依存しているため、インフラストラクチャのビルドまたはデプロイは常に新しいアーティファクトを読み取ります。

アーキテクチャ

Section titled “アーキテクチャ”

コンポーネントバージョンは、ビルドされたアーティファクトを明示的に所有されたリポジトリに公開します。スタックまたはルートモジュールは、コアデバイスのトークン交換ロールに読み取りアクセスを付与し、1つ以上のデプロイメントにバージョンを追加します。デフォルトの読み取り付与は、ワークスペースのコンポーネント名前空間にスコープされています。ロールのデバイスがそれらのコンポーネントのサブセットのみを必要とする場合は、さらに絞り込んでください。

Loading the diagram…

infra = none

infra: noneは、レシピ、エントリーポイント、Pythonテスト、ターゲット、および共有スクリプトのみを作成します。インフラストラクチャプロジェクトや共有コンストラクトは作成または変更されません。後でinfra: component-versionで再実行してインフラストラクチャを追加できます。既にインフラストラクチャを所有しているコンポーネントをnoneに戻すことはできません。

ローカルでのビルドと実行

Section titled “ローカルでのビルドと実行”

開発マシンでアーティファクトをビルドします。

Terminal window
pnpm nx run <project>:pulse-artifact

dist/<project-root>/greengrass/pulse/greengrass-build/の下の出力には、解決されたレシピを含むrecipes/と、アーカイブを含むartifacts/<ComponentName>/<ComponentVersion>/があります。Pythonコンポーネントは、マニフェストごとに1つのアーカイブをビルドし、両方のアーキテクチャをターゲットとする場合は<component>-<architecture>.zipという名前になります。TypeScriptコンポーネントは、すべてのマニフェストが共有する1つのアーカイブをビルドします。ipc: trueの場合、各アーキテクチャ用のaws-crtアドオンを保持し、各マニフェストのSetenvが独自のものを選択します。レシピのアーティファクトURIのBUCKET_NAME、COMPONENT_NAME、COMPONENT_VERSIONプレースホルダーは公開時に置換され、アーカイブのベース名はRunステップが解凍するものと同じである必要があります。

次の2つのターゲットは、通常のワークステーションではなく、クラシックGreengrassヌクレウスとgreengrass-cliがインストールされたマシンで実行されます。

Terminal window
pnpm nx run <project>:pulse-deploy-local
pnpm nx run <project>:pulse-logs

GREENGRASS_ROOTはデフォルトで/greengrass/v2です。pulse-deploy-localはローカルデプロイメントを送信し、コンポーネントのライフサイクル状態をポーリングし、3回のチェックでRUNNINGまたはFINISHEDのままでない限り、ゼロ以外で終了します。ローカルデプロイメントは、デバイス上でそのバージョンを固定し、異なるバージョンの後のクラウドデプロイメントと競合します。ローカルおよびクラウドデプロイメントを参照してください。

infra = component-version

デプロイ

Section titled “デプロイ”

デプロイメント構成は、インフラストラクチャプロジェクトに存在します。通常のフローは、1つのリポジトリ、1つの読み取り付与、コンポーネントごとに1つのアプリラッパー、ターゲットごとに1つのデプロイメントです。既存のシンググループまたはシングに1つのデプロイメントを使用し、そのtargetArnを設定します。別のターゲット用に別のデプロイメントを作成します。

ワークスペースにCDKアプリケーションがない場合は作成します。

このジェネレーターを実行@aws/nx-plugin:ts#infra

pnpm nx g @aws/nx-plugin:ts#infra --name=infra
コマンドを組み立てる5

必須

変更されるファイルを確認するためにドライランを実行することもできます

トークン交換ロールとターゲットシンググループは、アカウントに既に存在します。ロールはコアデバイスが引き受けるものであり、グループはそれらが登録されている場所です。スタックは、CloudFormationパラメーターを通じて両方をインポートします。

packages/infra/src/stacks/application-stack.ts
import {
  GreengrassArtifactBucket,
  GreengrassDeployment,
  Pulse,
} from '@my-scope/common-constructs';
import { CfnParameter, Stack, type StackProps } from 'aws-cdk-lib';
import { Role } from 'aws-cdk-lib/aws-iam';
import type { Construct } from 'constructs';


export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);


    const tokenExchangeRoleArn = new CfnParameter(
      this,
      'TokenExchangeRoleArn',
      { type: 'String' },
    );
    const thingGroupArn = new CfnParameter(this, 'ThingGroupArn', {
      type: 'String',
    });


    // One explicitly owned repository, and the grant the devices need.
    const artifacts = new GreengrassArtifactBucket(this, 'Artifacts');
    const tokenExchangeRole = Role.fromRoleArn(
      this,
      'TokenExchangeRole',
      tokenExchangeRoleArn.valueAsString,
    );
    artifacts.grantReadTo(tokenExchangeRole);


    // The generated wrapper takes the repository construct itself.
    const pulse = new Pulse(this, 'Pulse', { bucket: artifacts });


    // addComponent records the resolved version and orders the deployment
    // resource after the component version resource.
    const fleet = new GreengrassDeployment(this, 'Fleet', {
      targetArn: thingGroupArn.valueAsString,
    });
    fleet.addComponent(pulse);
  }
}

プロジェクト参照を同期し、アカウントとリージョンを一度ブートストラップしてから、デプロイします。deployターゲットは、^assembleの後にインフラストラクチャプロジェクトでcdk deploy --require-approval=neverを実行し、最初にコンポーネントアーティファクトを再ビルドします。生成されたmain.tsは、すべてのスタックをプロジェクトにちなんで名付けられたステージに配置します。@my-scope/infraの場合はmy-scope-infra-sandboxなので、cdk deployにはそのステージのセレクターが必要です。packages/infra/src/main.tsからステージ名を取得し、パラメーター値とともに--の後に/**を付けて渡します。

Terminal window
AWS_PROFILE=<profile> AWS_REGION=<region> pnpm nx sync
pnpm nx run @my-scope/infra:bootstrap
pnpm nx run @my-scope/infra:deploy -- 'my-scope-infra-sandbox/**' --parameters TokenExchangeRoleArn=<role-arn> --parameters ThingGroupArn=<thing-group-arn>

deployは完全な安定化を待ち、置換更新を受け入れます。deploy-sandboxはエクスプレスモードを使用し、--rollbackを渡さない限り置換更新を拒否します。定期的な改訂にはdeployを使用するか、deploy-sandboxを使用する場合は--rollbackを渡してください。

fleet.addComponent(pulse)は必須であり、装飾的なものではありません。固定のComponentVersionでは、デプロイメントのコンポーネントマップはリテラル文字列を保持するため、CloudFormationはデプロイメントとコンポーネントバージョンの間に依存関係を認識せず、それらを並行して作成します。その後、IoTジョブはバージョンが存在する前にデバイスに到達し、FAILED_NO_STATE_CHANGEで失敗します。NEXT_PATCHでは、マップはコンポーネントバージョンリソースのComponentVersion属性を保持し、生のNEXT_*文字列がデプロイメントに到達すると、addComponentを指定したメッセージでシンスが失敗します。

1つのフリートに2つのコンポーネント

Section titled “1つのフリートに2つのコンポーネント”

同じまたは別のプロジェクトに2番目のコンポーネントを生成し、両方を1つのデプロイメントに追加します。オーバーライドは、そのコンポーネントのエントリの名前付きトップレベルフィールドを置き換えます。バージョンは常にコンストラクトから取得されます。

const pulse = new Pulse(this, 'Pulse', { bucket: artifacts });
const uploader = new Uploader(this, 'Uploader', { bucket: artifacts });


const cameras = new GreengrassDeployment(this, 'Cameras', {
  thingGroupName: 'cameras',
});
cameras.addComponent(pulse);
cameras.addComponent(uploader, {
  configurationUpdate: { merge: { uploadIntervalSeconds: 60 } },
});

thingGroupNameは新しいAWS::IoT::ThingGroupを作成します。デバイスを登録しません。デバイスは、プロビジョニングプロセスを通じてグループに参加します。既に存在するグループまたはシングには、targetArnまたはthingNameを使用してください。

2つのフリートに1つのコンポーネント

Section titled “2つのフリートに1つのコンポーネント”

同じコンストラクトを2つのデプロイメントに登録します。各デプロイメントは独自の設定を保持します。

new GreengrassDeployment(this, 'WestFleet', {
  thingGroupName: 'west-fleet',
}).addComponent(pulse);


new GreengrassDeployment(this, 'EastFleet', {
  thingGroupName: 'east-fleet',
}).addComponent(pulse, {
  configurationUpdate: { merge: { sampleIntervalSeconds: 60 } },
});

同じコンストラクトを1つのデプロイメントに2回追加することは、2回目の呼び出しがオーバーライドを提供しない限り、何もしません。オーバーライドはエントリを更新します。同じコンポーネント名で異なるコンストラクトを1つのデプロイメントに追加すると、構築時に失敗します。

パブリックコンポーネントと生のエントリ

Section titled “パブリックコンポーネントと生のエントリ”

このワークスペースでビルドしなかったコンポーネントは、componentsマップに入ります。公開されたパブリックコンポーネントは、既に存在するため依存関係を必要としません。同じスタックで作成されたバージョンの生のエントリ（例：手書きのCfnComponentVersion）には、addComponentから取得する順序エッジが必要です。

import { CfnComponentVersion } from 'aws-cdk-lib/aws-greengrassv2';


const fleet = new GreengrassDeployment(this, 'Fleet', {
  targetArn: thingGroupArn.valueAsString,
  components: {
    // Published by AWS; pick a version from
    // `aws greengrassv2 list-component-versions`.
    'aws.greengrass.LogManager': {
      componentVersion: '2.3.8',
      configurationUpdate: {
        merge: {
          logsUploaderConfiguration: {
            systemLogsConfiguration: { uploadToCloudWatch: 'true' },
          },
        },
      },
    },
    // Created in this stack, so the deployment must wait for it.
    'com.example.Handwritten': { componentVersion: '1.2.0' },
  },
});
fleet.addComponent(pulse);


const handwritten = new CfnComponentVersion(this, 'Handwritten', {
  inlineRecipe: handwrittenRecipe,
});
fleet.deployment.node.addDependency(handwritten);

configurationUpdate.mergeはここではプレーンオブジェクトです。コンストラクトは、CloudFormationが期待するJSON文字列にシリアル化します。

既存のリポジトリのインポート

Section titled “既存のリポジトリのインポート”

1つのスタックがリポジトリを所有します。他のすべてのスタックは名前でインポートし、所有スタックに独自の付与を追加するか、トークン交換ロール自体に同等のs3:GetObjectポリシーをアタッチします。

const artifacts = new GreengrassArtifactBucket(this, 'Artifacts', {
  existingBucketName: 'central-greengrass-artifacts',
});
const pulse = new Pulse(this, 'Pulse', { bucket: artifacts });

インポートされたバケットは、独自の暗号化、バージョン管理、アクセス設定を保持します。リゾルバーは、NEXT_*バージョンのコンテンツIDにバケット名を含めるため、コンポーネントを別のリポジトリに移動すると、変更されていないバイトに対して新しいバージョンが割り当てられます。

デバイスでの確認

Section titled “デバイスでの確認”

完了したスタック更新または適用は、デプロイメントリソースが存在することを証明します。デプロイメントとそのIoTジョブの両方がSUCCEEDEDを報告する一方で、デバイス上のコンポーネントがBROKENである可能性があります。すべてのデプロイメント後にデバイスとコンポーネントの状態を確認してください。

Terminal window
aws --profile <profile> --region <region> greengrassv2 get-core-device \
  --core-device-thing-name <thing-name> --query status
aws --profile <profile> --region <region> greengrassv2 list-installed-components \
  --core-device-thing-name <thing-name>

デバイスが壊れた状態を報告する場合は、<component>-logsを使用してプロセスログを検査してください。

レシピとIPC

Section titled “レシピとIPC”

デフォルトのipc: falseでは、main.pyは30秒ごとに1行をログに記録し、レシピにはIPCアクセス制御がありません。ipc: trueでは、GreengrassCoreIPCClientV2を通じて30秒ごとにコンポーネント自身のローカルトピックにハートビートを公開します。

greengrass/pulse/main.py
client.publish_to_topic(
    topic=TOPIC,
    publish_message=PublishMessage(json_message=JsonMessage(message={"sequence": sequence})),
)

レシピは、aws.greengrass.ipc.pubsubの下で<ComponentName>/heartbeatに対してaws.greengrass#PublishToTopicを付与します。ローカルpub/subは、AWS IoT Coreではなく、同じコアデバイス上の他のコンポーネントに到達します。AWS IoT Coreに公開するには、publish_to_iot_coreを呼び出し、レシピのaws.greengrass.ipc.mqttproxyの下でaws.greengrass#PublishToIoTCoreを付与し、デバイスのIoTポリシーで正確なトピックに対してiot:Publishを付与します。

レシピのアクセス制御は、デバイス上のヌクレウスによって強制されます。SDK単独に依存しても何も承認されないため、コンポーネントが成長するにつれてoperationsとresourcesを拡大してください。

生成されたレシピは、クラシックaws.greengrass.Nucleusをターゲットとしています。Nucleus Liteは、IPC操作のサブセットを実装し、プラグインコンポーネントを実行せず、v2.15でのみコンテナサポートを獲得しました。フリートが実行するヌクレウスに対してレシピを確認してください。ジェネレーターはヌクレウスの機能を検出しません。

Ubuntu 25.10以降では、sudo-rsがIPC環境が失われるため、Greengrass Nucleus 2.18.3でIPCコンポーネントの起動を妨げる可能性があります。ジェネレーターは、ホストのsudoセキュリティ設定を変更しません。IPCが必要な場合は、クラシックsudo動作を提供するデバイスセットアップを使用してください。

自動バージョニング

Section titled “自動バージョニング”

CDKデプロイメントの場合、recipe.yamlのComponentVersionをNEXT_PATCH、NEXT_MINOR、またはNEXT_MAJORに設定して、プラグインのリゾルバーにアカウントとリージョンで既に公開されている最高の厳密なセマンティックバージョンからバージョンを割り当てるように依頼します。

センチネル最高公開1.4.2が次になるまだ何も公開されていない
NEXT_PATCH1.4.31.0.0
NEXT_MINOR1.5.01.0.0
NEXT_MAJOR2.0.01.0.0

最初のバージョンは1.0.0です。リゾルバーは、コンテンツタグが一致し、バージョンがデプロイ可能な場合、最高公開バージョンを再利用します。それ以外の場合は、センチネルによって選択された次のバージョンを公開します。タグは、バージョン行のないレシピ、アーティファクトバイト、およびアーティファクトバケット名をカバーします。したがって、変更されていないコンテンツはバージョンを再利用し、コンテンツまたはバケットを変更すると新しいバージョンが公開されます。ジェネレーターはrecipe.yamlを書き換えることはありません。

NEXT_*はNxプラグインの規約であり、Greengrassバージョンではありません。CDKはデプロイメント中にセンチネルを解決し、<project>:pulse-deploy-localはデバイスで利用可能なバージョンに対して解決します。GDKはgdk-config.jsonの設定としてNEXT_PATCHを使用し、レシピフィールドとしては使用せず、NEXT_MINORまたはNEXT_MAJORをサポートしていません。プラグインはGDKを呼び出しません。

Terraformには明示的なセマンティックバージョンが必要です。Greengrassバージョンは不変であるため、変更されたアーティファクトごとに新しいComponentVersionが必要です。TerraformはNEXT_*を解決しません。

CDKリゾルバーは、生成されたLambda実行ロールの下でCloudFormationデプロイメント中に実行され、スタックのコンポーネント名にスコープされます。同じコンポーネントに対して同時公開を実行しないでください。デプロイメントが同じ次のバージョンを選択し、1つの公開が失敗する可能性があります。

アーティファクトストレージと保持

Section titled “アーティファクトストレージと保持”

アカウントとリージョンごとに1つのアーティファクトリポジトリを使用し、1つのスタックまたはルートモジュールが所有します。CDKのexistingBucketNameまたはTerraformのexisting_bucket_nameを使用して、他の場所でインポートします。生成されたバケットは、バージョン管理され、SSE-S3で暗号化され、プライベートであり、TLSを必要とします。GreengrassアーティファクトはCDKアセットではありません。cdk gcは、コンポーネントバージョンがまだ必要とするアセットを削除できます。

両方のIaCパスは同じS3オブジェクトキーレイアウトを使用します。<ComponentName>/<first 32 hex characters of sha256>/<file>。ダイジェストは、ソートされたアーティファクト名とその完全なSHA-256ハッシュをハッシュし、1つまたは複数のアーティファクトに同じ式を使用します。キープレフィックスのみが短縮されます。アーティファクトダイジェストと自動バージョンIDは完全なハッシュを保持します。CDKのバケットデプロイメントタグは、プレフィックスを102文字に制限し、コンポーネント名に68文字を残します。ジェネレーターは、CDKインフラストラクチャが選択されたときにその制限をチェックし、シンセシスはレシピへの編集をチェックします。Terraformのオブジェクトアップロードには、このCDK制限はありません。

デプロイメントまたはロールバックがコンポーネントバージョンを必要とする可能性がある間、公開されたアーティファクトを利用可能に保ちます。CDKは、デフォルトで置き換えられたコンポーネントバージョンとそのアップロードを保持します。Terraformは、置き換えられたバージョンと置き換え前のオブジェクトキーを削除します。複数のグループで使用されるバージョンをバンプする前に、段階的ロールアウトと保持されたバージョンを参照してください。レジストリバージョンを削除しても、デバイスで既に実行されているコンポーネントはアンインストールされません。Terraformのリポジトリはprevent_destroyを設定します。そのアーティファクトが不要になった後の意図的な解体のためにのみ、そのリテラルライフサイクル設定を削除してください。

デフォルトのトークン交換ロール付与は、ワークスペースのコンポーネント名前空間でs3:GetObjectを許可します。より狭い付与の場合は、CDKでkeyPrefixを、Terraformでtoken_exchange_key_prefixを設定します。インポートされたバケットは独自のポリシーを保持するため、バケットまたはロールが所有されている場所で付与を管理します。

デプロイメントリビジョン

Section titled “デプロイメントリビジョン”

コンポーネントバージョンまたはデプロイメント設定を変更すると、デプロイメントリソースが置き換えられます。CloudFormationは、1つのスタック操作で最大10個のデプロイメントリソースを追加または削除できます。大規模なロールアウトをバッチに分割します。置換には通常のdeployターゲットを使用してください。deploy-sandboxはCloudFormationエクスプレスモードを使用し、置換更新には--rollbackが必要です。

デプロイメントリソースを削除すると、クラウド管理状態が削除されますが、デバイスからコンポーネントはアンインストールされません。まず、コンポーネントを省略したリビジョンをデプロイし、list-installed-componentsから消えるのを待ってから、そのIaCリソースを削除してください。

ローカルおよびクラウドデプロイメント

Section titled “ローカルおよびクラウドデプロイメント”

<component>-deploy-localからのローカルデプロイメントは、そのデバイス上でコンポーネントバージョンを固定します。異なるバージョンを要求するクラウドデプロイメントは、ピンを満たすことができません。クラウドからそのデバイスを更新する前に、ローカルデプロイメントを削除してください。

Terminal window
sudo /greengrass/v2/bin/greengrass-cli deployment create --remove com.example.Pulse

開発デバイスにはローカルデプロイメントを、フリートターゲットにはクラウドデプロイメントを使用してください。

トラブルシューティングとサービス制限

Section titled “トラブルシューティングとサービス制限”

クラウドデプロイメント後、Greengrassデプロイメントステータスとコンポーネントのデバイス状態の両方を確認してください。

Terminal window
aws --profile <profile> --region <region> greengrassv2 get-core-device \
  --core-device-thing-name <thing-name> --query status
aws --profile <profile> --region <region> greengrassv2 list-installed-components \
  --core-device-thing-name <thing-name>

ジョブがSUCCEEDEDを報告する一方で、コンポーネントがBROKENである可能性があります。<component>-logsを使用してプロセスログを検査してください。Ubuntu 25.10以降のIPCコンポーネントも、Nucleus 2.18.3でsudo-rsの下で失敗する可能性があります。ジェネレーターは、ホストのセキュリティ設定をそのままにします。

Greengrassは、リージョンごとに1つのコンポーネントを5,000バージョンに制限し、CreateComponentVersionをリージョンごとに1秒あたり1リクエストに制限します。レシピは16 KBに制限され、デプロイメントドキュメントはシンググループの場合は31 KB、単一のシングの場合は7 KBに制限されます。ハートビートとして新しいバージョンを使用することを避け、大規模なデプロイメントを小さなバッチに分割してください。