Deploy to Greengrass

This page covers deploying a EdgeCommons component to AWS IoT Greengrass v2, where it runs on the GREENGRASS platform and talks to the Nucleus over Greengrass IPC (the IPC transport). You build and package the component with the GDK (Greengrass Development Kit), then either deploy it locally with greengrass-cli or push it to a fleet from the cloud.

Every component the edgecommons CLI scaffolds already ships the two files the GDK needs — gdk-config.json (build + publish settings) and recipe.yaml (the component recipe) — so you rarely write either by hand.

Developing first?

For local iteration you do not need a Greengrass core at all — run on the HOST platform against a local MQTT broker. See the Quickstart and Platforms and transports.

Prerequisites

• A scaffolded component (edgecommons component new with GREENGRASS among its target platforms — the default). See the Quickstart.
• The GDK CLI (gdk) installed and on your PATH, plus AWS credentials with permission to upload artifacts to S3 and register component versions. Confirm with edgecommons doctor --platforms GREENGRASS, which exits non-zero when a required tool is missing.
• An S3 bucket for published artifacts. Scaffold with -b/--bucket to set it up front; without it, gdk-config.json carries the sentinel edgecommons-set-artifact-bucket in publish.bucket (and publish.region defaults to us-east-1) — edgecommons component validate errors on the sentinel until you replace it with a real bucket you own.
• A Greengrass v2 core device running the Nucleus, plus the Greengrass CLI component (greengrass-cli) installed on it if you want to deploy locally.

How a component runs under Greengrass

On the GREENGRASS platform the runtime resolves two defaults from the platform profile, so the launch command is short:

• Transport defaults to IPC — you do not pass --transport. (IPC is valid only on GREENGRASS; selecting it on another platform fails fast.)
• Config source defaults to GG_CONFIG — the component reads its configuration from the Greengrass deployment rather than a local file.

The generated recipe.yaml wires this into the component’s Run lifecycle for you. The exact launch line differs per language (and the artifact layout differs with it):

Java

The recipe sets the CONFIG environment variable from the deployment configuration and launches the shaded JAR on the GREENGRASS platform. Config source is left to the profile default (GG_CONFIG), so no -c flag is passed:

# recipe.yaml -> Manifests[0].Lifecycle.Run (tokens resolved to example values)
java -cp {artifacts:path}/my-component-1.0.0.jar com.example.MyComponent --platform GREENGRASS
# with Setenv CONFIG: "{configuration:/ComponentConfig}"

The jar name is the kebab crate/artifact name (JARNAME, the Maven artifactId/finalName convention); the class passed to -cp stays the full PascalCase reverse-DNS name.

Python

The recipe activates the per-component venv (created in the install lifecycle) and runs main.py on the GREENGRASS platform, relying on the GG_CONFIG profile default (no -c flag):

# recipe.yaml -> Manifests[0].Lifecycle.Run (tokens resolved to example values)
python3 -u {artifacts:decompressedPath}/MyComponent/main.py --platform GREENGRASS

Rust

The recipe chmod +x’s the binary in the Install lifecycle, then runs it. The Rust recipe passes -c GG_CONFIG explicitly (the result is identical to relying on the profile default):

# recipe.yaml -> Manifests[0].Lifecycle.Run (tokens resolved to example values)
{artifacts:path}/my-component --platform GREENGRASS -c GG_CONFIG

The binary name is the kebab BINNAME — the same name as the Cargo crate/[[bin]].

TypeScript

The recipe runs the prebuilt JS bundle (no on-device install step). Like Rust, it passes -c GG_CONFIG explicitly:

# recipe.yaml -> Manifests[0].Lifecycle.Run (tokens resolved to example values)
node {artifacts:decompressedPath}/MyComponent/dist/main.js --platform GREENGRASS -c GG_CONFIG

Note

The Java and Python recipes pass only --platform GREENGRASS and let the platform profile supply the GG_CONFIG config source; the Rust and TypeScript recipes pass -c GG_CONFIG as well. Both forms resolve to the same thing.

Build and publish

edgecommons component package builds the Greengrass artifacts, and --publish uploads them to your S3 bucket and registers a new component version in your account. It drives the GDK for you — gdk component build, then gdk component publish — so the commands are the same for every language. Run them from the generated component directory:

Linux

cd my-component
edgecommons component package --platforms GREENGRASS
edgecommons component package --platforms GREENGRASS --publish

Windows

cd my-component
edgecommons component package --platforms GREENGRASS
edgecommons component package --platforms GREENGRASS --publish

With no --platforms, package infers the platforms from what the project ships — a recipe.yaml means GREENGRASS. Invoking gdk component build / gdk component publish directly does the same thing; the rest of this page names the gdk steps where the distinction matters.

Auto-versioning

gdk-config.json sets the component version to NEXT_PATCH, so each publish registers the next patch version above whatever is already in your account. To pin a concrete version — which edgecommons component release requires, and which any rollback target needs — run edgecommons component version --to <x.y.z>.

Per-language packaging notes

What gdk component build actually does — and the artifact it produces — is driven by the build_system in gdk-config.json:

Java

build_system: "maven" — the GDK runs Maven to produce a shaded, self-contained JAR (target/my-component-1.0.0.jar, named from the kebab Maven artifactId). The recipe’s Manifests.Platform.os is all. The recipe also declares a HARD dependency on the Token Exchange Service (TES) so the component can obtain AWS credentials on-device.

# gdk-config.json -> component.<name>.build.build_system = "maven"
gdk component build

Streaming + native access

If your component uses the telemetry-streaming subsystem, the JVM needs --enable-native-access=ALL-UNNAMED for the FFM/Panama binding to the native streaming core. The shipped recipe’s Run script does not include this flag, so add it to the recipe’s java command before publishing a streaming component.

