Greengrass Package Management

Package Management

Create, version, deploy, and manage software components on your Greengrass devices. Package Management is how you push application logic from the cloud to the edge — including custom telemetry collectors, ML models, protocol translators, and business logic.

How Package Management works

The deployment pipeline follows four steps:

1. Create Component — Upload your code (artifact zip) and describe it (recipe YAML / JSON).

2. Create Package — Bundle one or more components together with a template association.

3. Deploy — Push the package to target devices. Greengrass Nucleus downloads and installs the components.

4. Monitor — Track deployment status (Pending → Successful / Failed) and verify telemetry.

Key Principle: By default, the device does not expose a shell or management API to the internet

. All code delivery happens through secure, authenticated Greengrass deployments — the device pulls components from a trusted source, not the other way around.

Understanding Components

A component consists of two parts:

1. Artifact — The actual code and files (packaged as a .zip):

Python scripts (.py files)

Configuration files

ML models, data files, or binaries

Any supporting files needed at runtime

2. Recipe — A YAML or JSON file describing the component:

Identity: Component name and version (e.g., com.mycompany.sensor-reader 1.0.0)

Configuration: Default parameters the component uses (intervals, thresholds, etc.)

Lifecycle: Install steps (pip install), Run command (python3 main.py), Shutdown behavior

Permissions: IPC access control (which topics the component can publish / subscribe to)

Artifacts: Reference to the zip file location

Create a Component

Steps:

1. Navigate to Devices → Greengrass Device → Package (bottom tab).

2.Open the Components section. or Click the Components tab.

3. Click Create Component.

4. Upload the Recipe file (.json or .yaml format).

5. The artifact file is referenced inside the recipe — it should be uploaded as the component zip.

6. Click Save.

Result: The component appears in the Components list with its name, version, artifact count, and last update date.

Component Types Available:

Type	Source	Description
Custom Components	You create	Your application code — sensors, logic, ML inference
Public Components	AWS provides	Pre-built AWS components (e.g., aws.greengrass.Cli, Log Manager)
/IOTCONNECT™ Default	Auto-included	The SDK bridge component (com.iotconnect.sdk2) that connects IPC to cloud

Create a Package

A Package groups components together for deployment. Think of it as a “release bundle.”

Steps:

1. In the Package section, click Create Package.

2. Fill in the fields:

Field	Description	Example
Name	Package identifier	Factory Monitoring v1.0
Template	Which device template this targets	Smart Factory Sensor
Custom Components	Your components to include	com.mycompany.sensor-reader
Public Components	AWS components to include (optional)	aws.greengrass.Cli

3. The /IOTCONNECT™ Default Component (SDK bridge) is automatically included — it handles cloud communication.

4. Click Save.

Result: Package is ready for deployment to any device using the selected template.

Deploy to Devices

Deployment pushes the package to one or more physical devices.

Steps:

1. Go to the Deployments section.

2. Click Create Deployment.

3. Fill in:

Field	Description
Deployment Name	Descriptive name (e.g., “v1.0 rollout – Building A”)
Package	Select the package to deploy
Components	Choose which components from the package (checkboxes)
Configuration	Override default config values for this deployment (optional)
Target Type	Single device, Device Group, or All
Target	Select specific device(s)

4. Click Deploy.

What happens on the device:

Greengrass Nucleus receives the deployment instruction via MQTT

Downloads component artifacts from the secure store

Executes the Install lifecycle step (installs dependencies)

Starts the Run lifecycle step (launches your application)

Reports status back to the cloud (success or failure)

Deployment Status

Track deployments in the Deployments list:

Status	Meaning	Action
Pending	Deployment sent, device hasn’t processed yet	Wait — device may be offline or processing
In Progress	Device is downloading and installing components	Wait — typically 1-3 minutes
Successful	All components installed and running	Check Live Data for telemetry
Failed	Installation or startup failed	Check device logs, fix recipe / artifact, redeploy

On failure: The device automatically rolls back to its previous component state. No partial deployments remain on the device.

Versioning and Updates

Updating a deployed Component:

Create a new version of the component with an incremented version number (e.g., 1.0.0 → 1.1.0)

Upload the updated artifact and recipe

Update the package to reference the new component version

Create a new deployment targeting the devices

Versioning rules:

Never reuse a version number. Always increment when making any change.

Use semantic versioning: MAJOR.MINOR.PATCH (e.g., 1.2.3)

MAJOR: Breaking changes | MINOR: New features | PATCH: Bug fixes

Rollback: To rollback, create a new deployment with the previous package version. The device will replace current components with the older version.

ⓘ BEST PRACTICE

Development workflow: Use a PC / VM with Nucleus Classic and deploy the aws.greengrass.Cli public component. This enables local-deploy.sh for instant testing without uploading to /IOTCONNECT™ each time. Only upload to the portal when you’re ready to deploy to production devices.