Python

build_system: "zip" — the GDK produces a ZIP artifact (Unarchive: ZIP). The recipe’s install lifecycle creates a per-component venv under the work dir and pip installs requirements.txt. Manifests.Platform.os is all, and the recipe declares a HARD TES dependency.

# gdk-config.json -> component.<name>.build.build_system = "zip"
gdk component build

Bundled wheel

The shipped recipe’s install step also pip installs a hard-coded wheel, greengrass_commons-0.0.10038883-py3-none-any.whl, whose pinned version may not match the edgecommons line in requirements.txt. On-device install fails unless that exact wheel is bundled into the ZIP. Prefer resolving the library through requirements.txt.

Rust

build_system: "custom" → custom_build_command: ["bash", "build.sh"]. build.sh compiles the release binary with the greengrass cargo feature (Greengrass IPC). The recipe’s Manifests.Platform.os is linux and its Install lifecycle chmod +x’s the binary.

gdk component build
# The greengrass feature compiles a C-FFI SDK and only builds on Linux (needs libclang).
# Build on a Linux host/WSL, or cross-compile:
EDGECOMMONS_TARGET=x86_64-unknown-linux-gnu gdk component build

TypeScript

build_system: "custom" → custom_build_command: ["bash", "build.sh"]. build.sh runs npm install + npm run build (tsc) and stages a ZIP bundling dist/ + node_modules/ + package.json, so there is no on-device install step. The recipe’s Manifests.Platform.os is linux.

# gdk-config.json -> component.<name>.build.build_system = "custom" (bash build.sh)
gdk component build

Note

The Java and Python recipes declare a HARD aws.greengrass.TokenExchangeService dependency; the Rust and TypeScript recipes do not. If your Rust/TS component calls AWS APIs on-device (for example CloudWatch metrics or Secrets Manager sync), add that dependency to its recipe.yaml.

What the generated recipe declares

The scaffolded recipe.yaml is a complete Greengrass v2 component recipe. The parts you are most likely to touch:

• ComponentConfiguration.DefaultConfiguration.ComponentConfig — the component’s default config (logging, heartbeat, metricEmission, tags, and the component instances block). This is the same schema the GG_CONFIG source reads; override any of it from a deployment.
• accessControl — IPC authorization policies the component needs: aws.greengrass.ipc.pubsub (local pub/sub), aws.greengrass.ipc.mqttproxy (publish/subscribe to IoT Core), and aws.greengrass.ShadowManager (thing shadows). The defaults grant *; tighten the resources to the topics/shadows your component actually uses.
• Manifests — the artifact URI (rewritten by gdk component publish) and the Run lifecycle shown above. os is all for Java/Python and linux for Rust/TypeScript.

gdk-config.json holds the build system, the publish bucket/region, and the NEXT_PATCH version. Edit the recipe and re-run gdk component build to pick up changes.

Deploy locally with greengrass-cli

For a development core device you can deploy straight from the device without going through the cloud, using the Greengrass CLI. After building, copy the recipe and artifact onto the core, then create a local deployment that merges the component (<Comp>=<ver> names the component and version):

Linux

# Run on the core device. Point --recipeDir / --artifactDir at the recipe and the built artifact.
greengrass-cli deployment create \
  --recipeDir ./recipes \
  --artifactDir ./artifacts \
  --merge "com.example.MyComponent=1.0.0"

# Tear the component down again:
greengrass-cli deployment create --remove "com.example.MyComponent"

Windows

# Run on the core device (greengrass-cli typically lives under C:\greengrass\v2\bin).
greengrass-cli deployment create `
  --recipeDir .\recipes `
  --artifactDir .\artifacts `
  --merge "com.example.MyComponent=1.0.0"

# Tear the component down again:
greengrass-cli deployment create --remove "com.example.MyComponent"

Note

greengrass-cli is usually invoked by its full path (for example /greengrass/v2/bin/greengrass-cli) and requires the Greengrass CLI component installed on the core. The artifact filename in --artifactDir must match the artifact URI in your recipe.yaml.

Deploy to devices from the cloud

Once a version is published, deploy it to a thing with the AWS CLI. Give the deployment the thing’s ARN as its target and name the component version you published:

Linux

aws greengrassv2 create-deployment \
  --target-arn arn:aws:iot:us-east-1:123456789012:thing/edge-device-1 \
  --deployment-name my-component-deployment \
  --components '{"com.example.MyComponent":{"componentVersion":"1.0.0"}}'

Windows

aws greengrassv2 create-deployment `
  --target-arn arn:aws:iot:us-east-1:123456789012:thing/edge-device-1 `
  --deployment-name my-component-deployment `
  --components '{\"com.example.MyComponent\":{\"componentVersion\":\"1.0.0\"}}'

Concrete version required

A deployment names a real component version — NEXT_PATCH is a publish-time idiom, not something you can deploy or roll back to. Pin one with edgecommons component version --to <x.y.z> before you publish the version you intend to deploy.

Verify the deployment

• On the core device, check component status with the Greengrass CLI: greengrass-cli component list (and watch the Nucleus logs under /greengrass/v2/logs/).
• Subscribe to ecv1/+/+/state (add ecv1/+/+/+/state for instance-scoped publishers) to confirm the component is alive and publishing its state keepalive — over IPC these surface on the local pub/sub bus (and on IoT Core when heartbeat.destination is northbound). The concrete topic is ecv1/{device}/{component}/state, where the device is the resolved thing name.

Next steps

Messaging guidePublish, subscribe, and request/reply across IPC and MQTT.

Configuration guideConfig sources, template variables, hot reload, and validation.

Platforms and transportsHow --platform and --transport resolve, and their defaults.

Scaffolding CLIedgecommons component new, validate, version, upgrade, package, and release.